Rotating MCP Credentials: A Practical Guide for Leaks, Expiry, and Routine Hygiene

Two credential models, two playbooks

MCP credentials live in one of two places. API keys for local stdio MCPs sit in the client\'s config file as environment variables — `GITHUB_TOKEN`, `STRIPE_KEY`, `POSTGRES_URL`. OAuth access and refresh tokens for remote MCPs sit in the OS credential store, managed by the client. The rotation steps differ by storage location, but the underlying principle is the same: revoke first, re-issue second, update third.

Playbook A — Rotating an API-key MCP

1. 1

   Issue a new key in the upstream service

   Most services let you have two keys active at once. Create the new one with the same (or tighter) scope.

2. 2

   Update the MCP client config

   Replace the env-var value in claude_desktop_config.json / mcp_config.json / .vscode/mcp.json. Save.

3. 3

   Restart the MCP client

   stdio MCPs only re-read env on start. Cmd+Q + relaunch is the surest path.

4. 4

   Verify the new key works

   Run a no-op tool call in a fresh conversation. Confirm a successful response.

5. 5

   Revoke the old key

   Only after the new key is confirmed working. This is the irreversible step — wait until you have proof of life.

6. 6

   Audit recent activity

   If this rotation was triggered by a suspected leak, scan the upstream service's activity log for the past 24 hours for actions you did not initiate.

Playbook B — Rotating an OAuth MCP

1. 1

   Revoke the token at the OAuth authorization server

   For most services this is in the user's "connected apps" or "authorized clients" UI. Revoking here invalidates both the access token and any associated refresh token.

2. 2

   Clear the token from the OS credential store

   Most MCP clients ship a "log out" or "disconnect" command per MCP. If yours does not, manually delete the entry from Keychain / DPAPI / libsecret using the client's service name.

3. 3

   Re-trigger the OAuth flow

   Open the MCP in your client. The client detects the missing token, opens the system browser, and walks you through OAuth 2.1 with PKCE. Approve the scopes.

4. 4

   Confirm the new tokens land in the credential store

   A new access + refresh pair should appear. Refresh-token rotation will handle subsequent renewals automatically.

5. 5

   Audit recent activity if the rotation was triggered by suspected compromise

   OAuth services typically expose an activity log keyed by the access token's session ID. Look for actions in the window between issue and revocation.

If the credential leaked into git

1. Revoke immediately — do not stop to remove the commit. Assume the key has already been scraped.
2. If the repo is public, GitHub\'s secret-scanning likely already pinged the upstream provider. Many providers (Stripe, GitHub itself, AWS) auto-revoke leaked tokens within minutes.
3. Issue a new credential with the same (or tighter) scope.
4. Update the MCP client config and restart.
5. Decide whether to rewrite git history. Public repo with a sensitive token: probably yes, but accept that any clone before the rewrite still has the secret. Private repo: usually not worth the disruption.
6. Audit upstream activity for the window between push and revocation.
7. Add a pre-commit hook (gitleaks, talisman, or similar) so this does not happen again.

Frequently asked questions