MCP: Connecting External Services

Out of the box, Claude Code knows your repository — files, git, the shell. It knows nothing about your Notion docs, your Figma designs, your Jira backlog, your Postgres database, or your Slack channels. The moment you find yourself copying data out of another tool and pasting it into chat, that is the signal you want MCP.

Model Context Protocol (MCP) is an open standard for AI-to-tool integrations. Think of it as a universal port: instead of Anthropic hand-building an integration for every service, any service can ship an MCP server that speaks the protocol, and Claude Code (the MCP client) plugs into it. Connect the server once and Claude can read and act on that system directly — no more paste-shuffling.

There are two pieces of vocabulary worth pinning down up front:

• MCP server — the thing you connect to (Notion's server, GitHub's server, a local database script). It exposes tools (actions Claude can call), resources (data Claude can read with @), and prompts (canned commands).
• Transport — how Claude talks to the server. HTTP is the recommended transport for remote cloud services; stdio runs a server as a local process on your machine; SSE is deprecated in favor of HTTP.

Once a server is connected, a request like "Add the feature in JIRA ENG-4521 and open a PR on GitHub" spans two external systems and your repo — Claude reads the issue, writes the code, and creates the PR, all in one loop.

You add servers from the terminal with claude mcp add. The flag that matters most is --transport, which picks how Claude connects.

Remote HTTP (recommended for cloud services). Most hosted servers — Notion, Stripe, Sentry, Slack — are remote HTTP:

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

# Real example: connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

Local stdio (for tools that need direct system access). A stdio server is a local process Claude spawns and talks to over standard in/out. Note the -- that separates Claude's flags from the command Claude should run:

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

# Example: a read-only PostgreSQL server
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Managing what you've added:

claude mcp list            # all configured servers
claude mcp get notion      # details for one server
claude mcp remove notion   # remove it

The official docs span the full menagerie of services — Notion, Figma, Slack, Jira, GitHub, Sentry, Google Drive, PostgreSQL, Airtable, and custom servers you build yourself — but they all reduce to the same three shapes above: a remote HTTP URL, a deprecated SSE URL, or a local stdio command.

Where a server's configuration lives determines which projects see it and whether your team shares it. Set this with --scope:

claude mcp add --transport http stripe https://mcp.stripe.com               # local (default)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp  # team-shared
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic  # everywhere

Project scope is the team play. It writes a .mcp.json at the repo root that you commit to version control, so every teammate gets the same tools. For safety, Claude prompts for approval before using project-scoped servers from .mcp.json (reset those choices with claude mcp reset-project-choices).

Loading servers ad hoc with --mcp-config. Instead of registering servers permanently, you can point a single session at a config — a file (or several), or inline JSON:

claude --mcp-config ./mcp.json                    # load servers from a file
claude --mcp-config '{"mcpServers":{...}}'         # or inline JSON

--strict-mcp-config ignores everything else. Normally --mcp-config servers load in addition to your local/project/user servers. Add --strict-mcp-config and Claude uses only the servers from --mcp-config — nothing from ~/.claude.json or .mcp.json. This is the clean, reproducible setup for CI and scripts, where you want a known-exact tool surface and no surprise servers leaking in.

Most cloud servers (Notion, Slack, Sentry, Jira) need you to log in before Claude can act on your account. Claude Code supports OAuth 2.0, and the flow is almost entirely hands-off.

1. Add the server as usual:
   bash Copy

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

2. Run /mcp inside Claude Code. The server shows up flagged as needing authentication (Claude marks a remote server this way when it returns 401 Unauthorized or 403 Forbidden).
3. Complete the login in your browser, then return to the terminal. That's it.

/mcp

The /mcp panel is your control center for connections: it lists every connected server, shows the tool count next to each, lets you authenticate OAuth servers, and offers Clear authentication to revoke access. Tokens are stored securely (system keychain on macOS) and refreshed automatically, so you log in once.

A few real-world wrinkles worth knowing:

• OAuth works on HTTP servers, not stdio (which runs locally and uses its own credentials).
• If the browser redirect fails after you log in, copy the full callback URL from the address bar and paste it into the URL prompt that appears in Claude Code.
• Some servers need a fixed callback port (--callback-port 8080) or pre-registered credentials (--client-id, --client-secret) when they don't support automatic Dynamic Client Registration.
• You can pin OAuth scopes with an oauth.scopes field in .mcp.json to restrict a server to a security-approved subset (e.g. "channels:read chat:write search:read" for Slack).

Here is the scaling problem. Every MCP tool has a JSON schema — its name, description, and parameters. A handful of servers can expose hundreds of tools, and if Claude loaded every schema into the context window at startup, your usable context would be gone before you typed a word. MCP definitions are verbose.

Tool search is the fix, and it is on by default. At session start, Claude loads only the tool names and each server's instructions — not the full schemas. When a task actually needs a tool, Claude calls a built-in ToolSearch tool to find the relevant ones, and only those schemas enter context. From your seat nothing changes: MCP tools work exactly as before. Behind the scenes, adding more servers now has minimal impact on your context window.

This is implemented with tool_reference blocks, which require a capable model: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support it. (On Vertex AI, support starts at Sonnet 4.5 / Opus 4.5.)

You control the behavior with the ENABLE_TOOL_SEARCH environment variable:

ENABLE_TOOL_SEARCH=false claude       # load all MCP tool schemas at startup
ENABLE_TOOL_SEARCH=auto:5 claude      # upfront only if under 5% of context

Exempting a server with alwaysLoad. Some tools you need on every turn — paying the search step each time is wasteful. Set "alwaysLoad": true in a server's config and all its tools load at startup regardless of ENABLE_TOOL_SEARCH. Use it sparingly: every always-loaded tool consumes context that could be conversation. A server can also mark individual tools with "anthropic/alwaysLoad": true in their _meta.

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Beyond tools (actions), MCP servers can expose two more things, plus you'll want to keep an eye on what all this costs in context.

Resources — read data with @ mentions. Just like you reference a file with @path/to/file, you reference an MCP resource with an @ mention. Type @ and connected servers' resources appear in the autocomplete alongside files. The reference format is @server:protocol://resource/path:

Can you analyze @github:issue://123 and suggest a fix?
Please review the API docs at @docs:file://api/authentication
Compare @postgres:schema://users with @docs:file://database/user-model

The referenced resource is fetched and attached before Claude responds. (You may also see the older @mcp_resource:protocol://path form referenced elsewhere — the current docs use @server:protocol://resource/path.)

Prompts — canned commands as slash commands. Servers can ship reusable prompts that surface as slash commands in the exact format /mcp__<server>__<prompt>. Type / to discover them; pass arguments space-separated:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

Names are normalized (spaces become underscores), and the prompt's result is injected straight into the conversation.

Watch per-server cost. MCP tools, results, and definitions all consume context and tokens. Two commands keep you honest:

• /mcp — shows the tool count per connected server, so you can spot a server flooding you with tools.
• /usage (aliases /cost, /stats) — session cost plus a breakdown by skill, subagent, plugin, and MCP server. This is where you discover one chatty server is eating your budget.

Skipping MCP entirely with --bare. When you want a fast, minimal session with no MCP discovery at all — plus no hooks, skills, plugins, auto-memory, or CLAUDE.md — launch with --bare. It leaves only Bash/Read/Edit and sets CLAUDE_CODE_SIMPLE. Perfect for a quick one-off where MCP startup would just be overhead.

claude --bare -p "summarize the git log of the last 10 commits"