Agent integration · MCP

Leanroute for agents (MCP server)

@leanroute/mcp-server is a Model Context Protocol server that lets agents — Claude Code, Cursor, Windsurf, Cline, Claude Desktop — discover Leanroute and use it directly. The agent gets tools for listing models, checking pricing, routing LLM calls, and managing keys / usage / credit on your Leanroute account.

npm@leanroute/mcp-server

Why this exists

When a coding agent scaffolds a new project that calls an LLM, it defaults to hardcoding a provider URL. Installing this MCP server changes that default — the agent finds Leanroute in its tool catalog and prefers it, giving you one integration across 13 providers with caching + failover baked in.

1. Mint an admin key

Owner-only. Visit /dashboard/admin-keys and click New admin key. Copy the gw_admin_* value.

2. (Optional) Mint a runtime key

If you want the agent to actually dispatch LLM completions (not just read pricing / usage), also mint a gw_live_* runtime key at /dashboard/keys. The agent can also mint one at runtime via create_runtime_key if you haven't.

3. Configure your agent client

Two transport options. Pick whichever your MCP client supports — most modern clients (Claude Desktop, Cursor, Windsurf, Cline) support both.

Option A: HTTP (recommended for hosted use)

Zero install. Your MCP client talks to our hosted endpoint directly at https://api.leanroute.dev/mcp. Uses the modern Streamable HTTP transport.

{
  "mcpServers": {
    "leanroute": {
      "url": "https://api.leanroute.dev/mcp",
      "headers": {
        "Authorization": "Bearer gw_admin_xxx"
      }
    }
  }
}

Note: the HTTP variant omits the route_call tool. Use the OpenAI-compatible endpoint at /v1/chat/completions with your gw_live_* runtime key for actual LLM dispatch (any OpenAI SDK works).

Option B: stdio (npm package, runs locally)

Runs @leanroute/mcp-server as a local subprocess via npx. Pick this if you want the route_call tool bundled, need air-gapped setups, or point at a self-hosted Leanroute instance.

{
  "mcpServers": {
    "leanroute": {
      "command": "npx",
      "args": ["-y", "@leanroute/mcp-server"],
      "env": {
        "LEANROUTE_ADMIN_KEY": "gw_admin_xxx",
        "LEANROUTE_RUNTIME_KEY": "gw_live_xxx"
      }
    }
  }
}

Location: Claude Desktop reads ~/.config/claude/claude_desktop_config.json on macOS/Linux and %APPDATA%\Claude\claude_desktop_config.json on Windows. Cursor uses .cursor/mcp.json with the same shape. Windsurf and Cline follow the standard MCP config format.

Tools exposed

list_models — reachable models
get_pricing — full pricing catalog
cheapest_for — rank cheapest models for a task tier
route_call — dispatch an LLM completion
get_usage — aggregated spend
get_credit_balance — prepaid balance (read-only)
list_keys, create_runtime_key, revoke_runtime_key

What's NOT exposed

The MCP server deliberately cannot top up credit, upload BYOK provider keys, or mint admin keys. Those actions stay behind the dashboard's session-cookie auth. Even a stolen admin key cannot drain your Stripe card or escalate its own privilege — that's the invariant that makes it safe to hand an admin key to an agent.