How do I keep API keys and tokens out of MCP client config files like mcp.json and claude_desktop_config.json?

What should I check, step by step?

1. Find every literal secret today: grep your client configs (~/.cursor/mcp.json, .cursor/mcp.json, .mcp.json, .vscode/mcp.json, ~/.claude.json and claude_desktop_config.json) for strings that look like keys, and run a scanner such as gitleaks over the repos and dotfile folders that contain them.

2. Claude Code: replace the value with "${GITHUB_TOKEN}" in .mcp.json; ${VAR:-default} works for non-secret settings like URLs. Its docs note that its own and cloud-provider credentials (ANTHROPIC_API_KEY, AWS_BEARER_TOKEN_BEDROCK, NPM_TOKEN and others) read as empty in a remote server's url and headers, so give each server its own variable name.
3. Cursor: use "${env:NAME}" in env, headers, args or url. Its docs offer envFile for stdio servers; if you use it, keep that file out of the repo and out of the project folder the agent can read.
4. VS Code: declare an inputs entry with type promptString and password: true and reference it as ${input:id}; VS Code prompts on first start and stores the value securely. Note its docs say input variables aren't supported in portable .mcp.json files.
5. Claude Desktop: prefer an MCPB extension whose manifest declares the key as user_config with sensitive: true, passed to the server as ${user_config.api_key} in env. For a hand-written server entry, point command at a launcher (op run --env-file with op:// references, or a script that reads your OS keychain) so the JSON never holds the value.
6. Remote servers: use the client's OAuth sign-in instead of a static bearer header where the server supports it. The MCP authorization spec is for HTTP transports; for stdio it says implementations should retrieve credentials from the environment, which is why the reference-plus-launcher pattern matters locally.
7. Shrink the blast radius: one token per server with the smallest scope (a fine-grained token for one repo, read-only where possible), with an expiry. Never reuse a personal account-wide token across servers.
8. Block regressions: gitleaks as a pre-commit hook and in CI, and GitHub secret scanning push protection on repos that hold configs. Keep .env and envFile paths in .gitignore.
9. If a key ever sat in plain text in a config, rotate it. Removing it from the file doesn't remove it from git history, backups, synced dotfiles or anything a server already read.

Why do MCP client config files like mcp.json leak API keys?

They are predictable files. The MCP Local Server Security guide calls client configuration files a known, predictable location on disk and says to keep long-lived secrets out of plaintext config, preferring the OS secret store (macOS Keychain, Windows Credential Manager, freedesktop Secret Service) where your client can reference it.

• They get shared. Project-scoped files such as .mcp.json, .cursor/mcp.json and .vscode/mcp.json are meant to be committed so a team gets the same servers, which is exactly how a pasted token ends up in git. Setup guides that show "API_KEY": "<your key>" encourage the paste.
• They are readable by the things you are trying to limit. A coding agent or a local MCP server running as your user can read the config file as easily as you can, unless a sandbox denies it.

How do Claude Code, Cursor, VS Code and Claude Desktop reference secrets in MCP config instead of storing them?

Claude Code: ${VAR} and ${VAR:-default} in a server's command, args, env, url or headers. /mcp and claude mcp list show the reference by name rather than the resolved value. For remote servers that need short-lived tokens, headersHelper runs a command at each connection and merges its JSON output into the request headers, so no token is stored in the file.

• Cursor: ${env:NAME}, plus ${userHome} and ${workspaceFolder}, resolved in command, args, env, url and headers; OAuth client secrets in the auth block can also be ${env:...} references.
• VS Code: ${input:id} backed by an inputs entry (promptString with password: true) prompts once and stores the value securely; envFile is supported in the VS Code format. Claude Desktop extensions: sensitive user_config values are masked at entry and stored securely, then substituted as ${user_config.KEY}.

How do short-lived, scoped credentials replace static API keys in MCP server config?

A reference moves the secret out of the file; it doesn't make the secret less valuable. The MCP guide's next step is short-lived credentials issued at launch time by a secrets manager or broker, and rotating anything a server held when you remove it.

• 1Password's op run loads op:// secret references and runs the command in a subprocess with the secrets as environment variables only for the life of that process, so the launcher pattern works for any client that can run a command.
• Where you control the API the server calls, issue the server a credential bound to its own key and configuration with a TTL in hours, and have the API verify and be able to revoke it per server, instead of trusting a bearer string copied into JSON.