What Is MCP and Why Does It Matter for Claude Code?
Claude Code is powerful out of the box. It can read and write files, run bash commands, search your codebase, and reason across your project. But its default toolset is limited to what lives on your local machine.
Model Context Protocol (MCP) changes that. MCP is an open protocol developed by Anthropic that lets Claude connect to external servers, expose new tools, and interact with services far beyond the filesystem. Think of it as a plugin system for Claude Code.
Without MCP, Claude Code knows about your files. With MCP, it can query your database, file GitHub issues, search the web, fetch Notion docs, and interact with any service that has an MCP server.
MCP turns Claude Code from a local coding assistant into a connected development environment that reaches across your entire stack.
How MCP Works in Claude Code
MCP follows a client-server model. Claude Code acts as the MCP client. External MCP servers expose tools that Claude can call during a session. The protocol handles communication between them.
Each MCP server defines a set of tools with names, descriptions, and input schemas. Claude reads those definitions at startup and can invoke them during a conversation just like it invokes built-in tools such as Bash or file read.
The practical result: when you install a Supabase MCP server, Claude gains tools like query_table, list_tables, and execute_sql. It uses those tools automatically when you ask it database-related questions.
The Two Configuration Locations
MCP servers are configured in JSON files. Claude Code reads from two locations depending on scope.
| Config file | Scope | Location |
|---|---|---|
claude_desktop_config.json | Global (all projects) | ~/.config/claude/ on Linux, ~/Library/Application Support/claude/ on macOS |
.mcp.json | Project-level | Root of your project directory |
Use the global config for servers you want available everywhere: filesystem access, web search, or productivity tools. Use the project config for servers tied to a specific project: a Supabase instance for one app, a Postgres database for another.
Project-level config takes precedence when both files define a server with the same name.
Step 1: Install the MCP Server
Most MCP servers are Node.js packages published to npm. Install them globally so Claude Code can find them.
npm install -g @modelcontextprotocol/server-githubSome servers are Python packages:
pip install mcp-server-postgresOthers are standalone binaries. Check the server’s README for the correct install method.
Step 2: Configure the Server
Open your config file and add the server definition under the mcpServers key.
Global config (claude_desktop_config.json):
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
}
}
}
}Project config (.mcp.json):
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase"],
"env": {
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_SERVICE_ROLE_KEY": "your_key_here"
}
}
}
}The command field is the executable. The args array passes arguments to it. The env object sets environment variables the server needs.
Step 3: Restart Claude Code
MCP servers are loaded at startup. After editing any config file, restart Claude Code completely. A reload of the current session is not sufficient.
Close the terminal or window running Claude Code and reopen it. The new servers will initialize when Claude Code starts.
Step 4: Verify the Connection
After restarting, ask Claude to list available tools or attempt a task that requires the new server.
What MCP tools do you have available?Claude will list all tools it has loaded, including those from MCP servers. If your server’s tools appear, the setup is working.
You can also test directly:
Use the GitHub MCP server to list my open pull requests.A successful response confirms the server is connected and authenticated.
Troubleshooting: Common MCP Setup Errors
| Error | Likely cause | Fix |
|---|---|---|
MCP server not found | Server binary not in PATH | Install globally with -g flag or use full path in command |
Connection refused | Server failed to start | Check the server’s own logs, ensure required env vars are set |
Authentication failed | Invalid or missing API token | Verify the token in your env config, check token permissions |
Tool not available | Config not reloaded | Restart Claude Code completely after editing config |
JSON parse error | Malformed config file | Validate your JSON with a linter, check for trailing commas |
If Claude Code starts but the MCP server’s tools are absent, the most common cause is a startup failure that produced no visible error. Run the server command manually in a terminal to see its output:
npx -y @modelcontextprotocol/server-githubAny startup errors will appear in the terminal. Fix those before relying on Claude Code to surface them.
Managing Multiple MCP Servers
You can register as many servers as you need. Each gets a unique key in mcpServers. Claude Code initializes all of them at startup.
{
"mcpServers": {
"github": { ... },
"supabase": { ... },
"postgres": { ... },
"brave-search": { ... }
}
}Be selective. Every server adds startup time and background processes. Install servers you will actually use rather than every server that sounds useful.
Frequently Asked Questions
Do MCP servers run locally or in the cloud?
MCP servers run locally on your machine as child processes of Claude Code. The server process starts when Claude Code starts and shuts down when you close the session. The server itself may make outbound network calls to external services, but the MCP server process lives on your machine.
Can I use both global and project MCP configs at the same time?
Yes. Claude Code merges both config files at startup. Global servers are always available. Project servers are only available when you are in that project directory. If both configs define a server with the same name, the project config wins.
Are my API keys in the config files secure?
Config files are plain text on your local filesystem. They have the same security properties as any file on your machine. Avoid committing .mcp.json files that contain real API tokens to version control.
Use environment variables or secret managers for production setups, and add .mcp.json to your .gitignore when it contains credentials.
What happens if an MCP server crashes during a session?
Claude Code will report that the tool is unavailable for the remainder of the session. It will not automatically restart the server. You will need to restart Claude Code to reconnect. Some servers are more stable than others. Check the server’s issue tracker if a specific server crashes frequently.
Ready to extend Claude Code with MCP servers?
Pick one server from the list of the most useful MCP servers for Claude Code, follow the configuration steps above, and verify the connection before adding more servers.
Path one: set it up yourself. Start with a single server, confirm it works, then expand. The Claude Code course covers MCP configuration, workflows, and practical patterns in depth, including how to combine multiple servers in a single session.
Path two: work with Phos AI Labs. If you want MCP configured as part of a broader Claude Code setup for your engineering team, including project configs, access controls, and workflow design, we handle that implementation. Phos AI Labs is a CCA-F certified Claude implementation partner. Thirty minutes, no deck. Start here.