Switch AI Agents Without Rebuilding Your Integrations

Keep The Agent Thin

The integration boundary should not be Claude Code, Cursor, ChatGPT, VS Code or whichever client wins the next internal trial. Those products are important user surfaces, but they are the wrong place to own durable connection state. If each client connects directly to GitHub, Linear, Postgres, Drive and a handful of internal APIs, a future migration becomes a credential hunt plus a behavior audit.

Use MCP as the stable contract. From the client's side, the server exposes tools; the client discovers them with tools/list and invokes them with tools/call. From the operator's side, the endpoint owns the parts that should survive the client change: upstream accounts, scopes, source names, policy checks, logging, timeouts and failure language. The client then becomes replaceable because it is no longer the system of record for integrations.

This is narrower than a full architecture program. You are not trying to make every model reason identically. You are making sure that a move from one client to another does not also mean reconnecting every source, reissuing every upstream token and rediscovering every permission edge. For the broader design pattern, see agent-agnostic architecture.

Map What Must Move

Start with an inventory that separates client setup from integration ownership. A useful migration table has one row per source and columns for current client, MCP server name, transport, credential owner, read/write capability, approval path and audit location. Mark anything stored directly in a client file as debt unless it is genuinely local-only.

The table prevents a common false migration: the new client appears to work because a developer copied old tokens into a new JSON file. That is not portability. It is duplicated state. The better target is one approved endpoint in each client and one place to inspect which systems the agent can reach.

Configure Each Client Once

Client config will never be identical, so do not chase identical files. Chase identical intent: one remote MCP server, a neutral server name and a credential that represents the agent or workspace. In Claude Code, an HTTPS MCP endpoint can be added with the HTTP transport and an authorization header:

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

Cursor uses mcp.json. For a project-level setup, keep the entry in .cursor/mcp.json and rely on environment interpolation for the key:

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

When the new client is VS Code, decide first whether the server belongs to one repository or to you. For one repository, VS Code reads .vscode/mcp.json, keyed by servers; other tools read a root .mcp.json keyed by mcpServers. Either way the switch adds one remote entry:

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

For ChatGPT or the OpenAI API, the same principle is remote-first: connect to a remote MCP server rather than assuming local stdio config will carry across. OpenAI's API path uses remote MCP server URLs, and ChatGPT's developer-mode docs distinguish remote MCP from local servers. That makes a hosted endpoint much easier to reuse than a pile of local processes.

Verify The Protocol Surface

Do not test the migration only by asking the new agent to do a realistic task. Start one layer lower. The first check is the discovery call the client is supposed to make:

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

The result should be understandable before any model touches it. Tool names should not collide. A tool that came from the issue tracker should not be indistinguishable from a tool that came from the CRM. MCP tool names are unique within one server, and aggregating multiple servers can create collisions, so the integration layer needs a stable disambiguation rule.

The second check is a permitted read. Pick one harmless source, one concrete argument and one expected result shape:

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

Run the same read from the old client and the new client. The natural-language answer may differ, but the source reached, permission decision, tool arguments, upstream status and log record should line up. If they do not, you have found a boundary bug rather than a model preference.

Test Denials Before Trusting Writes

A migration is not ready just because reads work. Try one action that should be denied: create an issue, update a customer, delete a file, deploy a build or run an unsafe SQL statement with a read-only key. The correct behavior is a refusal at the MCP boundary before the upstream system is called. A prompt that says the agent should avoid writes is useful context, but it is not an access-control system.

Also test a missing source and a broken upstream. If the new client sees an empty result when an upstream is down, the agent may reason that there are no matching issues or files. The boundary should return an explicit failure state that names the source and preserves enough operator detail for debugging. Cursor, VS Code and Claude Code all have their own ways of surfacing MCP connection or tool-call failures, but the underlying endpoint still needs to produce a clear, bounded error.

Finally, compare approval behavior. One client may ask before every tool call, another may have an allowlist or run mode, and another may route through API-side approval settings. That difference is fine when the server-side policy is consistent. It is dangerous when client approval is the only thing stopping a write.

How SPYN3 handles the switch

In SPYN3 a switch is a config change in the new client, not a rebuild. The connections, their OAuth grants and the key's permissions stay in the workspace, so the new agent points at the same endpoint with a key and sees the same sources. Issue the new client its own key rather than copying the old one. You can then run both agents side by side for a while, compare them in the call log, and revoke the old key when you're done.

Cut Over In A Reversible Order

Use a small rollout instead of a dramatic flip. Add the new client with a read-only credential, run tools/list, call one harmless read, confirm the audit record, then run the denied-write test. Only after those pass should you enable broader sources or write grants. Keep the old client connected during this window so you can compare behavior without guessing.

1. Choose the canonical endpoint name, such as workspace.
2. Add the endpoint to the new client with a fresh or rotated agent credential.
3. Run discovery and save the returned tool list for review.
4. Call one known read tool and compare logs with the old client.
5. Attempt one forbidden write and confirm denial before routing.
6. Disable stale direct entries in the new client so it cannot bypass the endpoint.
7. Move a small team or project onto the new client, then expand source access gradually.

The cleanup matters. If one developer still has a direct GitHub MCP server in a global Cursor file, while everyone else goes through the shared endpoint, future incidents will be hard to explain. Search global and project config locations for old server names before you declare the move complete. For the more mechanical version of this cleanup, see migrating per-agent MCP configs to one endpoint, and for permission design see scoped API keys for agents.