Skip to main content
When a key leaks, a contractor rolls off, or a token simply ages out, you need to swap the credential on a registered MCP server without tearing down the server record, re-authoring its firewall rules, or interrupting the agents already connected through the gateway. That’s what rotation is: update the auth on an existing server, and the MCP gateway starts injecting the new secret on the very next tools/call it dispatches. Each server’s auth is encrypted at rest and masked on read, so the plaintext token never round-trips back to your console, your agents, or the model. Rotation is a one-field update through the workspace console.

​
1. Why MCP secret rotation is its own action

A registered MCP server holds three things you don’t want to lose when a credential changes: a unique workspace name (the <server>.<tool> namespace your rules glob against), an endpoint, and its discovered tool set. Deleting and re-creating the server to change a token would orphan every rule scoped to <server>.* and force a fresh probe. Rotation sidesteps all of that. You PUT the same server record with new auth_json; everything else — name, rules, discovered tools — stays put.
The gateway injects credentials at dispatch time, decrypting them only to make the upstream call. A rotated secret takes effect on the next connection — OrcaRouter invalidates the per-workspace tool cache on every server change, so there’s no TTL to wait out.

​
2. One concrete rotation

Say you registered an MCP server named github with a bearer token, and that token needs to roll. Read the current record first — the response masks the secret, so you’re never handling the old plaintext: 
# Configure from the console session (UserAuth), not a relay key.
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42 \
  -H "Authorization: Bearer <your console access token>"
Then PUT the same record with only the new credential. Send the id in the body and the fresh auth_json; the gateway re-encrypts it before it touches the database: 
curl -X PUT https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your console access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 42,
    "auth_json": "{\"token\":\"ghp_NEW_token\"}"
  }'
Fields you omit are left untouched — name, endpoint, auth_mode, and enabled all keep their stored values. The new token is live on the next tools/call.
Echo the mask to keep a secret; send a real value to change it. If you read the record and PUT it back verbatim, the masked placeholder in auth_json is recognized as “keep what’s stored” — the secret is not overwritten with the mask. Only a genuinely new auth_json rotates the credential.

​
3. Changing auth mode, not just the secret

Rotation also covers moving a server between auth schemes. The closed set of auth_mode values is:
No credential. auth_json is empty. Use for public or network-trusted MCP servers.
{ "token": "…" } — sent as an Authorization: Bearer header.
{ "client_id": "…", "client_secret": "…", "token_url": "…" }. If you store a static access_token in the JSON, the gateway sends it as a bearer token; the client-credentials exchange itself is not run yet, so a server that needs a live exchange will fail until you supply a token.
{ "username": "…", "password": "…" } — HTTP basic auth.
Switching between two credentialed modes (e.g. bearer → basic) requires sending a fresh auth_json in the same request. The stored ciphertext is bound to its original mode, so the old secret can’t be reinterpreted under the new shape — supply the new credential, or the update is rejected.

​
4. After you rotate: re-probe

A rotated credential changes which tools you can reach if the old token had been revoked. Probe the server to confirm the new auth works and refresh its reachability status: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your console access token>"
The probe runs an MCP handshake with the new decrypted credential and reports ok, degraded, or down. An auth failure surfaces here rather than as a confusing tool error mid-run.

​
5. Roles and what stays masked

Every action on this page is a workspace-scoped console call (/api/workspace/firewall/mcp_servers, UserAuth) and is role-gated:
ActionMinimum role
Read a server (secret masked)Member
Rotate / update / registerDeveloper+
DeleteDeveloper+
Plaintext is never returned to your console. Reads mask the secret and redact the endpoint; the gateway is the only thing that decrypts a credential, and only at the moment it dials the upstream server. The model and your agents see neither the old nor the new token.

​
6. Where this fits

Rotation is one operation in the broader MCP trust surface. Once your servers are connected and authenticated, the same gateway evaluates every tools/call against your firewall policy before it runs, applies skill quarantine on top, and governs outbound reach.

Connect a server

Register an MCP server and probe its tools.

Authenticate

Pick the right auth mode for each server.

Allow-list MCP tools

Scope which tools each server may expose.

Egress limits

Govern where tool calls may reach.
See Firewall: MCP Servers for the full server lifecycle and the MCP trust checklist for the end-to-end hardening pass. Rotation is also a standing line item against MCP tool poisoning and data exfiltration: a credential you can roll fast is a credential a leak can’t sit on.

​
FAQ

No. Rotation changes only the credential. The server keeps its name, so every rule scoped to <server>.* — and any allow-list — stays attached.
The new secret is injected on the next dispatched tools/call. There’s no cache TTL to wait out — OrcaRouter invalidates the workspace tool cache on every server change.
No — and that’s the point. Reads return a masked secret; the plaintext is only ever decrypted by the gateway at dispatch. Rotate by sending a new value, then probe to confirm it works.