Rotating Credentials Without Touching Every Agent Config

What Should Stay Still

The invariant is the agent configuration. A developer should not edit every Claude Code, Cursor and VS Code MCP file just because a GitHub token expired, a Linear OAuth grant was re-consented, or a database read role was replaced. Those client files should describe where the agent connects, not every credential the workspace needs behind the scenes.

In MCP terms, the client only needs a server entry that can answer tools/list and accept tools/call. The server may return a different allowed tool set based on the authorization presented on the request, and tool names are only guaranteed to be unique within one server. That is exactly why a central boundary is useful: one endpoint can keep names, permissions and routing stable while its internal credential map changes.

The related guide on MCP gateways covers the broader runtime boundary. For rotation, the narrower rule is this: the client-facing endpoint and server name should be boring, durable and reviewed once. Rotation should happen in the credential store, OAuth connection record, source policy or key table behind that endpoint.

Separate The Three Secrets

Most messy rotations come from treating one token as if it does every job. In an agent integration, there are usually three different credentials. The agent credential authenticates Claude Code, Cursor or VS Code to the workspace MCP endpoint. The upstream credential lets the endpoint call a provider such as GitHub, Stripe or Notion. The OAuth refresh material, when OAuth is involved, lets the integration obtain replacement access tokens without asking the agent client to change anything.

Those credentials need different rotation motions. An agent API key can be replaced by issuing a second key, moving one client or automation at a time, then revoking the old key. An upstream token should be swapped where the gateway stores source credentials, with a test call before the old token is disabled. An OAuth refresh token may be replaced by re-running consent or by refresh-token rotation from the authorization server; OAuth defines refresh tokens as credentials used to obtain new access tokens, and servers may issue a new refresh token during refresh.

This separation is the operational partner to scoped API keys for agents. Least privilege is easier when each secret has one purpose and revoking it does not require editing a half-dozen unrelated client files.

Keep Client Config Static

Claude Code can add a remote HTTP MCP server with a URL and optional headers. The rotation-friendly version keeps the URL stable and points the header at an environment value or other local secret source:

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

If the team uses a project-scoped Claude Code config, commit the endpoint entry but not the secret. A project .mcp.json can name the shared server; each developer still supplies a local key or uses the remote server's sign-in flow. Claude Code also documents OAuth client credentials for remote MCP servers, which is useful when the MCP endpoint itself performs sign-in rather than accepting a static bearer key.

Cursor has the same basic shape in .cursor/mcp.json for a project or ~/.cursor/mcp.json for a user. Its documentation supports remote servers with url, headers, OAuth config and environment interpolation, so the committed file can stay unchanged during upstream rotation:

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

VS Code can also store MCP servers in a workspace file. In the VS Code-specific shape, a remote server is an HTTP entry under servers:

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

None of those snippets contains a GitHub token, database password or provider refresh token. That is the point. The client config says, "talk to the workspace MCP endpoint." The endpoint decides which upstream credential to use for github/search_issues, stripe/list_customers or postgres/select_orders.

Rotation Runbook

A useful rotation is a controlled handoff, not a surprise replacement. Start by deciding which credential class is rotating. If it is an upstream source credential, do not touch client configs at all. Create or obtain the replacement credential in the provider, store it in the gateway, bind it to the same source identifier, and run a read-only validation through MCP before disabling the old credential at the provider.

1. Record the source, old credential identifier, new credential identifier, owner, planned revoke time and rollback condition.
2. Install the new upstream credential behind the existing source name, such as github or linear. Do not rename tools during rotation.
3. Run tools/list with the same agent credential and confirm the visible tool names and schemas did not unexpectedly change.
4. Run one harmless tools/call through the source. Use a query that proves the upstream credential is live but does not mutate data.
5. Review logs for actor, source, tool name, upstream credential version, duration and result class.
6. Revoke or disable the old provider credential only after the new path has produced a successful MCP result.
7. Run the same read call again and confirm no call is still using the retired credential.

The protocol checks can be very small. Discovery should still be ordinary JSON-RPC:

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

A validation call should exercise the routed source without changing state:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "github/search_issues",
    "arguments": {
      "query": "repo:acme/api is:open label:incident",
      "limit": 5
    }
  }
}

If the visible tool list changes during a credential rotation, stop and inspect why. A token swap should not silently add write tools, hide unrelated sources, or rename a tool the model has already learned to call. Those are permission or registry changes, and they deserve their own rollout. The migration article on moving from per-agent configs to one endpoint is the safer order if client files are still carrying upstream secrets today.

Failure Cases To Test

The rotation is not complete until the bad paths are boring too. Test an expired upstream token and confirm the MCP server returns a clear source-specific failure rather than a generic model error. Test an agent key that should be revoked and confirm it cannot list sources or call tools. Test a read-only key against a write-capable tool and confirm the denial happens before any upstream request is made.

OAuth deserves its own dry run. MCP HTTP authorization uses OAuth-style protected resource metadata and token validation, and OAuth refresh behavior can replace access tokens without rewriting the client configuration. The operational risk is stale consent or a refresh token bound to the wrong client. Your test should prove that the gateway can refresh, detect invalid grants, and ask for re-authentication at the source connection layer without requiring every developer to edit .cursor/mcp.json, .mcp.json or mcp.json.

Also watch client caching. Some clients keep the first tool list they saw for a session, and the MCP tools specification encourages deterministic ordering and cache-friendly discovery. Do not rely on a refreshed list to prove rotation. Prove it by routing a call through the endpoint, logging which upstream credential version was used, and returning a result or denial that matches the new policy.

Rotating keys in SPYN3

SPYN3 separates the two kinds of credential this article covers. Upstream OAuth tokens are refreshed by SPYN3 shortly before they expire, and after a 401 it forces a refresh; an upstream that issued no refresh token needs a fresh sign-in in the dashboard. Agent keys are rotated by creating the new key, swapping it into the client's Authorization header and revoking the old one. A revoked key is refused on its next call; when we revoked a test key on 2026-10-14, the next request got a 401.