Claude Code MCP Setup

Purpose

Guide for adding and configuring MCP (Model Context Protocol) servers in Claude Code CLI.

When to Use

• Adding a new MCP server to Claude Code
• Configuring remote MCP servers (HTTP/SSE)
• Troubleshooting MCP connection failures
• Understanding MCP transport types
• Setting up OAuth-authenticated MCP servers

Quick Reference

CLI Commands

# Add local stdio MCP server
claude mcp add <name> <command> [args...]

# Add remote HTTP MCP server (supports OAuth)
claude mcp add --transport http <name> <url>

# Add remote SSE MCP server
claude mcp add --transport sse <name> <url>

# Add with environment variables
claude mcp add <name> -e API_KEY=xxx -- <command> [args...]

# Add with custom headers
claude mcp add --transport http <name> <url> --header "Authorization: Bearer xxx"

# List configured servers
claude mcp list

# Remove a server
claude mcp remove <name>

Transport Types

Common MCP Server Examples

monday.com (Remote HTTP with OAuth)

claude mcp add --transport http monday https://mcp.monday.com/mcp

After adding, restart Claude Code and run /mcp. First connection will prompt OAuth authorization in browser.

GitHub (Local with Token)

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx @modelcontextprotocol/server-github

Filesystem (Local)

claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /path/to/directory

Custom Local Server

claude mcp add my-server node /path/to/server.js

Configuration Files

MCP servers are stored in:

• User config: ~/.claude.json (global)
• Project config: .mcp.json (per-project, legacy)

Manual Configuration (if needed)

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["@org/mcp-package"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

For remote servers:

{
  "mcpServers": {
    "remote-server": {
      "type": "url",
      "url": "https://example.com/mcp"
    }
  }
}

Troubleshooting

Check MCP Status

# Inside Claude Code
/mcp

# Detailed diagnostics
/doctor

Common Issues

"Does not adhere to MCP server configuration schema"

• Use claude mcp add CLI command instead of manual JSON editing
• Ensure correct transport type for remote servers

"Failed to reconnect"

• Check network connectivity
• Verify OAuth authorization completed
• Try removing and re-adding: claude mcp remove <name> && claude mcp add ...

OAuth not prompting

• Restart Claude Code after adding server
• Run /mcp to trigger connection
• Check browser for blocked popups

Environment variable errors

• Use -e VAR=value flag when adding
• Or set in shell before running Claude Code

Verify Configuration

# Check what was added
cat ~/.claude.json | jq '.mcpServers'

# Validate JSON syntax
jq . ~/.claude.json

Resources

• Claude Code MCP Docs
• MCP Specification
• MCP Server Registry