Model Context Protocol

MCP passthrough

Route MCP tool servers and chat completions through one endpoint. Add mcp_servers to any /v1/chat/completions request, keep the OpenAI-compatible response shape. No SDK swap, no separate MCP client.

Quickstart

Add an mcp_servers array to any request. Leanroute forwards it to an Anthropic-family model, Claude connects to each server, calls tools as needed, and returns the final answer.

curl https://api.leanroute.dev/v1/chat/completions \
  -H "Authorization: Bearer $LEANROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
      { "role": "user", "content": "What upcoming meetings do I have this week?" }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "calendar",
        "authorization_token": "eyJhbGciOi..."
      }
    ],
    "max_tokens": 1024
  }'

Response is OpenAI-shape. The assistant.content string already incorporates any MCP tool results Claude retrieved; you don't need to run a separate tool loop.

Server configuration

Each entry in mcp_servers takes:

• type — currently only "url".
• url — MCP server endpoint. Must be https://. Supports Streamable HTTP and SSE transports.
• name — unique identifier for this server within the request. Used to reference it in Claude's internal tool binding.
• authorization_token — OAuth Bearer token if the server requires it. Forwarded verbatim; Leanroute never logs it.

Response headers

Two headers surface the MCP path so you can verify what happened:

• x-gateway-mcp-passthrough: N — number of MCP servers forwarded. Present only when mcp_servers was sent.
• x-gateway-provider: anthropic — MCP requests always route to Anthropic today (see provider support below).

Provider support

MCP passthrough (v1) requires an Anthropic-family model because Anthropic's Messages API is currently the only chat completion API that natively consumes mcp_servers. Universal cross-provider support (via a gateway-hosted MCP shim) is planned for /v2.

Errors

If you set mcp_servers on a request that routes to a non-Anthropic provider, Leanroute refuses loudly rather than silently dropping the field:

{
  "error": {
    "message": "mcp_servers requires an Anthropic-family model. Set model to anthropic/* ...",
    "code": "mcp_unsupported_provider"
  }
}

Fix: set model to any anthropic/* id (anthropic/claude-sonnet-5 is a good default), or remove mcp_servers if you don't need MCP for this call.

Arbitrage + MCP

Requests with mcp_servers are excluded from same-tier cost arbitrage — swapping to a non-MCP-capable model would silently drop the field. Explicit model choice is respected; if you pointed at anthropic/claude-sonnet-5, that's what runs.

What's not supported yet (v1)

• Non-Anthropic providers — see the provider table above. Bridging is the /v2 story.
• Per-tool allowlist / denylist / defer_loading — v1 enables all tools from each server with default configuration. Send Anthropic's mcp_toolset config directly if you need finer control (as of writing this we don't translate that; open an issue if it matters).
• Local stdio MCP servers — MCP passthrough is HTTPS-only, matching Anthropic's constraint. Local servers need a client that speaks stdio.
• MCP prompts / resources — only tools are supported at the Messages API level; prompts and resources are managed client-side.

Pricing

MCP-augmented requests are billed like any other request: upstream input + output tokens, at the model's catalog rate. Tool calls Claude makes to MCP servers server-side are billed by Anthropic as input tokens on the subsequent turn — same math whether you go direct to Anthropic or through us.

See also: API reference · Response headers · Model catalog · MCP specification