Try free

Last updated 13 October 2026

How to add environment variables to MCP servers

Environment variables for MCP servers

Your MCP servers need specific environment variables to function correctly. When you integrate a new tool into Claude Code, you often find that it requires a secret key or a specific configuration path to communicate with an external service. Without these variables, the server might start but fail silently or throw errors when you try to use a tool like WebSearch or a custom database connector. You must ensure these variables are available to the process that runs the server. This is a common hurdle for developers who want to expand the capabilities of their coding agent beyond local file manipulation.

Environment variables act as the bridge between the Claude Code environment and the external world. They hold sensitive data like authentication tokens, project identifiers, and service endpoints. If you are building a custom MCP server to interact with your company internal API, you will likely need to pass headers or credentials through these variables. Setting them up correctly ensures that the agent can read and write data as needed without you having to manually intervene every time a network request is made.

Configuration file locations

Claude Code looks for MCP server configurations in a specific file named .mcp.json. This file typically sits in the root of your project directory or in your home directory. If you place it in the project root, the configuration only applies to that specific repository. This is useful for project-specific tools like a local database explorer or a specialized build script. If you place it in your user home directory, the servers are available across all your projects, which is ideal for general-purpose tools like a global search engine or a documentation reader.

The location of the .mcp.json file determines the scope of the tools available to the agent. When you run the claude command, the agent searches for this file to understand which external servers it can start. If you have a global configuration and a project-local configuration, the agent combines them. This allows you to have a set of core tools that are always available while adding specialized tools for individual codebases. Understanding this hierarchy is the first step in creating a reliable and flexible development environment.

The structure of the configuration file

The .mcp.json file is a standard JSON object that defines how the agent interacts with external processes. It contains a section for mcpServers where each key represents a unique name for a server. Inside each server object, you define the command to run and the arguments to pass to that command. To add environment variables, you include an env key. This key points to another object where each property is the name of an environment variable and its value is the actual string you want to pass to the server process.

For example, if you are configuring a server that requires an API key for a weather service, your .mcp.json might have a server named weather-service. Under that name, you would add an env object containing a key named WEATHER-API-KEY. The value would be your actual secret key. When Claude Code starts the weather-service, it injects this key into the process environment. The server can then access the key using standard language-specific methods. This structure keeps the command line arguments clean and focuses on secure data passing.

Securely handling sensitive keys

You should avoid committing plain text API keys to your version control system to protect your credentials. While .mcp.json is a convenient place to store configuration, it is often tracked by git in collaborative projects. To keep your keys safe, you can use environment variables that are already present in your shell. Claude Code can inherit variables that are active in the terminal session where you launch the command. If you export a variable in your shell configuration file like .zshrc or .bashrc, the MCP server can often access it without you hardcoding it into the JSON file.

Another layer of security involves using local files that are never shared. You can place your sensitive configurations in a file that is specifically ignored by your version control system. This ensures that even if you accidentally share your project code, your private keys remain on your local machine. Managing these secrets effectively is a critical skill for any developer using automated agents, as these agents often require broad access to perform their tasks. You must balance the need for the agent to be productive with the need to keep your development environment secure.

Local settings for individual overrides

If you need to store secrets on your machine without putting them in the main configuration, you can use .claude/settings.local.json. This file is intended for your own untracked overrides and is a great place for user-specific settings. You can specify environment variables here that you do not want other team members to see or that are unique to your local development setup. Always ensure that .claude/settings.local.json is listed in your .gitignore file to prevent accidental leaks. This approach allows you to have a shared base configuration while keeping individual secrets private.

This local settings file is part of a larger system of configuration that Claude Code uses to manage its behavior. By using .claude/settings.local.json, you can customize how the agent behaves on your machine without affecting the rest of the team. This is particularly useful for setting up paths to local binaries or specifying API keys for services that only you use. It provides a clean separation between project-wide requirements and personal environment preferences, which makes it easier to maintain a consistent setup across different development machines.

