Agent-Agnostic Architecture: Keep the Agent Replaceable

Put a Contract Between Client and Sources

The risky mistake is treating the current agent as the integration layer. A client config is good at telling a product where an MCP server lives. It is a weak place to keep long-lived SaaS tokens, database access rules, source naming conventions, write approvals and operational logs.

The contract should sit one layer lower: a workspace endpoint that speaks MCP to compatible clients and owns the durable source boundary. MCP gives clients a standard way to discover tools with tools/list and invoke them with tools/call. It does not, by itself, decide which workspace a token belongs to, whether a source is allowed for this key, or how an upstream outage should be reported.

That distinction is the whole design. The agent is allowed to change. The connected systems, permissions, audit trail and source vocabulary should not have to move with it. For the migration side of the same idea, see switching agents without rebuilding integrations.

Move Durable Responsibilities Outward

This is especially important when the same business source is useful in several places. A support issue may be triaged in ChatGPT, investigated in Claude Code and edited from Cursor. If each client owns its own source setup, the team now has three credential inventories, three approval surfaces and three places to debug the same failed call.

Keep the client-specific notes thin and explicit. One file can explain how Claude Code is configured, another how Cursor is configured, and another how VS Code is configured. None of those files should redefine who may call production tools.

Keep Client Setup Boring

A replaceable client has a small config. In Claude Code, the remote HTTP shape is a command that names the server and points at the endpoint:

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

In Cursor, keep the project entry in .cursor/mcp.json focused on the same endpoint. Use environment-backed secrets or a local-only mechanism for the actual key rather than committing credentials:

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

In VS Code, the workspace format uses a top-level servers object in .vscode/mcp.json, while the portable workspace format uses .mcp.json with mcpServers. A remote HTTP server entry can stay similarly small:

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

The point is not that these products store config identically. They do not. The point is that each config should carry only the client-specific connection details. Source grants, upstream tokens, write permissions and logging should remain behind the endpoint. For adjacent rollout choices, compare scoped API keys for agents and credential rotation without client edits.

Test Against Protocol Calls

Do not validate portability by asking whether a demo prompt worked once. Validate the MCP contract directly. The first check is discovery:

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

The response should be deterministic for the same credential, understandable to a human reviewer, and small enough that the model is not choosing from every source at once. If two upstreams both expose search, the boundary should disambiguate them before the client sees the tools. The MCP tool specification notes that tool names are unique only within one server, so aggregation needs an explicit collision strategy.

The second check is invocation. Pick a harmless read tool and call it with concrete arguments:

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

Record the expected source, permission decision, output shape and log entry before running the same task in another client. If the second client chooses a different tool, you now have a real comparison: the protocol surface was the same, so the difference is likely in prompt context, approval behavior, tool display or model choice.

Policy Is Runtime Work

Prompts can describe policy, but they should not be the policy. A prompt that says "do not write" is useful context; it is not an authorization boundary. The HTTP authorization path for MCP uses bearer-style access on requests, and the server side still has to validate the token, audience, scope and workspace before honoring a tool call.

Model the grants around jobs, not around personalities. A read-only investigation key can list source folders and call tools marked safe for reads. A release-management key may have write access to a narrower set of issue-tracker or deployment tools. A local-development key may reach staging sources but not production. Those are runtime checks the boundary can apply consistently, even when the client changes.

Also keep denial visible. If a key cannot call a source, the system should report that the source exists but is withheld or unauthorized, not make it look like the company has no such system. Hidden denial creates bad reasoning. Clear denial creates a useful next action: ask for access, switch keys or continue without that source.

How SPYN3 holds the line

In SPYN3 the agent holds two things: the endpoint https://api.spyn3.com/agent/mcp and a credential, either an API key or MCP sign-in. Connections, upstream credentials, per-key grants and the call log stay in the workspace. Moving from Claude Code to Cursor is therefore a change to one client config entry. Nothing about the sources, their permissions or their history moves with it.

Rollout Checklist

1. Draw the current agents, sources and credentials as separate boxes.
2. Choose the stable MCP endpoint that clients will point to.
3. Move upstream grants and generated connector credentials behind that endpoint.
4. Name tools with source identity before adding a second similar source.
5. Issue a read-only key for the first client and run tools/list.
6. Call one harmless tool and verify logs, latency, source name and output shape.
7. Repeat the same prompt in a second client and compare tool selection.
8. Test a forbidden source and a forbidden write before granting broader access.
9. Rotate the trial key and confirm no upstream source has to be reconnected.

The result is not that every agent behaves the same. It will not. The result is that client differences become observable and contained. The source layer stays stable, and the next client evaluation starts from one endpoint instead of a pile of copied integrations. For the surrounding gateway choice, use the MCP gateway guide.