MCP Servers in Claude Code

The Model Context Protocol (MCP) lets you extend Claude Code with custom tools — database queries, API calls, cloud service interactions, and more. Claude Code connects to MCP servers and exposes their tools alongside its built-in tools (Read, Write, Bash, etc.).

Adding MCP Servers to Your Config

MCP servers are configured in settings.json. Claude Code supports project-level (per-project) and global (all projects) MCP server configurations:

// .claude/settings.json (project-level)
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost:5432/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

Each MCP server entry specifies: the server name (key), the command to start it, any arguments, and environment variables to pass. Claude Code starts the MCP server process when the session begins and connects to it via the MCP stdio transport.

Project-Level vs Global MCP Servers

• Project-level: .claude/settings.json in your project root — only available when Claude Code is run in that project. Best for project-specific tools (your project's database, internal APIs).
• Global: ~/.claude/settings.json — available in every Claude Code session. Best for general-purpose tools you use across all projects (GitHub, filesystem tools, web search).

Project-level servers take precedence over global servers if both define a server with the same name.

Testing an MCP Server Connection

After adding an MCP server to settings.json, verify it is working:

1. Start a Claude Code session in the project: claude
2. Run /help and look for the MCP server's tools in the tool list
3. Ask Claude: "What tools are available from the [server-name] MCP server?"
4. Run a simple test call: "Use the [tool-name] tool to [simple task]"

If the server fails to start, Claude Code logs the error in the session output. Common issues: command not found (package not installed), wrong arguments, environment variables not set.

Calling MCP Tools in a Session

Once connected, MCP tools are available to Claude Code naturally — you don't need to invoke them explicitly. Just describe what you want:

• "Query the database for the 10 most recent orders." (Claude uses the postgres MCP tool)
• "List all files in the /data directory." (Claude uses the filesystem MCP tool)
• "Create a GitHub issue titled [title] in the [repo] repository." (Claude uses the GitHub MCP tool)

Claude selects the appropriate MCP tool based on the description and the tool's schema. You can also be explicit: "Use the postgres query tool to run: SELECT..."

Debugging MCP Connection Issues

Common issues and fixes:

• "MCP server failed to start": Check the command is installed (which npx, which node). Check environment variables are set correctly. Try running the server command manually in your terminal to see the error.
• "Tool not available": Check settings.json syntax (valid JSON, no trailing commas). Check the server name matches what you expect. Restart Claude Code after changing settings.json.
• "Tool call returned an error": Usually a configuration issue with the MCP server itself (wrong credentials, unreachable endpoint). Check the server's own documentation for config requirements.
• Permission prompts for MCP tools: MCP tool calls follow the same permission model as built-in tools — Claude Code will prompt before calling a tool if it has not been pre-approved. Add the tool pattern to allowedTools in settings.json to pre-approve.

Checklist: Do You Understand This?

• MCP servers are configured in settings.json under mcpServers — specify command, args, and env vars
• Project-level (.claude/settings.json) for project-specific tools; global (~/.claude/settings.json) for tools used everywhere
• Verify connection with /help or by asking Claude what tools are available from the server
• MCP tools are used naturally — describe the task and Claude picks the right tool
• Debug startup failures by running the server command manually in your terminal to surface the raw error