Try free

Last updated 13 October 2026

Store API keys for Claude MCP servers

The risk of hardcoding keys in MCP configuration

You need your MCP servers to talk to external services like GitHub, Slack, or a custom database. These services require authentication through API keys or tokens. If you paste a raw token directly into your server configuration, you risk exposing it. This risk increases if you share your project folder or commit your configuration files to a public repository. A leaked key can lead to unauthorized access or unexpected costs on your service accounts. You should treat your MCP configuration as code that requires the same security standards as your main application.

When you use Claude Code, the agent interacts with these servers to gather data or perform actions. If the configuration file contains plain text secrets, any person or process with read access to your file system can steal them. This is especially dangerous in collaborative environments where multiple developers might pull the same configuration. You need a way to provide these secrets to the agent without leaving them permanently written in a configuration file that might be shared or backed up insecurely.

Use environment variables in the MCP configuration file

The configuration file for MCP servers is .mcp.json and usually sits in your project root. This file defines how Claude Code launches each server. You can specify a command, arguments, and environment variables for each server. Instead of putting the key in the arguments list, you should use the env object within the configuration. This keeps the credentials separate from the execution command itself. It makes the configuration cleaner and easier to manage across different machines and development environments.

The structure of .mcp.json allows you to define an environment for each individual server. By placing your keys here, you ensure that only that specific server has access to the token. This follows the principle of least privilege. Even if one server is compromised or has a bug, your other services remain isolated. This method is much safer than passing keys as command line arguments, which might show up in process lists or shell history files where other users could see them.

Sourcing environment variables from your shell

To avoid keeping secrets in a project file at all, you can reference variables from your operating system. Set the environment variable in your shell profile, such as .bashrc or .zshrc. Use the export command followed by the variable name and the secret value. For example, you might export a variable named GITHUB-TOKEN. When you start a session with the claude command, the agent inherits these variables from your active shell. You can then configure .mcp.json to use these inherited values instead of hardcoding them.

This approach keeps your secrets in your personal shell environment where they belong. It ensures that your .mcp.json file remains safe to commit to version control because it does not contain any sensitive data. Other developers on your team can use the same configuration file but will provide their own keys through their own shell environments. This is the standard way to handle secrets in modern software development and it works perfectly with the way Claude Code launches MCP processes.

Project specific environment variables

Sometimes you have different keys for the same service depending on the project you are working on. You might have a development token for one repository and a production token for another. You can manage this by creating a .claude/settings.local.json file in each project folder. This file is intended for your own untracked overrides and should be added to your .gitignore file. It allows you to specify settings that apply only to that specific project on your local machine.

By using local settings files, you avoid the mess of having dozens of global environment variables in your shell profile. You keep the configuration close to the code it supports without the risk of pushing it to a remote server. When you run the claude command in that folder, it reads the local settings and applies them to the session. This gives you a high degree of control over how the agent authenticates with external tools while maintaining a clean and secure global environment.

Testing the MCP server connection

You can verify that your MCP server is correctly receiving the keys by using the /mcp slash command inside a session. This command lists active servers and their status. If a server fails to start because of a missing key, the status will show an error message explaining the failure. You can also run the claude mcp command from your terminal to manage the servers outside of an active coding session. This helps you isolate configuration issues before you start asking the agent to perform complex tasks.

If the agent cannot access a tool it needs, it might tell you that the tool is unavailable. Use the /doctor command to check the general health of your Claude Code installation. This command can identify if there are issues with how the agent is communicating with the MCP servers. Checking the logs or the status output frequently during setup saves time. It ensures that when you actually start coding, the agent has all the permissions and keys it needs to be effective.

Managing multiple project contexts

Managing many MCP servers across different projects can become confusing as your workflow grows. Each project might require a unique set of keys for different cloud providers or internal tools. adhdTerminal helps you keep these environments organized by running many Claude Code sessions side by side. Each session appears as a tile on a wall, and you can give each tile a specific name and color. This makes it easy to see which project is currently using which set of tools and keys.

With adhdTerminal, your tiles reopen in the same place after a restart. This means you do not have to reconfigure your environment every time you turn on your computer. You can have one tile dedicated to a project using a database MCP and another tile for a project using a cloud storage MCP. Each tile maintains its own session history and status, so you can monitor multiple agent tasks at once without mixing up your environment variables or terminal windows.

Updating and troubleshooting the setup

If you change your keys or update your shell profile, you might need to restart your terminal or your Claude Code session. The agent needs a fresh environment to see the new exported variables. You can run the claude update command to ensure you are using the latest version of the tool, which might include improvements to how MCP servers are handled. If an MCP server still refuses to connect, double check the names of the environment variables in your .mcp.json file to ensure they match exactly what the server expects.

Sometimes the issue is not the key itself but the permissions granted to the agent. Use the /permissions command to see if the agent is allowed to use the tools provided by the MCP server. You can change these settings in your settings.json file under the permissions key. If you have set the mode to plan, the agent will describe what it wants to do without executing the tool. This is a good way to verify that the agent is trying to use the correct MCP server before you grant it full access.

Security best practices for local development

Always review what information your MCP servers can access. Even with secure key storage, an agent with too much power can cause problems. You should use the default or plan permission modes when testing a new MCP configuration. This allows you to see exactly how the agent intends to use your API keys. If you are comfortable with the behavior, you can switch to acceptEdits or bypassPermissions for a faster workflow. You can cycle through these modes easily by pressing Shift+Tab inside a session.

Avoid using your most powerful administrative keys for local development. Most services allow you to create restricted tokens that only have access to specific repositories or actions. Use these limited tokens with your MCP servers whenever possible. If a token is ever compromised, the potential damage is restricted to a small part of your infrastructure. This layered security approach is the best way to use powerful coding agents like Claude Code safely and effectively.

Security is a continuous process

As you add more MCP servers to your workflow, the complexity of your configuration will increase. It is helpful to periodically run /cost and /usage to see if your MCP-enabled tasks are consuming more resources than expected. Sometimes an incorrectly configured server might retry connections or perform repetitive tasks that drive up costs. Monitoring the last exchanges of a conversation can help you spot these patterns early. Keeping a close eye on the agent helps you maintain both security and efficiency.

If you need to start over with a fresh environment in the same folder, you can use the /clear command. This wipes the current session history but keeps your MCP configurations intact. It is a quick way to test if a configuration change has fixed a problem without leaving the terminal. By following these steps to secure your API keys and manage your environment variables, you can build a powerful and safe development setup that leverages the full capabilities of Claude Code.

Questions people ask

How do I refresh an MCP server after updating an API key in my shell?

You must restart the Claude Code session to pick up new environment variables from your shell. Exit the current session by pressing Ctrl+C and then start it again using the claude command. The agent will then inherit the updated variables and pass them to the MCP servers upon launch.

Can I store my MCP keys in the global ~/.claude/settings.json file?

While you can store some settings there, it is better to keep API keys in environment variables or a local .claude/settings.local.json file. This prevents your secrets from being stored in a plain text configuration file that applies to every project. Using environment variables is the most secure and standard way to handle these credentials.

What should I do if the agent says it cannot find a specific MCP tool?

First, run the /mcp command to check if the server is running and if any errors are reported. If the server is not active, check your .mcp.json file for syntax errors or missing environment variables. You can also run claude doctor to ensure your overall installation and path configurations are correct.

Read next

More on claude code basics·All posts