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.

In .mcp.json you pass credentials through the server's env block, using ${VAR} expansion. The literal text ${GITHUB_TOKEN} is committed safely — the real token is resolved from the environment at launch time.

Here the GitHub MCP server receives its token without the secret ever touching the file.

The reference ${GITHUB_TOKEN} is inert until the runtime supplies the actual value. You provide it through your shell environment — typically from a local, git-ignored .env file or your OS secret store.

The token is set outside the repo. The committed config stays clean; each developer (and each CI runner) injects their own value.

Referencing an env var is only half the defense. You must also guarantee the file holding the real value never gets committed.

Add your secret files to .gitignore. Commit an example file with placeholder names so teammates know which variables to set — without ever shipping the values.

Scope also decides whose credential is used:

• A shared service token the whole team uses can be referenced in project .mcp.json — each member still supplies the value via their own environment.
• A purely personal token (your individual PAT) fits naturally with user scope ~/.claude.json, which isn't shared anyway.

Either way the principle holds: the file may contain the name; the environment supplies the value. Never invert that.

For standard integrations — GitHub, Postgres, Slack, filesystem — prefer a maintained community MCP server over a custom one. They already implement the env-based secret handling correctly, expose proper Tools/Resources/Prompts, and return structured errors.

Writing your own server just to call GitHub means re-implementing auth and token handling you could inherit safely. Reserve custom servers for genuinely proprietary systems.

In a pipeline there is no developer .env to source. Instead, your CI platform's encrypted secret store injects the variable into the job environment, and the same ${GITHUB_TOKEN} reference resolves identically.

This is why the reference pattern matters: one committed .mcp.json works locally and in CI, with the value sourced differently in each place — and never printed.

An MCP token inherits whatever permissions you granted it. A GitHub PAT scoped to repo can push code; one scoped to read:org cannot.

Mirror the architect's least-privilege habit from tool and subagent design: grant each token only the scopes its server actually needs. If ${GITHUB_TOKEN} ever leaks despite your safeguards, a tightly scoped, short-lived token limits the blast radius dramatically.

Treat any committed secret as compromised — even after you delete it, it remains in git history. The only real fix is to revoke and rotate the credential at its source (GitHub settings), then re-issue a fresh one into your environment.

Because your config references ${GITHUB_TOKEN} rather than embedding a value, rotation is painless: revoke the old token, update the env var, relaunch. No code change, no commit.

The complete, exam-grade pattern for MCP secrets:

• Declare the server in project .mcp.json (shared via VCS).
• Reference the secret as ${GITHUB_TOKEN} in the env block — never the raw value.
• Supply the value from a git-ignored .env locally and from an encrypted store in CI.
• Ignore secret files; commit only an .env.example of names.
• Scope tokens to least privilege and rotate on any suspicion.

Config is shareable; secrets are not. That separation is the whole game.

Apply the secret-handling rules to a real team scenario.

Key takeaways:

• MCP config has two scopes: project .mcp.json (shared via VCS) and user ~/.claude.json (personal).
• Committed config may hold a reference like ${GITHUB_TOKEN} — never the token value.
• Real values come from a git-ignored .env locally and an encrypted secret store in CI; commit only an .env.example of names.
• Prefer community MCP servers — they handle env-based secrets correctly out of the box.
• Scope tokens to least privilege; on any leak, revoke and rotate at the source — the reference pattern makes rotation a one-line env change.

Separate the shareable from the secret, and you've internalized the rule the exam is testing.