mcp-reference

Claude Code MCP Reference

MCP (Model Context Protocol) connects Claude to external tools and services.

Configuration Locations

Location	Scope
~/.claude/settings.json	User (all projects)
.claude/settings.json	Project (team shared)
.claude/settings.local.json	Project (gitignored)

Basic Configuration

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Configuration Fields

Field	Required	Description
command	Yes	Executable to run
args	No	Command arguments
env	No	Environment variables
cwd	No	Working directory
alwaysAllow	No	Array of always-allowed tools
disabled	No	Boolean to disable server

Common MCP Servers

Filesystem Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

GitHub Server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Database Server

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Plugin MCP Servers

In plugin's .mcp.json or plugin.json:

{
  "mcpServers": {
    "plugin-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Note: Use ${CLAUDE_PLUGIN_ROOT} for plugin paths.

Tool Permissions

Always Allow Specific Tools

{
  "mcpServers": {
    "github": {
      "command": "...",
      "alwaysAllow": [
        "create_issue",
        "list_repos"
      ]
    }
  }
}

Interactive Permissions

If alwaysAllow not specified, Claude asks before using tools.

Disabling Servers

{
  "mcpServers": {
    "expensive-server": {
      "command": "...",
      "disabled": true
    }
  }
}

Environment Variables

From System Environment

{
  "env": {
    "API_KEY": "${API_KEY}"
  }
}

Direct Values

{
  "env": {
    "DEBUG": "true"
  }
}

Server Management

List MCP Servers

/mcp

Refresh Servers

/mcp refresh

Check Server Status

Look in /mcp for connection status.

Debugging MCP Servers

# Debug mode shows server initialization
claude --debug

# Test server manually
npx -y @modelcontextprotocol/server-name

# Check server logs
# Look for MCP-related output in debug

Common Issues

Issue	Solution
Server not starting	Check command exists and is executable
Tools not appearing	Verify server implements MCP correctly
Permission denied	Check file/directory permissions
Environment vars missing	Verify env values are set

Example: Custom Python Server

{
  "mcpServers": {
    "my-python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "/path/to/server",
      "env": {
        "PYTHONPATH": "/path/to/server"
      }
    }
  }
}

Security Considerations

• Store secrets in environment variables, not in settings
• Use .claude/settings.local.json for sensitive configs
• Review server code before adding third-party servers
• Limit alwaysAllow to necessary tools only

---

For complete documentation, see:

• mcp-full.md - Complete MCP reference