MCP Credential Management: How to Stop Handing Secrets to Every Endpoint

Every MCP server an employee connects to needs a way into the system behind it: a GitHub token, a database password, a Jira API key. In most organizations today, that credential is pasted into a configuration file on the employee's laptop. Multiply that by every developer and every tool, and you have a secrets inventory that nobody owns, nobody rotates, and nobody can revoke in one place.

MCP credential management is the discipline of deciding where those secrets live, who can read them, what they can reach, and how quickly they can be taken away. This guide walks through where the credentials sit today, what goes wrong, and a practical model for moving them off the endpoint.

Where MCP credentials actually live

An MCP client — Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Codex — reads a list of servers from a configuration file. Each entry has one of two credential slots:

• env for local (stdio) servers. The client launches the server as a process on the employee's machine and passes these values as environment variables.
• headers for remote (HTTP) servers. The client sends these values with every request, typically an Authorization header carrying a bearer token.

A typical entry looks like this:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_…" }
    }
  }
}

That token is now stored in plaintext in a file on disk. The common locations are:

• Claude Code: ~/.claude.json (user) and .mcp.json (project)
• Cursor: ~/.cursor/mcp.json (global) and .cursor/mcp.json (project)
• VS Code: .vscode/mcp.json (project)
• Claude Desktop: claude_desktop_config.json under the user's application-support directory
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Codex: ~/.codex/config.toml

Note the project-level files. They exist so a team can share the same server setup, which means they are designed to be committed to a repository.

What goes wrong

Secrets committed with the project

A developer adds a server to .mcp.json so a colleague can use it, and the token comes along. Once pushed, the credential is in the repository's history and in every clone and fork, and removing it from the latest commit does not remove it from history. Rotation is the only real fix.

Personal, broad, and long-lived

The fastest way to get an agent working is to reuse the credential the employee already has. That credential carries the employee's full permissions, often has no expiry, and is not tied to the agent that uses it. The agent may only need to read issues, but it holds a token that can also delete repositories.

No inventory, so no rotation

Security teams cannot rotate what they cannot see. When credentials are spread across local files on hundreds of machines, there is no list of which secrets exist, which systems they reach, or who owns them. That is also why these credentials tend to outlive the people who created them — the lifecycle problem covered in MCP credentials and employee offboarding.

Secrets leaking through the conversation itself

Credentials do not only leak from config files. A tool result can contain a connection string, an .env file, or an API key the agent read from a repository. Once it is in the model's context, it can be repeated in an answer, passed to another tool, or stored in a log. Managing MCP credentials therefore also means watching what flows through tool calls, not only what sits in configuration.

A five-level model for MCP credential management

Most organizations will not move every server to the ideal design at once. It is more useful to know where each server sits today and what the next step is.

1. Level 0 — Plaintext in the config file. The default. The secret is on disk, readable by anything running as the user, and easy to commit by accident.
2. Level 1 — Referenced, not pasted. The config points at an environment variable instead of containing the value. Support for variable references differs between clients, so check each client's documentation. This keeps secrets out of shared files, but the value still lives in the user's environment.
3. Level 2 — Injected from a secrets manager. A small wrapper fetches the credential from the OS keychain or a secrets manager at launch and starts the server with it. Nothing sensitive is stored in the config, and rotation happens in one place.
4. Level 3 — OAuth for remote servers. For HTTP servers that implement the MCP authorization specification, the client obtains short-lived tokens bound to that specific server and to the user's identity. Disabling the identity stops new tokens. There is no static key to store.
5. Level 4 — Credentials held by a gateway. Employees connect to a central MCP gateway, and the gateway holds the downstream credentials, encrypted, on the server side. Endpoint configuration contains the gateway address and nothing that grants access to a downstream system. Access, policy, and audit sit in one place.

Levels 3 and 4 work together: OAuth is the right way for a person to reach a server, and a gateway is the right place to keep the credentials that the server itself uses to reach GitHub, a database, or a ticketing system.

Building the program

1. Inventory. Find every MCP configuration file on managed endpoints and in repositories. Record the server, the client, the transport, and whether a credential is present. Do not copy the secret values into the inventory itself.
2. Classify by blast radius. A read-only documentation server and a server with write access to production data are not the same risk. Prioritize the servers whose credentials could change or export sensitive data.
3. Replace personal credentials with dedicated ones. Give each server its own service account or app with the narrowest scope that works — read-only where possible — and a named owner.
4. Move the secret off the endpoint. Use OAuth where the server supports it, and a secrets manager or gateway everywhere else.
5. Define rotation and revocation. Set rotation by the access each credential grants, rotate immediately on exposure or when an owner leaves, and test that a revoked credential actually stops working.
6. Inspect tool traffic. Scan tool arguments and results for secrets and sensitive data so that a credential read by an agent does not travel onward through the conversation.
7. Keep an audit trail. Record which identity called which tool, when, and with what outcome, so an investigation does not depend on reconstructing activity from local machines.

MCP credential management checklist

• No secrets in project-level MCP files committed to repositories.
• Repository secret scanning covers .mcp.json, .cursor/mcp.json, and .vscode/mcp.json.
• Every MCP server credential has a named owner and a purpose.
• Agents use dedicated, least-privilege credentials, not an employee's personal token.
• Remote servers use OAuth where the server supports it.
• Downstream credentials are stored in a secrets manager or gateway, not on endpoints.
• Rotation and revocation are defined per credential and tested.
• Tool arguments and results are scanned for secrets.
• Tool calls are logged centrally with the calling identity.

Where ContextGuard fits

ContextGuard is a Level 4 design. Its MCP gateway sits in front of your approved MCP servers and holds their credentials on the server side: environment variables for local servers and headers for remote servers are encrypted at rest and write-only, and revealing a stored secret is restricted to administrators. Employee machines are configured with the gateway's address and the caller's directory identity, not with the downstream tokens.

Every tool call then passes through one place where you can allow, inspect, or block a tool, scan arguments and results for secrets and sensitive data, limit which servers each directory group can see, cut off a session or a specific client, and keep a record of who called what. ContextGuard's discovery scan also inventories the MCP servers configured across Claude Code, Cursor, VS Code, and Claude Desktop, which is where most programs have to start. See the platform architecture for the full model.

FAQ

Where are MCP credentials stored by default?

Usually in the MCP client's configuration file on the employee's machine: an env block for local stdio servers or a headers block for remote HTTP servers. Unless the client or a wrapper resolves them from somewhere else, those values sit on disk in plaintext.

Is it safe to commit a project-level MCP configuration file?

Only if it contains no secrets. Project files such as .mcp.json, .cursor/mcp.json, and .vscode/mcp.json are designed to be shared, which is exactly why a token pasted into one can end up in a repository, its history, and every clone.

Does OAuth solve MCP credential management?

For remote HTTP servers that implement the MCP authorization specification, OAuth replaces long-lived static keys with short-lived, audience-bound tokens tied to a real identity. It does not cover local stdio servers, which still read credentials from their environment, and it does not decide what the server itself uses to reach downstream systems.

How often should MCP credentials be rotated?

Set rotation by the access a credential grants rather than by a single calendar rule, and rotate immediately when an owner leaves or a credential may have been exposed. The larger goal is to remove long-lived credentials from endpoints entirely, so there is less to rotate.