Connect Claude Code to Many MCP Servers Through One Endpoint

Use One Claude Code Entry

Claude Code can add a remote HTTP MCP server from the CLI. For a workspace endpoint, the local setup should be deliberately boring: one server name, one URL and one authentication path. The shape is:

claude mcp add --transport http workspace https://mcp.example.com/agent/mcp \
 --header "Authorization: Bearer $AGENT_MCP_KEY"

That command is enough for Claude Code to treat the endpoint as an MCP server. The fact that the endpoint may reach GitHub, Linear, Sentry, Postgres and Google Drive behind the scenes should not leak into the developer's local config. If you put every upstream server directly into Claude Code, you also put every upstream credential, naming collision and rollout decision into each user's machine.

For a team, project scope is usually the part to standardize. Claude Code can write a project-scoped .mcp.json so everyone opens the same server entry after approving the project configuration. Keep that committed file free of static secrets. Put only the endpoint and server type in shared config, then use a local key, OAuth flow or approved header helper for the credential.

Keep The Protocol Boundary Ordinary

The endpoint does not need to invent a new client contract. Claude Code discovers tools through MCP, and the server answers discovery with ordinary tool descriptors. A minimal discovery request still looks like this:

{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "tools/list",
 "params": {}
}

Invocation is ordinary too. Claude Code calls one tool name with arguments, and the endpoint is responsible for routing that logical call to the right upstream source:

{
 "jsonrpc": "2.0",
 "id": 2,
 "method": "tools/call",
 "params": {
   "name": "linear/search_issues",
   "arguments": {
     "query": "checkout regression",
     "limit": 10
   }
 }
}

The important engineering work is behind the descriptor. MCP tool names are unique within a server, not across all servers your company connects. Two upstreams can both expose search, query or list_projects. A single endpoint has to disambiguate names before Claude Code sees them, preferably with source identity that survives logs and review. If names are unstable, prompts become brittle and audit trails become ambiguous.

Choose Local, Project Or User Scope Intentionally

Claude Code supports different MCP configuration scopes, and the scope decision affects both collaboration and risk. A local-scope server is useful for a personal experiment because it stays in the user's Claude configuration for the current project. A project-scoped server writes the shared .mcp.json at the repository root, which is better when the team wants the same MCP entry and reviewable changes.

claude mcp add --transport http workspace --scope project \
 https://mcp.example.com/agent/mcp

The resulting project file is intentionally small:

{
 "mcpServers": {
   "workspace": {
     "type": "http",
     "url": "https://mcp.example.com/agent/mcp"
   }
 }
}

Do not turn .mcp.json into a secret distribution mechanism. If the server needs a bearer token, prefer a local credential source or a header helper that your team understands and trusts. Claude Code treats header helpers as shell commands and has explicit trust rules for project and local-scope configurations. That is a hint about the operational model: shared config should declare the endpoint; secret material should be local, scoped and replaceable.

Make Discovery Smaller Than The Company

The first failure mode of connecting many systems is not usually protocol failure. It is giving the model a noisy shelf of tools and expecting it to choose well. Claude Code has tool availability and tool search behavior, but the server still controls what descriptors it returns. A one-endpoint design should use that control to expose a small working set, not a dump of every upstream operation.

For example, the initial list can show source-level controls and only the tools that are already open for the session. The user can ask for the issue tracker, documentation system or database when the task needs it. That keeps the visible surface close to the question at hand and makes tool choice easier to review. It also avoids retraining every developer to remember which of six different search tools belongs to which service.

This is the same problem as context bloat from too many MCP tools, but Claude Code makes it especially visible because the developer is often inside an active code task. The right setup lets Claude inspect the repo, open the specific external source it needs, call the needed tool and then continue without carrying the whole company's integration catalog in context.

Put Auth And Permissions Behind The Endpoint

There are two credentials to separate. One credential lets Claude Code reach the workspace endpoint. Other credentials let that endpoint reach upstream systems. Mixing those together on every developer machine makes rotation and least privilege harder than it needs to be.

For remote MCP servers, authorization can use OAuth discovery and scopes, and Claude connectors can also be configured with remote MCP URLs, sign-in behavior or fixed request headers. That is useful, but it does not remove the need for a runtime permission check at the aggregation layer. The endpoint should validate the agent credential, resolve the workspace, check the source allowlist, decide whether the requested tool is read-only or write-capable, and only then call the upstream system.

Model-facing instructions are not enough for this. A prompt that says "only read from production" is helpful context, but it is not a permission boundary. Put the boundary in code. A read-only key should be unable to call a write tool even if the model asks for it with perfect JSON. For the narrower policy design, see scoping API keys for agents and signing in to upstream MCP servers once.

How SPYN3 handles it

With SPYN3, Claude Code gets one entry instead of one per server: claude mcp add --transport http spyn3 https://api.spyn3.com/agent/mcp --header "Authorization: Bearer <key>". The agent opens a source with enable_toolset when it needs one. In our test on 2026-10-14, Claude Code kept the tool list it fetched at the start of the session, so tools opened mid-conversation did not appear. That is why enable_toolset answers with the opened tools and their arguments, and call_tool reaches them without a reconnect. Claude Code shows SPYN3's namespaced tools with underscores, for example mcp__spyn3__deepwiki_ask_wiki_question.

Roll It Out With Concrete Checks

1. Add the endpoint under a neutral Claude Code server name such as workspace, not the name of one upstream service.
2. Run claude mcp list and claude mcp get workspace to confirm Claude Code saved the server and reports the expected status.
3. Start with a read-only key and ask for a harmless discovery task, such as listing issue tracker projects or counting rows through a read-only Postgres tool.
4. Verify the endpoint log records the Claude Code client, source, namespaced tool, permission decision, timing and result class.
5. Try a blocked write with the same key and confirm it is denied before reaching the upstream service.
6. Disconnect or misconfigure one upstream and confirm Claude Code receives a clear unreachable-source result instead of a misleading empty answer.
7. Add a second client only after those checks pass, so any differences you see are client behavior rather than integration drift.

The goal is not to hide complexity from engineering. It is to put complexity where it can be reviewed once. Claude Code keeps one MCP entry, the endpoint owns the source graph, and each new upstream system goes through the same naming, permission, logging and failure-handling path. For a broader migration plan, compare moving from per-agent configs to one endpoint.