Migrating From Per-Agent MCP Configs to One Endpoint

Inventory Before You Move

Start by collecting the MCP entries that already exist in developer machines, repository files and editor settings. The goal is not to merge those JSON blobs mechanically. It is to identify which systems the agents actually use, which credentials they carry, which entries are local experiments and which ones belong to the team. A useful inventory has five columns: client, server name, transport, credential source and owner. If two clients point at the same upstream with different names, mark that immediately because it will become a tool naming and audit problem after the migration.

Claude Code, Cursor and VS Code all have valid places to store MCP configuration, but they are not the same operational boundary. Claude Code can add remote HTTP servers with claude mcp add --transport http <name> <url>, and project-scoped entries live in a root .mcp.json. Cursor uses .cursor/mcp.json for project configuration and ~/.cursor/mcp.json globally. VS Code supports a workspace .vscode/mcp.json, a portable root .mcp.json and user-profile configuration. Your migration plan should name those locations explicitly so nobody keeps reviving an old server from a forgotten profile file.

Replace Many Entries With One

Pick a neutral server name such as workspace, company or spyn3. The name should describe the boundary, not one upstream system. In Claude Code, the target shape is one remote HTTP entry:

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

In Cursor, the equivalent project file keeps the URL reviewable while the key comes from the user environment:

{
  "mcpServers": {
    "workspace": {
      "url": "https://mcp.example.com/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WORKSPACE_MCP_KEY}"
      }
    }
  }
}

For VS Code's workspace format, the same idea uses the top-level servers object:

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

Do this in a branch or rollout note before deleting the old entries. It gives reviewers a clean diff: many client-specific upstreams become one endpoint, and secret material is no longer spread across several client formats.

Keep The Protocol Contract Plain

A one-endpoint migration should still look like normal MCP from the agent's point of view. Streamable HTTP sends each client message as an HTTP POST to a single MCP endpoint, and MCP messages are JSON-RPC. Tool discovery remains tools/list:

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

Tool invocation remains tools/call with one tool name and one argument object:

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

The endpoint earns its place by doing the work the scattered files could not do consistently: disambiguating names, routing calls to the right source, applying authorization and producing one audit trail. MCP tool names are unique within one server, while aggregating multiple servers can create collisions such as two different search tools. Decide the naming rule before cutover. Dot prefixes, slash prefixes or another stable source prefix can work, but the same source must have the same name in discovery, logs and documentation.

Move Secrets And Grants Out Of Clients

The risky part of per-agent configuration is not the JSON syntax. It is credential sprawl. A developer may have a GitHub token in Claude Code, a different Linear OAuth grant in Cursor, and a database token in a VS Code profile. Rotation then becomes a search task across machines, and least privilege becomes a convention instead of an enforced rule.

After the migration, each agent should authenticate to the endpoint with one agent credential. The endpoint should hold or broker the upstream credentials and check policy before any upstream call. That policy needs to be executable, not just prompt text. A read-only key should be able to call issue search or database SELECT tools and should be unable to call update, delete, create or deploy tools even if the model emits perfect JSON. If the endpoint supports OAuth for its own remote MCP surface, keep OAuth scopes narrow and make the agent identity visible in logs.

Use a small permission matrix during rollout. For each source, record whether discovery is allowed, whether read tools are allowed, whether write tools are allowed and who approved the grant. This matrix is easier to review than three unrelated client files. It also aligns with the design in scoped API keys for AI agents and credential rotation without config changes: change the credential or grant at the boundary, not inside every agent's local setup.

Test The Cutover

Run the first cutover with a read-only key and one or two sources. Do not begin with the full company integration catalog. A good pilot has enough surface to prove routing and policy, but not enough surface to hide mistakes. Ask the agent to list sources, enable the issue tracker, perform one read-only search and summarize the result. Then ask for a write action the key should not be able to perform. The correct result is a clear denial before the upstream system is called.

Test failures as deliberately as successes. Expire an upstream token or point one source at a bad URL and confirm that the endpoint reports the source as unreachable instead of returning an empty answer that looks like there were no issues, files or rows. Then compare the agent-visible result with the operator log. The log should show client, workspace, source, tool, arguments or argument hash according to your privacy rules, permission decision, timing and result class. If the old per-agent setup cannot produce the same record, that is part of the migration's value.

Only after those checks pass should you remove old direct entries. In Claude Code, run claude mcp list and claude mcp get workspace to confirm the new server is the one being used, then remove obsolete upstream names. In Cursor, check both project and global files. In VS Code, check workspace and user-profile locations. The dull cleanup step matters because a stale local server can make a migration look successful on one machine and fail silently on another.

Doing this with SPYN3

With SPYN3 the migration has a natural order. Connect each system to the workspace once, then issue one key per agent or job with the grants it needs. Next, replace the client's per-server entries with the single SPYN3 block, and only then remove the old entries. Because the agent's view is the same in every client, you can migrate one client at a time and compare the call log before and after.

Leave A Small Runbook

Finish with a runbook that a teammate can follow without knowing the history of the old files. Include the chosen endpoint name, the client locations you changed, where the agent key comes from, the read-only smoke test, the denied-write test and the rollback path. The rollback path should be temporary and explicit: re-enable one old direct server for one user, investigate, then remove it again after the endpoint path is fixed.

Also document what should not come back. New upstream systems should be added behind the endpoint, not pasted into a single developer's agent config because it is faster in the moment. If a new system needs a direct client entry for experimentation, label it as local, give it an owner and set a deletion date. The long-term operating model is simple: agents keep one MCP server, the workspace owns connections and grants, and every new integration goes through the same naming, permission, logging and failure-handling path. For adjacent design choices, compare when to use an MCP gateway and switching agents without rebuilding integrations.