ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect an MCP Router to Claude Code

Connect an MCP router to Claude Code with HTTP transport, authentication, project configuration, verification steps, and fixes for common errors.

By the ScreenshotNeo team1 October 20266 min read

Use Claude Code’s MCP command to register the router as an HTTP server, pass the router’s authentication header, restart Claude Code, and run /mcp to verify the connection. The exact hostname, route, token format, and available tools come from your router. The endpoint might expose every enabled server, one downstream server, or a workspace-specific collection.

1. Collect the router details

Before changing Claude Code, get these values from the router’s documentation or administrator:

  • Endpoint URL: the actual HTTP or HTTPS MCP route. A route named /mcp is only an example.
  • Transport: this guide uses Streamable HTTP, selected with Claude Code’s --transport http option.
  • Authentication: whether a bearer token or another header is required.
  • Scope: whether the endpoint aggregates all enabled servers, exposes one server, or targets a workspace.
  • Permissions: which tools and data sources the router allows this credential to use.

Do not paste a real token into a shared article, repository, or team configuration file. Use an environment-aware secret workflow or a local user configuration supported by your router.

2. Add the router with the Claude Code CLI

For the documented HTTP router pattern, run:

claude mcp add --transport http router http://localhost:3000/mcp \
  --header "Authorization: Bearer <token>"

Replace all three example values:

  • router is the local name Claude Code displays for this connection.
  • http://localhost:3000/mcp must become your router’s real endpoint.
  • <token> must become the credential required by that router, if authentication is enabled.

For a remote router, use its HTTPS URL:

claude mcp add --transport http company-router https://router.example.invalid/workspaces/acme/mcp \
  --header "Authorization: Bearer <token>"

The hostname and path above are placeholders. Use the route supplied by your router rather than assuming that every implementation supports /mcp, a per-server suffix, or a workspace path.

3. Configure the connection in a project

Claude Code also supports a project-root .mcp.json configuration. Use the schema documented by your installed Claude Code version and router. A representative HTTP entry looks like this:

{
  "mcpServers": {
    "router": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Keep credentials out of a committed file. If your team shares .mcp.json, use the router’s supported environment-variable or secret-reference mechanism instead of writing a live token into Git.

4. Restart and verify the connection

  1. Close and reopen Claude Code after adding or changing the server.
  2. Run /mcp inside Claude Code.
  3. Confirm that the router appears as connected and that its expected tools are listed.
  4. Ask Claude Code to perform a harmless read-only operation through one known tool.

If the router aggregates several downstream MCP servers, verify the downstream server you need is enabled in the router. A successful connection to the router does not guarantee that every downstream tool is available.

5. Understand endpoint and transport choices

Router setup Claude Code approach What to confirm
One aggregate HTTP endpoint claude mcp add --transport http ... The endpoint exposes the enabled tools you expect.
One endpoint per downstream server Add each endpoint with its own name. Each URL and credential maps to the intended server.
Workspace or tenant endpoint Use the workspace-specific URL supplied by the router. The token has access to that workspace.
Local process server Follow the server’s command or local-process configuration instructions. Do not force an HTTP transport onto a process-based server.
Private-network HTTP server Use a reachable private-network option supported by your environment. DNS, firewall, TLS, and client support are all in place.

6. Private routers and Anthropic’s tunnel option

Anthropic documents a tunnel design for private MCP servers in which cloudflared makes outbound-only connections and an Anthropic proxy routes requests to upstream servers by hostname. This can avoid opening inbound firewall ports or exposing the service publicly.

The tunnel documentation labels this feature a research preview with no uptime, support, or continuity commitment. Its quickstart ends in a Claude Managed Agents session; it does not establish a verified direct Claude Code CLI setup. Confirm that your intended Claude Code client supports the exact tunnel flow before adopting it.

Anthropic’s account-brokered remote connector guidance also says those connections originate from Anthropic’s cloud infrastructure. That statement applies to those custom connectors and should not be generalized to a local Claude Code MCP process.

7. Secure the connection

  • Use HTTPS for routers reachable outside your machine or private network.
  • Issue a token with only the tools and data permissions Claude Code needs.
  • Rotate tokens through the router’s normal credential process.
  • Never commit bearer tokens, session cookies, or authorization headers.
  • Review which downstream servers the aggregate endpoint exposes before granting write-capable access.
  • Record the router name and endpoint scope so operators know whether a request can reach one server or many.

8. Troubleshooting

Symptom Likely cause Fix
Claude Code says the server is disconnected Claude Code has not reloaded the configuration. Restart Claude Code, then run /mcp.
401 or 403 response Missing, expired, malformed, or under-permissioned credential. Check the router’s required header and token scope. Do not assume every router uses bearer authentication.
404 response The path is implementation-specific and the example route is wrong. Copy the exact aggregate, per-server, or workspace endpoint from the router documentation.
Connection times out The router is not reachable from the machine running Claude Code, or a firewall/TLS rule blocks it. Check DNS, routing, firewall policy, certificate trust, and whether the server is listening on the expected interface.
The router connects but tools are missing The downstream server is disabled, the token lacks permission, or you connected to the wrong scope. Inspect the router’s enabled-server and workspace settings, then reconnect and run /mcp.
Tools work intermittently Network instability, overloaded downstream services, or a preview tunnel dependency. Check router and downstream logs, reduce concurrent calls, and treat research-preview tunnel behavior as non-guaranteed.
CLI rejects --transport http An older or different Claude Code build is installed. Use the MCP configuration method supported by your installed version and consult its current command help.
A local process was added as HTTP The server is stdio or another process transport. Follow that server’s local-process setup instead of using an HTTP URL.

9. Performance, reliability, and cost considerations

Performance

An aggregate router adds a network hop and tool-discovery layer. Keep the router close to its downstream services when possible, avoid routing large unnecessary payloads, and select a workspace or per-server endpoint when the router offers narrower scopes.

Reliability

Claude Code depends on the router, every selected downstream server, authentication, and the network path between them. A healthy router connection can still fail when one downstream server is unavailable. Build operational checks around /mcp, router logs, downstream health signals, and token expiry.

Cost

The dossier provides no universal MCP router pricing or usage benchmark. Check the router and downstream providers for their own limits and charges. Anthropic’s tunnel research preview also provides no continuity commitment, so do not treat it as a guaranteed production dependency.

Or skip the browser setup

If your MCP workflow needs website screenshots, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status.

For a direct screenshot call, see the ScreenshotNeo API documentation:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

The API also supports full-page and element captures, device presets and custom viewports, retina scale, dark mode, PDFs, HTML/CSS rendering, custom CSS and JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, bulk capture, and usage reporting. Every plan includes every feature. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and connect its MCP server when you want Claude Code to capture clean pages without maintaining browser infrastructure.

FAQ

Does every MCP router use the /mcp path?

No. The path is router-specific. It may be an aggregate, per-server, or workspace route.

Can I use a router without authentication?

Only if that router permits unauthenticated access. Send an authorization header only when the router requires it.

Does adding one router expose all of my MCP servers?

Only the tools and downstream servers exposed by that endpoint and credential are available. Confirm the router’s scope before connecting it.

Should I use Anthropic’s tunnel for Claude Code?

Verify client support first. The documented quickstart connects to Claude Managed Agents, and the tunnel is marked a research preview.

Where should I look when a tool is absent?

Check /mcp, the router’s enabled-server list, workspace selection, and the token’s permissions.

Keep reading