Interactive management with slash commands

Inside a Claude Code session, you can manage your MCP servers using the /mcp command. This command is an interactive tool that allows you to view the current status of your servers and see which ones are active or failing. If you update your .mcp.json file while a session is running, you might need to restart the session or use the command to refresh the configuration. This ensures that the agent sees the latest environment variables you have added and can use the updated tools immediately.

The /mcp command provides a window into the background processes that power the agent tools. It lists the available servers and tells you if they are connected properly. If a server requires an environment variable that is missing, the /mcp interface might show an error or a disconnected status. This feedback is essential for debugging configuration issues. By regularly checking the status of your servers, you can ensure that the agent has all the resources it needs to help you with your coding tasks.

Verifying the installation and health

If your environment variables do not seem to work, you can use the claude doctor command from your terminal. This command performs a series of checks on your installation and configuration to identify common problems. It can find issues with your setup, such as incorrect file paths or missing permissions, and help you understand why a server might be failing to start. It is a good first step when you suspect that a path or a variable is not being passed correctly to the MCP process.

The doctor command is designed to be a comprehensive diagnostic tool. It checks the health of the Claude Code installation and ensures that all necessary components are functioning. When you run it, the command scans your configuration files and your environment to look for inconsistencies. If it finds a problem with your .mcp.json file or your environment variables, it will provide feedback that can guide you toward a solution. This saves you time by automating the troubleshooting process and pointing you directly to the source of the error.

Managing many projects with adhdTerminal

When you work on many different projects at once, managing multiple .mcp.json files can become complex. Each project might require its own set of API keys for different services, and switching between them can lead to confusion. This is where adhdTerminal helps by letting you run many Claude Code sessions side by side on a single wall. Each tile can represent a different project with its own specific environment and configuration. You can see at a glance which session is working and which one is waiting for your input, making it easier to track which API keys are active in which context.

By using adhdTerminal, you can keep your project environments isolated yet visible. The app shows the last exchanges of each conversation and provides status updates for every tile. This visual overview is particularly helpful when you are testing MCP servers across different repositories. You can monitor the performance and output of multiple servers simultaneously without having to constantly switch terminal tabs. This setup improves your workflow by providing a high-level view of all your active coding sessions and their associated tools.

Best practices for naming variables

Always use clear and descriptive names for your environment variables to avoid collisions between different servers. Many MCP servers follow a convention of using uppercase letters with underscores for their variables. If a server expects a specific variable like DATABASE-URL or API-KEY, ensure the spelling matches exactly what the server documentation requires. A single typo in a variable name can prevent the server from connecting to its data source, leading to errors that might be difficult to trace.

You can also use the /config command inside a session to inspect some of your settings, though the environment variables themselves are usually handled at the process level before the session starts. If you find yourself frequently changing environment variables, consider creating custom slash commands in .claude/commands to automate repetitive setup tasks. This allows you to create a more streamlined development experience where the tools you need are always ready to go. Proper management of your environment variables is the foundation of a powerful and efficient coding agent setup.

Questions people ask

Can I use shell variables inside the .mcp.json file?

You cannot use shell expansion like $SECRET_KEY directly inside the JSON file. You must either put the literal string in the env object or ensure the variable is exported in your shell before running Claude Code. The agent will inherit the environment of the terminal where it was started.

How do I refresh a server after changing its environment variables?

You can use the /mcp command to see the status of your servers. If a change does not take effect, the most reliable way is to quit the current session and start a new one. This forces the agent to reload the .mcp.json file and restart the server processes with the new environment.

Is there a way to hide keys from my screen during a session?

Claude Code generally does not print the values of your environment variables to the terminal unless a tool specifically outputs them. You can use /clear to remove previous conversation history from your view if you are worried about sensitive data being visible. For more control, ensure your MCP servers are designed to handle secrets quietly without echoing them.

Read next

More on claude code basics·All posts