MCP (Model Context Protocol)

Level: 🌿 Intermediate Source: MCP

← Back to Automating Your Workflows

MCP gives Claude access to external tools and data sources through a standardized protocol. An MCP server exposes a set of tools, and Claude can call them during a session.

But before you reach for MCP, understand when it’s the right choice — and when it isn’t.

The Restaurant Analogy

Think of MCP like eating at a restaurant.

You sit down, get a menu (the list of tools the MCP server exposes), you choose what you want (Claude picks the right tool for the task), and a server prepares it for you (the MCP server executes the tool and returns results). You don’t cook anything yourself — you order, and it arrives.

For eating out, this is great. You get food you couldn’t easily make at home, prepared by specialists, without setting up your own kitchen.

For eating at home, you wouldn’t call a restaurant every time you want toast. You’d just make it yourself — or have someone in your household (a sub agent) prepare it for you.

MCP is eating out. It’s the right choice when the capability is hosted elsewhere, maintained by someone else, and you want it constantly available on a menu. It’s the wrong choice when you could just do the thing directly.

When to Use MCP

MCP makes sense in two specific situations:

1. The capability is hosted elsewhere and constantly needed

The service lives on a remote server, it’s maintained by a third party, and you want it available as a persistent menu of tools in every session. Examples: GitHub (issues, PRs, repos), Sentry (error monitoring), Notion (docs), Slack (messaging).

2. You need the menu-serve design pattern

The value comes from having a structured menu of operations that Claude can browse and invoke — and having the server execute them. This is the streaming, always-available, tool-discovery pattern that MCP provides natively.

When NOT to Use MCP

Most of the time, prefer simpler alternatives:

Situation Instead of MCP, use…
CLI tool exists for the service Just use the CLI directly. Claude works great with gh, aws, gcloud, kubectl, jq, curl, and most CLI tools. Try: “Use gh to list open PRs.”
You want Claude to run a script or tool Use a Skill that tells Claude how to run it, or a Sub Agent that runs it in isolation
One-off API call Use curl or WebFetch — no server needed
You wrote a custom tool for your project Make it a Skill or a Sub Agent with bash access. Simpler, no protocol overhead
You want to query a local database A sub agent with bash access to psql/sqlite3 is often simpler than an MCP server

Rule of thumb: If you can do it with a CLI command, a skill, or a sub agent — do that instead. MCP adds protocol overhead, another process to manage, and another thing that can break. Reserve it for things that genuinely benefit from the menu-serve pattern with an external host.

Adding an MCP Server 

# 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 authentication header
claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Local stdio server 

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

# Example: Database access
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@host:5432/mydb"

Important: All options (--transport, --env, --scope) must come before the server name. The -- separates the server name from the command that gets passed to the MCP server.

Note: The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.

Authentication for remote servers

Many cloud MCP servers use OAuth. After adding the server, authenticate inside Claude Code:

/mcp

Follow the browser flow to log in. Tokens are stored securely and refreshed automatically.

Managing Servers 

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# Check status inside Claude Code
/mcp

Scopes: Who Can See the Server

Scope Stored in Shared? Use for
local (default) ~/.claude.json No — just you, this project Personal servers, experiments, sensitive credentials
project .mcp.json (project root) Yes — committed to git Team-shared servers, project-specific tools
user ~/.claude.json No — just you, all projects Personal utilities you use across projects 
# Add a project-scoped server (shared with team)
claude mcp add --transport http notion --scope project https://mcp.notion.com/mcp

# Add a user-scoped server (personal, all projects)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

For team sharing via .mcp.json, Claude Code prompts for approval before using project-scoped servers. Reset with claude mcp reset-project-choices.

Environment variables in .mcp.json

Use ${VAR} or ${VAR:-default} for machine-specific paths and secrets:

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

🌳 MCP in Plugins

Plugins can bundle MCP servers alongside skills, agents, and hooks. When a plugin is enabled, its MCP servers start automatically. Define them in .mcp.json at the plugin root or inline in plugin.json.

See Plugins for details on plugin structure and distribution.

MCP Resources and Prompts

MCP servers can expose more than tools:

Resources — reference data with @server:protocol://path in your prompts. Type @ to see available resources from connected servers.

Prompts — server-provided commands available as /mcp__servername__promptname. Type / to discover them.

Tool Search (Scaling with Many Servers)

When you have many MCP servers, tool definitions can eat context. Claude Code automatically enables Tool Search when MCP tool descriptions exceed 10% of the context window — tools load on-demand instead of all at once.

Control with ENABLE_TOOL_SEARCH:

  • auto (default) — activates when tools exceed 10% of context
  • auto:5 — custom threshold (5%)
  • true — always on
  • false — disabled, all tools loaded upfront

Practical Tips

  • Check /mcp regularly to verify your servers are healthy and connected
  • Set MAX_MCP_OUTPUT_TOKENS if you work with servers that return large results (default: 25,000 tokens, warning at 10,000)
  • Import from Claude Desktop: claude mcp add-from-claude-desktop brings over your existing config
  • Claude.ai servers sync automatically if you’re logged in with a Claude.ai account
  • Use Claude Code as an MCP server for other apps: claude mcp serve exposes Claude’s tools via stdio

The Decision Checklist

Before adding an MCP server, ask yourself:

  1. Is there a CLI tool for this? → Use the CLI instead
  2. Can a skill or sub agent handle it? → Use those instead
  3. Is this a one-off call? → Use curl or WebFetch
  4. Is the capability hosted elsewhere and constantly needed? → MCP is a good fit
  5. Do I need the menu-serve pattern with streaming? → MCP is a good fit

If you answered yes to 4 or 5 — add the MCP server. Otherwise, keep it simple.

Next Steps

Claude and Claude Code are products of Anthropic, PBC. This guide is a community project and is not affiliated with or endorsed by Anthropic. Original content is licensed under CC BY 4.0 — the license does not cover Anthropic's product or official documentation.

This site uses Just the Docs, a documentation theme for Jekyll.