Last updated 13 October 2026
How to connect MCP servers to Claude Code
Claude Code requires external context to solve real world problems
Claude Code often lacks the specific context of your running environment. You might find yourself copying and pasting database schemas or API responses into the terminal just so the agent can understand the state of your project. This manual process is slow and often leads to mistakes because the agent does not have a live connection to your data. When you work on complex systems, the agent needs more than just your source code to be effective.
The Model Context Protocol solves this by creating a bridge between the agent and external services. This protocol allows you to connect servers that provide specialized tools for tasks like searching the web or querying a database. Instead of being limited to local file operations, the agent can now use these servers to fetch real-time data. This makes the agent much more capable during debugging or when you are exploring a new codebase that relies on external infrastructure.
Configuration happens in the mcp json file
The configuration for these connections lives in a file called .mcp.json. You can place this file in your project root to keep tools specific to one repository, or in your home directory to make tools available across all your work. The file defines how the agent should start each server, including the command and any necessary environment variables. If you need to provide an API key for a search service, you add it to the environment section of this JSON file.
The agent reads this configuration whenever you start a new session. If you have several servers defined, they will all be initialized when the agent begins its work. You should organize your .mcp.json file to only include the servers you actually need for a given project. Including too many tools can make the agent less efficient as it has more options to consider for every prompt you send. Keeping the configuration local to the project folder is the best way to maintain this focus.
Use the command line to add and remove servers
You can manage your server list using the claude mcp command in your terminal. This is an interactive tool that helps you add or remove servers without manually editing JSON files. When you run this command, you can provide the name of the server and the exact command needed to run it. This is helpful for ensuring that the paths and arguments are correct before you start a long coding session.
The tool also helps you verify that a server is working. If a server requires a specific runtime like Node or Python, the management command will check if those are available. It acts as a gatekeeper to prevent you from adding broken configurations. Using this command is the safest way to modify your global or local settings because it handles the file formatting and basic validation for you.
Control your tools from within an active session
Inside a running session, you have access to the /mcp slash command. This command provides a quick overview of every server currently connected to the agent. It lists the tools each server provides and shows their current status. If you suspect a tool is not working as expected, this command will tell you if the server process is still running or if it has encountered an error.
The agent uses these tools automatically when it determines they are needed for your request. For example, if you ask the agent to find the latest version of a library, it will look for a tool that can perform a web search. You will see the agent call the specific MCP tool in the terminal log. This transparency allows you to see exactly what data the agent is fetching and how it is using the external servers you have provided.
Project specific instructions in CLAUDE md
You can further guide the agent by using the CLAUDE.md file in your repository. This file holds the project instructions and is the best place to tell the agent when to use specific MCP tools. If you have a database server connected, you can add a rule in CLAUDE.md that tells the agent to always verify the table structure before writing a new SQL query. This ensures the agent uses the tools in a way that aligns with your project standards.
If your project has different parts, you can place a CLAUDE.md file in a subdirectory. The agent will follow the instructions in that specific folder when it works on those files. This is useful for large monorepos where one folder might need a web search tool for frontend documentation while another folder requires a database tool for backend logic. By combining .mcp.json for the connections and CLAUDE.md for the instructions, you create a highly tailored environment for the agent.
Manage permissions for external tool use
Security is a major factor when you connect the agent to external data. Claude Code uses different permission modes to control how tools are executed. The default mode requires you to approve any action that an MCP tool takes. You will see a prompt in the terminal explaining what the tool wants to do, such as querying a specific database table or fetching a URL. You can then choose to allow the action or deny it.
If you want to speed up your work, you can use Shift+Tab to cycle through the permission modes. The bypassPermissions mode allows the agent to run tools without asking for your consent each time. This is useful for trusted servers in a local development environment. You can also fine-tune these settings in the .claude/settings.json file. Under the permissions key, you can specify which tools should always require approval and which can be run automatically, giving you precise control over the agent's behavior.
Monitor costs and usage of external services
Using external servers can impact the cost of your sessions. Every time an MCP tool returns data, that information is added to the session context. If a tool returns a massive amount of JSON or a long documentation page, it uses up tokens. You can monitor this by using the /cost and /usage commands. These commands show you exactly how many tokens you have used and the estimated cost of the current session.
When the context window gets too crowded with data from your tools, the agent might lose track of the earlier parts of your conversation. You can use the /compact command to resolve this. It summarizes the work done so far and clears the detailed tool outputs from the window. This keeps the agent fast and reduces the cost of subsequent prompts. It is a good habit to run this command after a heavy sequence of data fetching or web searching.
Handle multiple server environments with adhdTerminal
Developers often work on multiple projects that require different MCP configurations. Managing these separate sessions in standard terminal tabs can lead to mistakes. The adhdTerminal app provides a better way to handle this by running many Claude Code sessions side by side as tiles on a wall. Each tile can be dedicated to a specific service or task, with its own project-specific MCP servers and instructions. This app is a native tool for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic.
A tile in adhdTerminal has a color, a number, and a name, which helps you stay organized. The app shows the last few exchanges of each conversation and indicates whether a session is working or waiting for your input. This is especially helpful when you are running a long task on one MCP server, like a full database scan, and want to work on something else in a different tile. The app costs 99 dollars once and includes a free iPhone app that mirrors your wall over an end to end encrypted link, letting you monitor your tools from anywhere.
Troubleshooting the MCP connection
If you encounter problems with your MCP servers, the claude doctor command is your first line of defense. It runs a series of checks on your installation and your configuration files to find errors. It can detect if a server command is invalid or if there are permission issues preventing the agent from starting the process. This command saves you time by identifying common setup mistakes that are hard to see in the JSON files.
Keeping your tools updated is also important for stability. You can run claude update to ensure you have the latest version of the agent, which often includes improvements to how MCP servers are handled. If a specific server is still failing, check the .mcp.json file for any missing environment variables or incorrect paths. You can always restart a session with /clear if the agent state seems corrupted, though this will start the conversation over. Regular maintenance of your configuration files and tool versions ensures a reliable connection to your external data.
Questions people ask
How do I add an API key for an MCP server?
You add the API key to the environment variables section of the .mcp.json file. You can do this manually or by using the claude mcp command to configure the server. The agent will then pass these variables to the server process when it starts.
Can I use MCP servers on a remote server?
Claude Code runs the MCP servers as local processes on the same machine where the agent is running. If you need to access a remote database, the MCP server itself must be configured to connect to that remote host. The agent communicates with the server locally, and the server handles the remote connection.
Why are my MCP tools not appearing in the session?
First, check if the server is listed in the /mcp command output. If it is missing, verify the .mcp.json file exists in your project root or home directory and has the correct syntax. You can also run claude doctor to see if there are any errors preventing the servers from loading.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.