ucsandman/claude-code-capability-primer/claude-code-mcp

Claude Code MCP Servers

What is MCP?

Model Context Protocol (MCP) = external tools/data/resources exposed to Claude as callable tools. Live systems: issue trackers, databases, APIs, browsers, design tools. Not suitable for repo-local logic (use skills or scripts instead).

Tools are named mcp__<server-name>__<tool-name> in output. Example: mcp__github__list_issues.

Configuration

Three scopes, stored in two files:

Add a server:

# HTTP server (hosted)
claude mcp add --transport http <name> <url>
claude mcp add --transport http stripe https://mcp.stripe.com
 
# Stdio server (local process, needs --)
claude mcp add <name> -- <command> [args...]
claude mcp add playwright -- npx -y @playwright/mcp@latest
 
# Set scope
claude mcp add --scope user <name> <url>
claude mcp add --scope project <name> <url>

Verify:

claude mcp list
claude mcp get <name>

Remove:

claude mcp remove <name> [--scope local|project|user]

Edit `.mcp.json` directly:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/...",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Transports

HTTP (hosted, recommended for remote servers):

• Stateless, runs at a URL.
• claude mcp add --transport http <name> <url>
• Also called streamable-http in JSON (MCP spec naming).

Stdio (local, for filesystem/browser/db access):

• Command runs on your machine, talks via stdin/stdout.
• claude mcp add <name> -- <command> [args...]
• Critical: Separate options from server command with --. Everything after -- goes untouched to the server.
• Pass env vars via --env KEY=value or env in config.
• Startup timeout: 30s default; set MCP_TIMEOUT=60000 (ms) if slow.

SSE (hosted, DEPRECATED — use HTTP instead):

• Server-Sent Events; older streaming transport.
• "type": "sse" in .mcp.json.

WebSocket (hosted, for persistent bidirectional connections):

• Configure in .mcp.json or claude mcp add-json.
• "type": "ws" with url, headers, timeout, alwaysLoad.
• Use HTTP instead when server only responds to requests (HTTP has OAuth support, WebSocket does not).

Authentication

Environment variables (stdio servers):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${} syntax (or ${VAR:-default} for defaults) expands from shell env at runtime.

HTTP headers (hosted servers):

{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

OAuth (interactive browser sign-in):

1. claude mcp add --transport http <name> <url>
2. Server shows ! Needs authentication in /mcp
3. Inside claude session: /mcp → select server → Authenticate → sign in → auto-connected

Static token (at add time):

claude mcp add --transport http <name> <url> --header "Authorization: Bearer <token>"

Tool Search (Deferred Loading)

What it does: Instead of loading all tool definitions upfront (bloats context for 50+ tools), Claude searches on demand and loads only what it needs (3–5 tools per search). Saves ~85% context overhead.

Who supports it: Requires Sonnet 4.5+ or Opus 4.5+. Haiku does not support tool search (on Claude Code or API).

Enabled by default: Yes. Falls back to upfront loading on Vertex AI or custom ANTHROPIC_BASE_URL.

Configure via `ENABLE_TOOL_SEARCH` env var:

Set in settings.json:

{
  "ENABLE_TOOL_SEARCH": "true"
}

Override per query (Agent SDK only):

for await (const msg of query({
  prompt: "...",
  options: { env: { ENABLE_TOOL_SEARCH: "auto:5" } }
})) { ... }

Always load one server upfront (skip search):

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "...",
      "alwaysLoad": true
    }
  }
}

Permissions

Tools from MCP require explicit allow-list.

CLI (first time):

• Claude asks: "Allow use of mcp__<server>__<tool>?"
• Approve in session.

Pre-approve via settings.json:

{
  "permissions": {
    "allow": [
      "mcp__github__*",
      "mcp__stripe__*"
    ]
  }
}

Use wildcards to avoid per-tool approval.

Scope Precedence

When the same server is defined in multiple scopes:

1. Local
2. Project
3. User
4. Plugin-provided
5. Claude.ai connectors

The entry from the highest-precedence source is used entirely (fields not merged).

Connection Status

Run /mcp in session or claude mcp list from shell:

Debug stdio: Run the command directly to see errors:

npx -y @playwright/mcp@latest

Debug HTTP:

curl -I https://mcp.sentry.dev/mcp
# 404/405: up, reachable.
# 401/403: auth missing/invalid.
# No response: network/DNS issue.

Startup timeout:

MCP_TIMEOUT=60000 claude

Resources and Prompts

Reference resources in prompts (like @file.md):

@server:protocol://path
@github:issue://123
@postgres:schema://users

Execute MCP prompts as commands:

/mcp__servername__promptname [args...]
/mcp__github__pr_review 456

When to Use MCP vs Skills/Scripts

Use MCP when:

• Tool is external API/service/database with live state.
• Needs to read/act on remote system (GitHub, Stripe, Slack, browser).
• Shared across projects (user or project scope).
• Already exists and MCP-compatible.

Use skill/script when:

• Repo-local logic, refactoring, generation, testing.
• Parses your codebase and emits artifacts.
• Runs only in this project.
• Custom to your workflow.

Examples

Stdio server (local CLI, no auth):

"mcpServers": {
  "my-tools": {
    "command": "my-mcp-server",
    "args": ["mcp", "--transport", "stdio"],
    "description": "what this server exposes"
  }
}

Common servers people add: context7 (live library docs), github (GitHub API), stripe (Stripe API), plus filesystem, database, and browser/automation servers.

Check your actual servers: /mcp in session or claude mcp list from shell.

Troubleshooting Checklist

1. Server not in `/mcp` list?

• Check scope: claude mcp get <name> or grep ~/.claude.json and .mcp.json.
• Local servers tied to project root or exact directory. Re-add if different project.

1. Status: "Failed to connect"?

• HTTP: curl -I <url> to confirm reachable.
• Stdio: run command directly to see error.
• Missing env var / token / startup timeout.

1. Tools visible but Claude won't call?

• Missing permissions.allow pre-approval. /mcp to approve, or add to settings.

1. No tools in `/mcp` tool list?

• Server started but no tools registered → likely missing API key / env var.
• Check server docs for required vars; pass via --env KEY=value or env field.

1. Changes to `.mcp.json` don't apply?

• Restart session (Claude reads .mcp.json at startup).
• Check file syntax (valid JSON).
• Run claude mcp reset-project-choices if you rejected server earlier.

Key Settings You Control

{
  "mcpServers": {
    "name": {
      "type": "http|stdio|sse|ws",
      "url": "...",
      "command": "...",
      "args": [...],
      "env": { "KEY": "${VAR}" },
      "headers": { "Authorization": "Bearer ${TOKEN}" },
      "alwaysLoad": true,
      "timeout": 600000
    }
  },
  "ENABLE_TOOL_SEARCH": "auto|auto:5|true|false",
  "permissions": {
    "allow": ["mcp__<server>__*"]
  }
}

Related

• MCP quickstart
• MCP full reference
• Managed MCP (team/enterprise control)
• MCP specification
• MCP server directory
• Build your own server