MCP Server Not Getting Environment Variables: How to Fix It (Claude, Cursor, VS Code)

If your MCP server says an API key or variable is missing, but it works when you run it in a terminal, the client did not pass that variable. Desktop clients do not load your shell profile, and stdio servers inherit only a small set of variables. The fastest fix is to put the variable in the server's env block in the client's config file, using that client's own reference syntax, then fully restart the client.

Checked against: the MCP debugging guide, Claude Code's MCP docs, Cursor's MCP docs and the VS Code MCP configuration reference on 2 November 2026. eSEOspace did not run these steps.

What this error means

When a client starts a local server, it creates a new process with a fresh environment. The MCP debugging guide says the inherited set is "platform-dependent," and tells you to use the env key to provide your own values.

So a key that lives only in your terminal session never reaches the server. The server then fails at startup or on the first tool call. Typical messages include "API key not set," "missing required environment variable" or an HTTP 401 from the upstream service.

The same thing happens with remote servers when a header refers to a variable the client cannot see. The request goes out with an empty or literal ${VAR} value, and the server rejects it.

Quick fix

1. Find the exact variable names in the server's README.
2. Add them to the server's env block in the client config, not to your shell profile.
3. Use the reference syntax your client supports, or paste the literal value if the file stays private.
4. Check spelling and case. API_KEY and api_key are different variables.
5. Fully quit and reopen the client. A window reload is not always enough.
6. Read the client's MCP log for the server's first error line.

A minimal Claude Desktop block, from the debugging guide:

{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

Fix by client / OS

Claude Desktop

Put values in env inside claude_desktop_config.json. On macOS it is in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\ and on Linux in ~/.config/Claude/. On Windows, the local server guide shows one special case. If the log mentions ${APPDATA} in a path with an ENOENT error, add the expanded APPDATA value (for example C:\\Users\\user\\AppData\\Roaming\\) to env.

Claude Code

Add variables when you register the server:

claude mcp add myserver --env API_KEY=your-key -- npx -y @example/mcp-server

The Claude Code docs note two traps. --env takes several pairs, so if the server name comes right after it the CLI reads the name as another pair and rejects it. Put the name first or another option in between. And everything after -- goes to the server, so --env must come before it.

In a shared .mcp.json, you can reference variables as ${VAR} or ${VAR:-default} in command, args, env, url and headers. If a variable is unset and has no default, Claude Code still loads the server with the literal ${VAR} text and warns in claude mcp list and /mcp. An empty string counts as set, so ${VAR:-default} expands to empty, not to the default.

For remote servers, Claude Code reads some credential variables, such as ANTHROPIC_AUTH_TOKEN, as empty in url and headers. The docs say this stops a project file from sending your Claude credentials to a server it names. The server then usually returns 401. The docs list ANTHROPIC_API_KEY, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN among the covered names. Copy the value into a variable with your own name and reference that instead.

Cursor

Cursor's MCP docs support ${env:NAME} in command, args, env, url and headers, plus envFile for stdio servers:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": { "API_KEY": "${env:API_KEY}" }
    }
  }
}

The docs say envFile does not work for remote (HTTP or SSE) servers. Cursor's help page adds that variables from your shell profile must be available to Cursor, and to restart Cursor after you change the profile.

VS Code

In .vscode/mcp.json (the VS Code format) use ${env:NAME}, envFile, or an ${input:...} prompt that VS Code stores securely. The configuration reference says the portable .mcp.json format uses ${NAME} or ${NAME:-default} instead, and does not support envFile or input prompts. It also warns that VS Code's client "treats bare $NAME as literal text," so always use braces. For remote and container sessions, the variable must exist on the remote host.

macOS, Windows and Linux

On macOS, apps opened from the Dock or Finder do not read .zshrc. Launching the client from a terminal can work as a test, but the env block is the reliable fix. On Windows and Linux, the same rule applies: a value that exists only in one terminal session is not visible to an app started elsewhere. Put it in the config's env block or in a variable the client can see, then restart the client.

Where to find the logs

• Claude Desktop: ~/Library/Logs/Claude, %APPDATA%\Claude\logs or ~/.config/Claude/logs. The mcp-server-SERVERNAME.log file holds the server's stderr.
• Claude Code: claude mcp list and /mcp show missing-variable warnings. If a remote server's header references a covered credential variable, run claude --debug-file /tmp/claude-debug.log and search for never expanded toward a remote server, per the docs.
• Cursor: Output panel, then MCP Logs.
• VS Code: MCP: List Servers, select the server, Show Output.

If it still fails

• The server reads a config file instead. Some servers want a .env next to them. The debugging guide says the working directory "may be undefined (like / on macOS)," so use absolute paths.
• Docker in the middle. Values in env reach docker, not the container, unless you also pass -e NAME. See Docker MCP server not connecting.
• WSL in the middle. Windows variables do not cross into WSL by default. See WSL setup errors.
• Auth errors remain. If the value arrives but the service rejects it, follow fixing MCP 401 Unauthorized.

You can generate a clean block per client with the MCP config generator, and decode error codes with the MCP error code lookup.

Next step

Once keys reach the server, keep them out of shared files and chat logs. Our secret leakage guide covers safer storage. If your team needs a review of how servers and keys are set up, eSEOspace offers an MCP readiness audit.

Frequently asked questions