MCP Tools in Claude Code: Best Config Setup

To configure MCP (Model Context Protocol) tools in Claude Code, the best approach is to use a project-level .mcp.json file for shared settings and a user-level claude_desktop_config.json for personal tools, then launch Claude Code with the --mcp-config flag or rely on automatic discovery. This gives you per-project isolation, version control, and avoids the common pitfall of global tools leaking into every session. Below is a detailed breakdown of why this works, how to structure it, and what to watch out for.

What MCP Tools Are and Why They Matter

MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external tools—databases, web search, file systems, APIs—through a unified interface. Instead of hardcoding every integration, MCP acts as a middleware layer: the model sends a request, the MCP server translates it into a tool call, and returns structured results. This matters because it decouples the AI from the underlying service, so you can swap out a search engine or database without retraining the model.

In Claude Code specifically, MCP tools are configured as JSON files that list server names, commands, and environment variables. The two main files are .mcp.json (project-level) and claude_desktop_config.json (user-level). The project file lives in your repository root and is meant to be committed to version control, so all team members get the same tools. The user file sits in ~/.claude/ and holds personal tools like a private API key or a local file server.

How MCP Configuration Files Work

Each MCP config file is a JSON object with a mcpServers key. Each server entry has a command (the executable to run), args (command-line arguments), and env (environment variables). Here’s a minimal example:

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

When you start Claude Code, it reads both the user-level and project-level configs, merges them (project overrides user on conflicts), and launches each server as a subprocess. The model then sees the available tools and can invoke them via function calls. You can also pass a custom config file with claude --mcp-config /path/to/config.json, which takes precedence over both default files.

Choosing Between Project and User Config

The key decision is where to put a tool. Use project-level .mcp.json when:

• The tool is specific to that codebase (e.g., a database schema, a test runner).
• You want all collaborators to have the same tools without manual setup.
• The tool’s environment variables are non-secret (e.g., a localhost URL).

Use user-level claude_desktop_config.json when:

• The tool is personal (e.g., a notes app, a personal calendar).
• It requires secret API keys that should not be committed to git.
• You want the tool available across all your projects.

A common mistake is putting secrets in .mcp.json and committing it. Git history leaks keys. Instead, reference environment variables in the config and set them in your shell or a .env file that is gitignored.

Step-by-Step: Setting Up a New MCP Tool

1. Identify the MCP server you need. Most popular services (Postgres, GitHub, Slack) have official or community servers on npm.
2. Create or edit .mcp.json in your project root. If it doesn’t exist, create it with the mcpServers key.
3. Add the server entry with the correct command and args. For Node-based servers, use npx -y package-name to avoid manual installs.
4. Set environment variables. Use env for static values, or reference ${VAR} to pull from your shell environment.
5. Restart Claude Code. Run claude in the project directory and check the tool list with /mcp command.
6. Test the tool with a simple prompt, like “list tables in the database� for a Postgres server.

Common Problems and Fixes

MCP configuration often fails silently. The most frequent issues:

• Server not starting: Check the command is executable and the package is installed. Run the command manually in your terminal to see errors.
• Environment variables not resolved: Claude Code does not expand ${VAR} inside the config by default. Use a wrapper script that exports variables, or hardcode non-secret values.
• Port conflicts: Some servers bind to a fixed port. If you run two instances, the second fails. Use different ports or a single shared server.
• Project config ignored: Ensure .mcp.json is in the root of the directory you launch Claude Code from. Subdirectories won’t be picked up.
• Merging conflicts: If a server name exists in both user and project config, the project one wins. This can be confusing if you expected the user version.

Comparing MCP to Native Integrations

Claude Code also has built-in integrations (e.g., for GitHub or filesystem) that don’t require MCP. The trade-off is simplicity vs. flexibility. Native integrations are zero-config, but limited to what Anthropic provides. MCP gives you any tool, but you manage installation and security. For a team, MCP is better because it’s standardized and portable—you can move to another MCP-compatible client later. For a single user with basic needs, native may suffice.

Security and Performance Considerations

MCP servers run with your user permissions. A malicious or buggy server can read files, send network requests, or execute commands. Only install servers from trusted sources, and review the package code if it’s obscure. Avoid running MCP servers as root or with elevated privileges. Performance-wise, each server is a separate process; too many servers can slow down startup and consume memory. Limit to the tools you actually use, and consider lazy-loading (some clients support on-demand server start).

Frequently Asked Questions

Q: Can I use MCP tools without writing JSON?
Yes, some community tools generate config files via CLI, but the underlying format is always JSON. Claude Code also has a /mcp interactive command that can add servers for you, but it still writes to the same files.

Q: Why does my MCP server work in the desktop app but not in Claude Code CLI?
The desktop app uses claude_desktop_config.json, while the CLI uses both that and .mcp.json. If a server name conflicts, the CLI may pick a different one. Check the exact paths and ensure the command is available in the CLI’s PATH.

Q: How do I debug an MCP server that fails to connect?
Run the server command manually in a terminal to see logs. Also check Claude Code’s verbose mode (claude --verbose) which prints MCP handshake details. Most failures are due to missing environment variables or wrong command paths.

Q: Can I use MCP tools with other AI models?
Yes, MCP is an open standard adopted by several AI assistants. The config format is similar, but check each tool’s documentation for specific fields. The JSON structure here is specific to Claude Code.

Q: Is there a limit on how many MCP servers I can have?
No hard limit, but practical limits come from your system’s memory and process count. Each server spawns a process; 10-15 is typical for heavy use, but you may see slowdowns. Use fewer servers or combine multiple tools into one server if possible.

Q: What if I need a tool that isn’t available as an MCP server?
You can write your own MCP server using the official SDKs (Python, TypeScript). The protocol is straightforward: define tools, handle JSON-RPC requests. Many wrappers exist to expose REST APIs as MCP servers with minimal code.

Related

• How Self-Destructing Circuits Work in Mission: Impossible
• Set Vintage Story Server Name & Description
• Motorola Edge 70 Pro 5G vs Nothing Phone 4b: Which to Pick?

in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0 | 100000
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2