Setting up MCP Servers in Claude Code

What is Claude Code?

Claude Code is Anthropic's official CLI tool for AI-assisted coding. It brings Claude's capabilities directly to your terminal, enabling code generation, refactoring, debugging, and more through natural language commands.

What is MCP?

MCP (Model Context Protocol) follows a client-server architecture where:

• MCP clients (like Claude Code) connect to MCP servers and request actions on behalf of the AI model
• MCP servers provide tools that expose specific functionalities through a well-defined interface
• The protocol defines the message format for communication between clients and servers

Prerequisites

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18+ or Bun
• Docker (optional, for containerized MCP servers)
• API key for any MCP servers that require authentication

Installing Claude Code

If you haven't installed Claude Code yet:

# Using npm
npm install -g @anthropic-ai/claude-code

# Using bun
bun install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Configuring MCP Servers

Claude Code stores MCP servers in three scopes:

The recommended way to add a server is the claude mcp add command, which writes the correct JSON for you.

Option 1: Add a Remote HTTP Server

HTTP is the recommended transport for cloud services:

# Basic syntax
claude mcp add --transport http <name> <url>

# Example
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Share it with the team via project scope
claude mcp add --transport http notion https://mcp.notion.com/mcp --scope project

Option 2: Add a Local stdio Server

For servers that run on your machine, pass the whole launch command after --:

claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

Everything after -- is passed to the server untouched, so flags like -y and --port are not read as Claude Code options.

Option 3: Edit .mcp.json Directly

To commit shared configuration, create .mcp.json at your project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Project-scoped servers require approval the first time: run claude interactively and accept the prompt.

Global Configuration

User-scope servers live in ~/.claude.json. Add them with --scope user rather than hand-editing:

claude mcp add --scope user --transport stdio brave-search \
  --env BRAVE_API_KEY=YOUR_KEY \
  -- npx -y @brave/brave-search-mcp-server

Popular MCP Servers for Claude Code

Filesystem & Git

• @modelcontextprotocol/server-filesystem - Read/write files in allowed directories (pass directories as positional arguments)
• mcp-server-git - Git operations (status, diff, commit); run with uvx mcp-server-git

Development Tools

• github/github-mcp-server - Issues, pull requests, and repository management (Docker or remote at https://api.githubcopilot.com/mcp/)

Search & Research

• @brave/brave-search-mcp-server - Web search via the Brave Search API
• mcp-server-fetch - Fetch and process web content; run with uvx mcp-server-fetch

Starting Claude Code with MCP

Once configured, start Claude Code in your project:

cd /path/to/your/project
claude

Claude Code loads user- and local-scope servers automatically. Project-scope servers from .mcp.json show as "Pending approval" until you approve them once in an interactive session.

Verifying MCP Servers

Check server status and health from your terminal:

claude mcp list
claude mcp get filesystem

Inside a session, run /mcp to see each server's status, tools, and options.

Using MCP Tools in Claude Code

Once connected, you can use MCP tools naturally in your conversations:

Example 1: File Operations

Read the contents of src/index.ts and suggest improvements

Claude Code will use the filesystem MCP server to read the file and provide suggestions.

Example 2: GitHub Integration

Create a new issue titled "Add unit tests" with a description of what tests we need

Claude Code will use the GitHub MCP server to create the issue.

Example 3: Web Search

Search for the latest Next.js documentation on server components

Claude Code will use the Brave Search MCP server to find relevant information.

Environment Variables

Many MCP servers require API keys. Set them in your shell profile:

# ~/.zshrc or ~/.bashrc
export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_xxxxxxxxxxxx"
export BRAVE_API_KEY="BSAxxxxxxxxxxxxxx"

In .mcp.json, ${VAR} is expanded from your environment, and ${VAR:-default} supplies a fallback when the variable is unset.

Advanced Configuration

Custom Server Paths

If you have a custom MCP server:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Docker-Based Servers

Run a stdio MCP server in Docker:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Filesystem Directories

The filesystem server takes allowed directories as positional arguments, not as a flag:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects",
        "/home/user/docs"
      ]
    }
  }
}

Adding a Server from Another Client's JSON

Use claude mcp add-json, passing the object inside mcpServers:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}' --scope project

Security Considerations

⚠️ Caution: MCP servers can run arbitrary code on your machine. Only add servers from trusted sources, and always review the server configuration before starting it.

🔒 Important: Never hardcode sensitive information like API keys directly in configuration files. Use environment variables or input variables instead.

📁 Filesystem Access: Be specific about which directories MCP servers can access. Avoid granting access to your entire home directory.

Troubleshooting

Server Not Connecting

1. Check the server command and arguments are correct
2. Verify required environment variables are set (claude mcp list warns about missing ones)
3. Ensure the server package is installed (try npx with -y)
4. Run claude --debug for verbose output

Tool Not Available

1. Verify the MCP server is connected (claude mcp list, /mcp)
2. Check the server's tool list matches what you're trying to use
3. Restart Claude Code after configuration changes

Project Server Pending Approval

Servers from .mcp.json are not loaded until you trust the workspace. Run claude in the project and accept the approval prompt.

Permission Errors

1. Ensure the MCP server has access to required directories
2. Check file permissions on configuration files
3. Verify API keys have the necessary scopes

Sources

• Claude Code MCP Documentation
• Anthropic Connector Directory
• MCP Specification
• Official MCP Servers Repository