AIX MCP Server

MCP (Model Context Protocol) server for the AIX Brain Decision Engine. Exposes decision-only tools for AI agents — no gateway behavior, no prompt proxying.

Setup

# From repo root
cd packages/aix-mcp

# Set environment
export AIX_API_URL=http://localhost:5000   # or https://aix.cloudverse.ai
export AIX_TOKEN=your_api_key_here         # AIX API key

Running

# Start MCP server (stdio transport)
npx tsx src/index.ts

MCP Tools

brain.decide

Request a routing decision from the AIX Brain Decision Engine.

Input:

{
  "executionClass": "conversation",
  "priority": "balanced",
  "allowSubstitution": true,
  "constraints": {
    "maxCostUsd": 0.05,
    "maxLatencyMs": 3000,
    "minQsr": 0.9
  },
  "tokenEstimates": {
    "inputTokens": 1000,
    "outputTokens": 500
  }
}

Output:

{
  "decision_id": "dec_abc123",
  "decision_status": "ok",
  "provider": "openai",
  "model_name": "gpt-4o",
  "model_class": "premium",
  "confidence": 0.95,
  "data_used": "org",
  "explanation": "Selected based on quality-optimized scoring",
  "trace_summary": {
    "alternatives_count": 3,
    "score_breakdown": { "cost": 0.3, "latency": 0.2, "qsr": 0.4, "total": 0.9 },
    "selection_mode": "brain"
  }
}

brain.explainDecision

Get explanation and trace for a past decision.

Input:

{
  "decision_id": "dec_abc123"
}

policy.validate

Validate whether a decision would be allowed under current policy without executing it.

Input:

{
  "executionClass": "conversation",
  "priority": "cost",
  "constraints": {
    "maxCostUsd": 0.01
  }
}

Output:

{
  "allowed": true,
  "reasons": ["Allowed providers: openai, anthropic"],
  "effective_constraints": {
    "max_cost_usd": 0.01,
    "priority": "cost"
  },
  "policy_source": "org"
}

catalog.status

Get catalog status and coverage.

Output:

{
  "discovered_model_count": 94,
  "routable_model_count": 12,
  "defaults_count": 8,
  "activation_gates": {
    "has_pricing_coverage": true,
    "has_capability_rows": true,
    "execution_classes_total": 33,
    "execution_classes_with_coverage": 6
  }
}

Claude Desktop Configuration

Add to your Claude Desktop MCP config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aix-brain": {
      "command": "npx",
      "args": ["tsx", "/path/to/packages/aix-mcp/src/index.ts"],
      "env": {
        "AIX_API_URL": "http://localhost:5000",
        "AIX_TOKEN": "your_api_key"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AIX_API_URL | No | http://localhost:5000 | AIX server base URL | | AIX_TOKEN | Yes* | — | API key for authentication |

*Not required if server allows unauthenticated access in local dev mode.