MCP Servers

MCP (Model Context Protocol) servers extend Claude Code with live access to external tools, databases, and APIs. Instead of copy-pasting context into your conversation, Claude can query live systems directly. The difference between a basic Claude Code setup and a power-user setup is often the MCP servers.

Adding servers

The primary way to add MCP servers is through the claude mcp add CLI command. There are three transport types depending on where the server runs.

Remote HTTP server (recommended)

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

# Example: Connect to GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

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

Remote SSE server (deprecated)

SSE (Server-Sent Events) transport is deprecated in favor of HTTP. Use it only when a server does not support HTTP.

claude mcp add --transport sse asana https://mcp.asana.com/sse

Local stdio server

Stdio servers run as local processes on your machine. They are ideal for tools that need direct system access.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Example: PostgreSQL via @bytebase/dbhub
claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/dev"

# With environment variables
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Option ordering matters. All flags (--transport, --env, --scope, --header) must come before the server name. The -- separates the server name from the command that launches the MCP server process.

Adding from JSON

You can also add a server from a raw JSON configuration:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}'

claude mcp add-json local-tool '{"type":"stdio","command":"npx","args":["-y","some-package"]}'

Configuration files

MCP server configurations are stored in two files depending on scope. These are not the same as .claude/settings.json or .claude/settings.local.json, which are for Claude Code settings.

The .mcp.json format:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://..."],
      "env": {}
    }
  }
}

Environment variables are supported in .mcp.json using ${VAR} or ${VAR:-default} syntax, so teams can share configs without hardcoding secrets.

Scopes

Use the --scope flag to control where a server configuration is stored:

# Add a server only you can see in this project (default)
claude mcp add --transport http stripe https://mcp.stripe.com

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

# Available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

When the same server name exists at multiple scopes, precedence is: local > project > user.

Practical examples

Query a PostgreSQL database

claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@localhost:5432/analytics"

Then ask Claude:

Show me the schema for the orders table.
Find customers who haven't made a purchase in 90 days.

Use read-only database connections by default. Only allow writes when explicitly needed.

Connect to GitHub

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Authenticate via /mcp inside Claude Code, then:

Review PR #456 and suggest improvements.
Show me all open PRs assigned to me.

Monitor errors with Sentry

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authenticate via /mcp, then:

What are the most common errors in the last 24 hours?
Which deployment introduced these new errors?

Management commands

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# Import servers from Claude Desktop (macOS/WSL)
claude mcp add-from-claude-desktop

# Check server status inside Claude Code
/mcp

OAuth authentication

Many remote MCP servers require OAuth 2.0 authentication. The workflow is straightforward:

1. Add the server: claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. Run /mcp inside Claude Code
3. Follow the browser login flow

Authentication tokens are stored securely and refreshed automatically. Use “Clear authentication” in the /mcp menu to revoke access.

For servers that require pre-configured OAuth credentials (no dynamic client registration), use --client-id and --client-secret:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Troubleshooting

• Server not starting: Check the command works directly (e.g., npx -y @bytebase/dbhub --help). MCP servers must run as long-lived processes.
• Connection closed on Windows: Wrap npx commands with cmd /c on native Windows: claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
• Timeout errors: Configure startup timeout with the MCP_TIMEOUT environment variable (e.g., MCP_TIMEOUT=10000 claude for 10 seconds).
• Output too large: Increase the token limit with MAX_MCP_OUTPUT_TOKENS=50000 claude (default is 25,000 tokens, warning at 10,000).
• Authentication errors: Run /mcp inside Claude Code to re-authenticate. Check that env vars are set correctly for stdio servers.
• Project server prompts: Claude Code prompts for approval before using project-scoped servers from .mcp.json. Use claude mcp reset-project-choices to reset approvals.

Quick reference