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

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 recorded session, the client 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. RoxyAPI has since added Human Design, Forecast, Chinese astrology, feng shui, Mesoamerican astrology, Vastu, Kabbalah and Ayurveda servers, bringing the platform to 18 in total; the traces in this post capture the 10 server roster as it stood when the sessions were recorded. 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 now gives you 18 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. Measure discovery latency from your client when selecting the domains to configure.

A recorded REST discovery session

One recorded session used REST discovery. The agent read the public OpenAPI specification and product pages, then attempted six endpoints. Four succeeded on the first attempt; a method mismatch and an invalid payload were corrected before the remaining calls completed.

A recorded MCP discovery session

A second recorded session used MCP discovery. The client initialized the configured servers and listed their tools before making any tool calls. This demonstrates catalog discovery across multiple domains without writing a separate schema for each endpoint.

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. 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, uses the same API subscription 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 templates include a multi domain chatbot that speaks to every one of these servers.

How much latency to expect on warm calls

Latency varies by endpoint, client location, and request conditions. Measure the complete request from your application before setting a user-facing latency target.

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 12 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.

Configure the domains your agent needs and let the client discover their tools. The MCP guide carries the current setup instructions, and pricing covers all domains under one subscription.