Connecting Claude Code to 10 Remote MCP Servers (Real Transcript)

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience building APIs and developer tooling, including three years focused on AI native infrastructure for spiritual and wellness applications. He has led developer relations at two Series B SaaS companies and spoken at PyCon and JSConf on building context rich AI agents using Model Context Protocol.

Most MCP tutorials show a single server, usually running on localhost, usually talking to one thing. That is not how agents actually get used. A working Claude Code session pulls from several tools at once, discovers what each server exposes, and decides on the fly which to call. Until now there has not been a public trace of a real session connecting to many remote MCP servers inside one working directory. This post fixes that. We walk through two anonymized but verified integration traces captured this month, show the exact config that registers 10 remote MCP servers at once, and benchmark the tools/list and tools/call numbers you can expect. No pseudo code. Read the sections in order, copy the JSON, and run the curl.

What happens when Claude Code connects to 10 remote MCP servers

In one traced session, a paying developer registered the spiritual domain RoxyAPI product MCP endpoints in a single mcp.json and initialized them inside Claude Code version 2.1.111. Claude Code sent initialize to each server, then tools/list to each in sequence, and only then paused. No tools/call was issued during the survey phase. The agent inventoried every tool across astrology, Vedic astrology, tarot, numerology, I Ching, dreams, crystals, angel numbers, and biorhythm before committing to an action. Today that same roster pairs with a tenth location geocoder MCP. That is the value of per product MCP servers over a single monolithic server. The client can see the shape of the full surface, route user intent to the right domain, and keep tool descriptions short enough for the context window. Breadth becomes a feature, not a noise tax.

Ready to build this? RoxyAPI gives you 10 MCP servers under one API key. See the full MCP documentation.

How the RoxyAPI MCP transport actually works

Every RoxyAPI product ships its own dedicated MCP server at /mcp/{product-slug} on the main domain, never on a subdomain. The transport is Streamable HTTP, POST only, stateless. There is no SSE channel, no WebSocket upgrade, no long lived session. That design choice matters for Claude Code because the client probes unfamiliar endpoints with GET first. RoxyAPI responds to GET with a 405 and a JSON RPC error that explains the transport is POST only. Every compliant MCP client falls back to POST automatically, which is exactly what happened in both traced sessions. The stateless model means you can run 10 servers against one X-API-Key header with no session state to reconcile. It also means tools/list is idempotent and cacheable on the client. Warm tools/list latency measured in production sits at 2 to 3 ms, because the server returns a precomputed array rather than rebuilding the spec on every request.

How one developer went from signup to 6 live endpoints in 26 minutes

This is the first traced pattern and it is a clean picture of the AI agent acquisition loop. A developer in the Atlantic region completed checkout and instant provisioning. They opened the API reference playground in a browser first, then Claude Code took over. Its user agent string, claude-code/2.1.101, showed up on the server fetching /api/v2/openapi.json and then discovery crawling seven product pages in sequence: tarot, numerology, I Ching, biorhythm, angel numbers, dreams, and crystals. Twenty six minutes after signup the first curl session fired. Of the 6 endpoints attempted, 4 succeeded first try. The remaining 2 recovered inside seconds: one was a GET on a POST only route, one was a schema invalid payload. No support ticket, no email, no onboarding friction. The agent read the OpenAPI, guessed, corrected itself, and moved on.

How another developer swept every product MCP server in 30 minutes

The second pattern is a different shape and it is the reason per product MCP servers exist. A developer in South Asia signed up, provisioned a key, and within 30 minutes had claude-code/2.1.111 connected to every one of the spiritual domain RoxyAPI product MCP endpoints. Every server received initialize. Every server received tools/list. Not a single tools/call fired during this window. The agent used the MCP surface itself as the documentation. It did not open a product page, it did not hit the REST reference, it did not curl anything by hand. The tool catalog was the map. This is what MCP first onboarding looks like in practice, and it is the reason our MCP split is one server per product rather than a single giant server. A buyer can survey the capability breadth in a single agent session, decide which domain they want to build on, and commit once, all before writing a single line of integration code.

What the mcp.json config for 10 remote RoxyAPI servers looks like

Here is the exact Claude Code config that registers all 10 RoxyAPI per product MCP servers under a single X-API-Key header. The URL segment for every MCP endpoint uses the full product slug with the -api suffix, matching the product registry. Save this as .mcp.json at the root of your working directory and Claude Code will pick it up on start.

