MCP Integration

GreatRouter exposes a remote Model Context Protocol (MCP) server so AI assistants can classify prompts, suggest models, run auto-routing, and browse the catalog using your API key.

Endpoint

https://mcp.greatrouterai.com/mcp

Health check: GET https://mcp.greatrouterai.com/health

Authentication

Every MCP request must include your GreatRouter API key:

Authorization: Bearer pk_live_...

Test keys (pk_test_...) work the same way. Get a key from the dashboard.

Cursor configuration

Add this to your Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "greatrouter": {
      "url": "https://mcp.greatrouterai.com/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Replace pk_live_YOUR_KEY_HERE with your API key from the dashboard.

Available tools

Example: suggest models

Ask your assistant to call suggest_models with a prompt:

{
  "prompt": "Generate a cinematic sunset landscape image",
  "optimization": "balanced",
  "limit": 5
}

The tool returns classification metadata and ranked suggestions — no inference is run.

Example: auto route

auto_route runs full routing plus inference. Use budget_dollars to cap spend:

{
  "prompt": "Write a TypeScript function to debounce API calls",
  "optimization": "price-optimized",
  "budget_dollars": 0.05
}

Billing and rate limits

MCP tools use the same wallet, usage records, and rate limits as the REST API. auto_route deducts usage on successful inference; suggest/list/catalog tools are free aside from any underlying API costs where applicable.

Agentic payments (x402, optional)

When the MCP Worker has X402_RECIPIENT configured, auto_route is also exposed as an x402 paidTool (default $0.01 USDC per call on Base). API key auth remains required — x402 is additive for autonomous agent clients using withX402Client from agents/x402.

See greatrouter/apps/mcp/.env.example for local wrangler dev setup.

Troubleshooting