obsidian/wiki/claude-code/mcp-integration.md

title	aliases	tags	sources	created	updated
MCP Integration in Claude Code	mcp-servers model-context-protocol claude-mcp	claude-code mcp integrations tools authentication enterprise	raw/Connect Claude Code to tools via MCP.md	2026-04-17	2026-04-17

MCP Integration in Claude Code

Claude Code connects to external tools, databases, and APIs via the Model Context Protocol (MCP) — an open standard for AI-tool integrations. Instead of pasting data into chat, you connect a server once and Claude reads/acts on the system directly.

What MCP Enables

Claude Code can:

• Implement features from issue trackers (JIRA → GitHub PR)
• Analyze monitoring data (Sentry, Statsig, PostHog)
• Query databases (PostgreSQL, BigQuery, Supabase)
• Integrate design tools (Figma → code)
• Automate workflows (Gmail drafts, Slack messages)
• React to external events via channels (Telegram, webhooks, Discord)

Installing MCP Servers

Three Transport Types

Transport	When to Use	Command
HTTP (recommended)	Cloud services, remote APIs	claude mcp add --transport http <name> <url>
SSE	Deprecated — use HTTP instead	claude mcp add --transport sse <name> <url>
stdio	Local processes, direct system access	claude mcp add <name> -- <command> [args]

# HTTP example
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

# stdio example (Airtable)
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Option ordering rule: All flags (--transport, --env, --scope, --header) must come before the server name. -- separates the server name from its command.

Managing Servers

claude mcp list           # list all configured servers
claude mcp get <name>     # details for a specific server
claude mcp remove <name>  # remove a server
/mcp                      # check status inside Claude Code

Configuration Scopes

Scope	Loaded in	Shared	Stored in
local (default)	Current project only	No	~/.claude.json
project	Current project only	Yes (via .mcp.json)	.mcp.json in project root
user	All projects	No	~/.claude.json

claude mcp add --transport http stripe --scope project https://mcp.stripe.com
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

• Project scope → checked into version control → team shares same servers
• Claude Code prompts for approval before using .mcp.json project-scoped servers

Environment Variable Expansion in .mcp.json

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

Syntax: ${VAR} or ${VAR:-default}. Works in command, args, env, url, headers.

Authentication

OAuth 2.0

Run /mcp inside Claude Code to authenticate. Tokens are stored securely and auto-refreshed.

# Fixed callback port (for pre-registered redirect URIs)
claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp

# Pre-configured OAuth credentials
claude mcp add --transport http --client-id <id> --client-secret <secret> my-server <url>

Restrict OAuth Scopes

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": { "scopes": "channels:read chat:write search:read" }
    }
  }
}

Dynamic Headers (non-OAuth auth)

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

• Command must output a JSON object of string key-value pairs to stdout
• Runs fresh on each connection (10-second timeout, no caching)
• Available env vars: CLAUDE_CODE_MCP_SERVER_NAME, CLAUDE_CODE_MCP_SERVER_URL

Advanced Features

Dynamic Tool Updates & Reconnection

• MCP list_changed notifications → Claude Code auto-refreshes available tools without disconnect
• HTTP/SSE servers: auto-reconnect with exponential backoff (5 attempts, starting 1s, doubling each time)
• Stdio servers: not auto-reconnected (local processes)

Push Messages via Channels

MCP servers can push messages directly into your session (CI results, alerts, chat). Requires server declaring claude/channel capability + --channels flag at startup. See wiki/claude-code/overview.

Tool Search (context efficiency)

By default, MCP tools are deferred — only names load at session start, definitions fetched on demand.

ENABLE_TOOL_SEARCH	Behavior
(unset)	All tools deferred; falls back to upfront for non-Anthropic ANTHROPIC_BASE_URL
true	All tools deferred, always
auto	Load upfront if within 10% of context window, defer otherwise
auto:<N>	Custom threshold percentage
false	All tools loaded upfront

Requires Sonnet 4+ or Opus 4+. Haiku does not support tool search.

MCP Output Limits

• Warning at 10,000 tokens output
• Default max: 25,000 tokens (MAX_MCP_OUTPUT_TOKENS env var)
• Per-tool override via _meta["anthropic/maxResultSizeChars"] in tools/list response (max 500,000 chars)

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Claude Code as MCP Server

claude mcp serve   # expose Claude's tools (View, Edit, LS, etc.) to other MCP clients

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Enterprise / Managed MCP

Option 1: Exclusive control (managed-mcp.json)

Deploy to system path (requires admin):

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux/WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

Users cannot add/modify servers. Same format as .mcp.json.

Option 2: Allowlists / Denylists (policy-based)

In managed settings:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

• Denylist takes absolute precedence over allowlist
• Each entry: exactly one of serverName, serverCommand, or serverUrl
• Command matching is exact (order and all args must match)
• URL patterns support * wildcards
• allowedMcpServers: [] = complete lockdown (no MCP servers allowed)

Popular MCP Servers (Quick Reference)

Category	Server	Command
Issue tracking	Linear	claude mcp add --transport http linear https://mcp.linear.app/mcp
Issue tracking	Atlassian (Jira/Confluence)	claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp
Version control	GitHub	claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Monitoring	Sentry	claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Database	Supabase	claude mcp add --transport http supabase https://mcp.supabase.com/mcp
Design	Figma	claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp
Docs/Notes	Notion	claude mcp add --transport http notion https://mcp.notion.com/mcp
Automation	Zapier	claude mcp add zapier --transport http https://mcp.zapier.com/api/v1/connect
Search	Exa	claude mcp add --transport http exa https://mcp.exa.ai/mcp
Communication	Slack	claude mcp add --transport http --client-id ... --callback-port 3118 slack https://mcp.slack.com/mcp

Key Takeaways

• MCP replaces copy-paste: connect once, Claude reads/acts on the system directly
• HTTP transport is the recommended default for cloud services; SSE is deprecated
• Three scopes: local (default, private), project (team-shared via .mcp.json), user (cross-project)
• OAuth 2.0 is the standard auth flow; headersHelper handles non-OAuth schemes
• Tool search defers MCP tool definitions to keep context lean — enabled by default on Sonnet 4+
• Channels let MCP servers push events into your session (webhooks, alerts, chat)
• Enterprise control via managed-mcp.json (exclusive) or allowlist/denylist policies
• Dynamic reconnection on HTTP/SSE servers; stdio servers must be restarted manually

Sources

• raw/Connect Claude Code to tools via MCP.md (scraped from code.claude.com/docs/en/mcp, 2026-04-17)

Related

• wiki/claude-code/overview
• wiki/agent-sdk/_index
• wiki/architecture/_index