{
  "mcpServers": {
    "roxy-astrology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/astrology-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-vedic-astrology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/vedic-astrology-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-tarot": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/tarot-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-numerology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/numerology-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-iching": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/iching-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-dreams": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/dreams-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-crystals": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/crystals-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-angel-numbers": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/angel-numbers-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-biorhythm": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/biorhythm-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    },
    "roxy-location": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/location-api",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    }
  }
}

Export ROXY_API_KEY in your shell before launching Claude Code. Three auth paths are accepted by the server, checked in order: X-API-Key header, Authorization: Bearer header, and api_key query param. X-API-Key is the canonical pattern our docs ship across every client config (Claude Code, Claude Desktop, VS Code, Antigravity, OpenAI Agents SDK, Gemini), so the block above drops straight into any of those without changes. The one exception is the Claude Messages API, which takes authorization_token on its MCP connector block and maps to Bearer auth under the hood.

How to verify tools/list with a single curl call

Before you wire the config into an agent, confirm the server answers you directly. This curl hits the tarot MCP server with a JSON RPC 2.0 tools/list request and prints the full tool catalog. tools/list and initialize are public methods on the MCP server, so this call does not consume billable quota. The tools/call method is authenticated and billable, and runs through the same middleware chain as REST requests.

export ROXY_API_KEY="your_key_here"

curl -sX POST https://roxyapi.com/mcp/tarot-api \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ROXY_API_KEY" \
  --data-binary @- <<JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
JSON

Tool names follow a strict convention pulled from the OpenAPI spec. Routes keep their full domain prefix in the tool name. A route declared as GET /astrology/horoscope/{sign}/daily becomes the MCP tool get_astrology_horoscope_sign_daily. A route declared as POST /vedic-astrology/birth-chart becomes post_vedic_astrology_birth_chart. That rule lets an agent reason about the tool surface without ever reading a product page. Full endpoint details live in the interactive playground once you want to drill in. For copy ready integrations you can fork, the starter apps include a multi domain chatbot that speaks to every one of these servers.

How much latency to expect on warm calls

Numbers from production, measured across the MCP router. tools/list on a warm server returns in 2 to 3 ms. The server holds a precomputed array of tools keyed by product slug, so there is no spec parse and no tool rebuild on the hot path. The first tools/list on a brand new product does a one time 114 ms cache build; every call after that hits the warm path. tools/call is about 35 ms end to end: 3 ms of MCP overhead plus about 32 ms to proxy the request through the full middleware chain. That chain includes API key validation, rate limit accounting, usage tracking, and schema validation, the same chain the REST endpoints run. That is the number you should budget against user perceived latency when an agent chains multiple tool calls into one response. Ten servers registered in parallel cost about 20 to 30 ms of warm tools/list traffic at boot.

Frequently Asked Questions

Q: What is a remote MCP server and how is it different from a local one? A: A remote MCP server is a hosted HTTP endpoint that speaks the Model Context Protocol. Your agent client connects to it over the network instead of launching a local process. RoxyAPI ships 10 remote MCP servers at /mcp/{product-slug} (where the slug carries the -api suffix, matching the product registry), which means no local install, no runtime dependency, and the same auth model as the REST API.

Q: How do I connect Claude Code to a remote MCP server? A: Create an .mcp.json at the root of your working directory with one entry per server, give each "type": "http", a url, and a headers block carrying your X-API-Key value, then start Claude Code. The client reads the config on launch, sends initialize to each server, and calls tools/list to inventory the tools it can use.

Q: Does connecting to 10 MCP servers cost 10 times more? A: No. initialize and tools/list are free. You only pay when the agent calls tools/call, which runs one billable API request through the same middleware the REST endpoints use. Ten registered servers cost nothing until you actually invoke a tool.

Q: Why does MCP return a 405 when I hit the URL in a browser? A: Streamable HTTP is POST only. A GET on an MCP endpoint returns a 405 with a JSON RPC error describing the transport. This is expected and compliant. MCP clients probe with GET first, see the 405, and fall back to POST automatically.

Q: How do MCP tool names map to REST endpoints? A: RoxyAPI derives tool names from the OpenAPI spec, keeping the full domain prefix. GET /astrology/horoscope/{sign}/daily becomes get_astrology_horoscope_sign_daily. POST /vedic-astrology/birth-chart becomes post_vedic_astrology_birth_chart. The HTTP method prefixes the snake cased path. That rule keeps names predictable for agents that have never seen the product before.

The shortest path from signup to a working multi domain agent today is to paste the mcp.json above, export your key, and let Claude Code inventory 10 servers for you. We see it work in 30 minutes because the MCP surface doubles as the documentation. Ready to try it? Grab a key on the pricing page and point Claude Code at it.