Configure MCP Server Environment Variables: Setup and Security Guide

Quick Answer

• MCP server environment variables are configured through the env block in your MCP Host's JSON configuration file (e.g., claude_desktop_config.json or Cursor settings)
• First checks: verify the env block exists for your server, confirm variable names match exactly (case-sensitive), and ensure the configuration file is valid JSON
• Minimal fix: add an "env": { "API_KEY": "your-key-here" } block to your server configuration, then restart the MCP Host completely
• Applies to all MCP Hosts (Claude Desktop, Cursor, etc.) and any MCP server requiring authentication tokens, database URLs, or logging configuration

What Problem It Solves

MCP servers often need external configuration values: API keys for third-party services, database connection strings, logging verbosity levels, or result limits. Hardcoding these values into server code creates security risks and maintenance headaches. The environment variable configuration pattern solves this by letting you inject configuration at startup through the MCP Host's JSON configuration file, keeping sensitive values out of version control and allowing different settings per environment.

Minimal Working Configuration

The core pattern is an env block inside your server's configuration object. Here is a complete example for a custom server and two popular third-party servers:

JSON
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["./mcp-servers/my-server/dist/index.js"],
      "env": {
        "API_KEY": "sk-your-api-key-here",
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb",
        "LOG_LEVEL": "info",
        "MAX_RESULTS": "50"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects",
        "/Users/yourname/documents"
      ]
    }
  }
}

The filesystem server shows that not all servers require environment variables—only add the env block when the server expects it.

Parameters and Environment Variables

The following parameters are available for environment variable configuration:

Variable names are case-sensitive. GITHUB_PERSONAL_ACCESS_TOKEN is not the same as github_personal_access_token.

Common Errors and Fixes

Server reports missing environment variable

Error: API_KEY environment variable is not set or similar missing variable message

Fix: Verify the env block in your MCP Host configuration contains the required variable with the exact name the server expects. Check for case mismatches—GITHUB_TOKEN and github_token are different variables. Restart the Host after making changes.

Configuration changes do not take effect

Error: After editing the configuration file, the server still uses old environment variable values

Fix: MCP Hosts read environment variables only at startup. You must fully exit and restart the application:

• Claude Desktop: Quit completely and relaunch
• Cursor: Run Cmd+Shift+P → Reload Window

Saving the configuration file alone does not trigger a reload.

npx-based server fails to start

Error: npx: command not found or the server package cannot be loaded

Fix: Ensure Node.js and npm are installed and npx is available in your system PATH. Verify the command field is "npx" and args includes "-y" followed by the correct package name. For globally installed packages, try npm install -g <package> first.

JSON syntax error in configuration file

Error: Host cannot parse the configuration file

Fix: Validate your JSON format. Common issues include trailing commas, unquoted keys, and unquoted string values. Ensure the env block uses object syntax ({}), not an array ([]).

Production Notes and Security Checks

Environment variables in MCP Host configuration files are stored as plain text. This introduces several security considerations for production deployments:

Critical limitations:

• Values are stored in plaintext JSON—set file permissions to restrict access (Unix: chmod 600 config.json)
• System environment variables (like $HOME or %PATH%) cannot be referenced; all values must be literal strings
• Configuration changes require a full Host restart—no hot-reload support
• For npx-based servers, environment variables pass through the npx subprocess, which may be affected by npx caching
• In multi-user environments, configuration files may be readable by other users

Security recommendations:

• Never commit configuration files with real secrets to version control—use template files (e.g., config.template.json) instead
• Add configuration files to .gitignore
• Rotate API keys regularly and restart the Host to apply new keys
• For high-security environments, use a wrapper script that fetches temporary credentials from a secrets manager (AWS Secrets Manager, HashiCorp Vault) and writes them to the env block before starting the Host
• Consider using encrypted file systems for storing configuration files

FAQ

Q: Can I reference system environment variables (like $HOME or %PATH%) in the MCP Host configuration file?

A: No. The env block in MCP Host configuration files accepts only literal string values. Variable substitution is not supported. For example, "DATABASE_URL": "$HOME/db.sqlite" will not work. If you need to use system environment variables, write a wrapper script (shell or batch) that reads the system variables and passes them to the server, then point the command field to that script.

Q: How do I safely manage production MCP server secrets?

A: For production environments: 1) Never commit configuration files containing real secrets to version control—use template files with placeholder values; 2) Set configuration file permissions to owner-only read (Unix: chmod 600); 3) Consider using an external secrets manager (HashiCorp Vault, AWS Secrets Manager) with a startup script that fetches temporary credentials and populates the env block; 4) Rotate keys regularly and restart the Host to load new values; 5) For high-security needs, store configuration files on encrypted file systems.

Q: Do MCP servers support hot-reloading environment variables without restarting the Host?

A: No. Environment variables are injected into the MCP server process at startup and cannot be changed at runtime. After modifying the configuration file, you must fully restart the MCP Host (quit and relaunch Claude Desktop, or Reload Window in Cursor). This is a fundamental limitation because environment variables are a process-level concept in operating systems. If your server needs dynamic configuration, implement an internal polling or listener mechanism within the server code itself.