Intermediate

Using MCP with Claude Code

Claude Code supports MCP servers at two levels: project-level (specific to one codebase) and global (available in all projects). Configure them in settings.json files and Claude Code connects automatically when you start a session.

Project-Level MCP Config

Project-level MCP servers are configured in .claude/settings.json at the root of your project. Only sessions started in that project directory use these servers:

// .claude/settings.json
{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./src"
      ]
    }
  }
}

Commit this file to version control to share the MCP server configuration with your team. Anyone who clones the repo and runs Claude Code gets the same server setup.

Global MCP Config

Global MCP servers are available in all Claude Code sessions regardless of the project directory. Configure them in ~/.claude/settings.json (your home directory):

// ~/.claude/settings.json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Use global config for tools you always want available: web search, GitHub integration, personal file access. Use project config for project-specific tools: the project's database, internal APIs, or project-scoped file directories.

Adding a Remote SSE Server

For SSE transport (remote HTTP server), use type: "sse" and provide a url:

{
  "mcpServers": {
    "my-team-server": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer team-api-key"
      }
    }
  }
}

Enabling and Disabling Servers

You can enable or disable specific MCP servers without removing them from config using the Claude Code CLI:

# List all configured MCP servers and their status
claude mcp list

# Add a new MCP server via CLI (updates settings.json)
claude mcp add postgres --command npx -- -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

# Remove a server
claude mcp remove postgres

Debugging: Verifying Server Connection

If Claude Code cannot connect to an MCP server, diagnose with these steps:

Run the server command manually in a terminal to check for startup errors: npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb
Check that the command and args in settings.json are correct (valid JSON, no trailing commas)
Ensure required environment variables are set — missing API keys cause silent failures
Start a Claude Code session and ask "what MCP tools do you have?" — if the server connected, its tools will be listed
Run claude mcp list to see connection status for each configured server

Checklist: Do You Understand This?

Project-level: .claude/settings.json — commit to version control to share with your team
Global: ~/.claude/settings.json — for tools available in all projects (search, GitHub)
Each server entry: type (stdio/sse) + command/args or url; credentials go in env
CLI management: claude mcp list, claude mcp add, claude mcp remove
Debug by running the server command manually — startup errors appear in the terminal