Using Environment Variables in MCP Config

MCP servers often need secrets: API keys, tokens, connection strings. You should never hardcode those into config that's shared or committed. Claude Code gives you two clean ways to supply them.

Pass a value with --env

For a local stdio server, you can inject an environment variable into the server process with --env when you add it:

claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=KEY -- npx -y airtable-mcp-server

The server starts with AIRTABLE_API_KEY set in its environment, and it reads the key from there.

Expand variables in .mcp.json

For project-scoped servers stored in .mcp.json, you don't want the raw key in the file, because the file is checked into git. Instead, reference an environment variable with ${...} expansion:

{
  "mcpServers": {
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

When Claude Code loads the server, it replaces ${AIRTABLE_API_KEY} with the value from your environment. The committed file holds only the variable name, and each teammate supplies their own real key.

Set the variable

Before starting Claude Code, make sure the variable exists in your shell, for example by exporting it in your profile or loading it from a local, gitignored file. If a server fails to connect after you pull a shared .mcp.json, a missing environment variable is a common cause: check that the key is actually set. This pattern keeps secrets out of version control while letting the whole team share one server definition.