Secrets with Environment Variables

MCP servers connect Claude to real systems — GitHub, databases, internal APIs. Each connection needs credentials: tokens, API keys, passwords.

The architect's rule is absolute: secrets never live in committed files. Your .mcp.json (project scope, shared in version control) declares which servers exist and how to launch them — but a raw token written there is now in your git history forever.

The clean pattern is to reference a secret by environment-variable name and let the runtime resolve it. This lesson shows how MCP does exactly that with ${GITHUB_TOKEN}.

MCP configuration lives in two distinct scopes, and the distinction drives where secrets are safe:

• Project scope — .mcp.json at the repo root. Shared via VCS so the whole team gets the same servers.
• User scope — ~/.claude.json. Personal, on your machine only, NOT shared.

Because project scope is committed, anything you put in .mcp.json is visible to everyone with repo access — including a leaked clone. That is precisely why a token's value must never appear there; only a reference to an env var may.