Model Context Protocol (MCP)

Connect Claude Code to external tools and data sources through a standardized protocol.

What Is MCP?

MCP (Model Context Protocol) is an open standard that lets Claude Code communicate with external services. Instead of copy-pasting data into prompts, MCP servers provide Claude with direct access to tools and resources.

Think of MCP servers as plugins that give Claude new abilities beyond reading and writing files.

Configuration

The recommended path is claude mcp add — it writes the right file for the scope you pick:

claude mcp add --transport stdio --scope project myserver -- npx @my/server --port 8080
claude mcp list
claude mcp remove myserver

A project-scoped .mcp.json looks like this:

{
"mcpServers": {
  "db": {
    "command": "npx",
    "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
  }
}
}

All claude mcp add flags (--transport, --env, --scope, --header) must come before the server name; -- separates it from the command. Note: mcpServers is not a valid key in .claude/settings.json — keep it in .mcp.json (project) or ~/.claude.json (local/user).

Common MCP Servers

Database Access

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

Claude can now query your database directly: how many users signed up this week?

Extended Filesystem

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

GitHub

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Enables: list open PRs, check CI status for PR #42, create an issue for this bug

HTTP / Remote Servers

For remote MCP servers, prefer the HTTP transport:

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

${VAR} and ${VAR:-default} inside command, args, env, url, and headers are expanded from your shell environment at startup.

The MCP spec name for this transport is streamable-http; Claude Code accepts both "type": "http" and "type": "streamable-http" as aliases. The older SSE transport (--transport sse) is deprecated — use HTTP servers where available.

Other Popular Servers

• Slack — Search messages, post updates
• Google Drive — Read documents and spreadsheets
• Figma — Extract design specs and assets
• Linear / Jira — Read and create issues
• Sentry — Query error logs and exceptions

Browse reviewed connectors in the Anthropic Directory↗.

Scope Hierarchy & Approving Servers

When the same server name appears in multiple scopes, the highest-precedence definition wins:

1. Local (~/.claude.json, default) — private to you, this project
2. Project (.mcp.json, committed to git) — shared with the team
3. User (~/.claude.json) — your servers across all projects

For security, Claude Code prompts before using project-scoped servers from .mcp.json. Reset those choices with claude mcp reset-project-choices.

To approve, reject, or auto-accept project servers without prompts, use these keys in .claude/settings.json (any scope):

{
  "enabledMcpjsonServers": ["db"],
  "disabledMcpjsonServers": ["risky-server"],
  "enableAllProjectMcpServers": false
}

Managed deployments can also lock things down via allowedMcpServers / deniedMcpServers in managed-settings.json.

MCP Tools in Hooks

MCP tools appear as regular tools in all hook events. Their names follow the pattern mcp__<server>__<tool>:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__playwright__.*",
        "hooks": [{ "type": "command", "command": "echo 'Browser action' >> audit.log" }]
      }
    ]
  }
}

Handling Large Tool Results

If you build an MCP tool that needs to return large data (schemas, configs, bulk records), add _meta["anthropic/maxResultSizeChars"] to that tool's tools/list entry. Claude Code can raise that tool's inline threshold up to a hard ceiling of 500,000 characters:

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

For servers you do not control, raise MAX_MCP_OUTPUT_TOKENS in your shell or ask the server author to add the annotation.

Building Your Own MCP Server

MCP servers are simple programs that communicate over stdio or HTTP. Build one with the official MCP SDK for your language, define tools (actions Claude can take), resources (data Claude can read), and prompts (reusable templates), then configure the built command in Claude Code with claude mcp add.

Related Reading

• Skills — Modular workflows that can reference MCP tools
• Subagents — Isolated workers that can use scoped tool access
• Hooks — Automate actions around MCP tool use
• Workflows — Integrate MCP into development workflows