MCP (Model Context Protocol) gives Claude real-time access to external services. Unlike memory files that store static context, MCP connections let Claude query live data — your GitHub issues, production database, Slack channels, or any service with an MCP server. This module covers adding servers, understanding scopes, and using MCP tools effectively.
Adding MCP Servers
The fastest way to add a server is the claude mcp add command. Choose the transport that matches the server type: http for remote servers, stdio for locally-running processes, and sse for older remote servers that haven’t moved to HTTP yet. (Note: SSE is deprecated — use HTTP servers instead, where available.) On native Windows you’ll often use cmd /c when launching npx-based stdio servers.
# Add a remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Add a local Node.js server via stdio
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github
# Add with an auth header
claude mcp add --transport http my-api https://api.example.com/mcp \
--header "Authorization: Bearer $MY_TOKEN"Manage your servers with claude mcp list, claude mcp get <name>, and claude mcp remove <name>. The /mcp command inside a session shows active connections and triggers OAuth flows for servers that require browser-based authentication. Other useful commands include claude mcp reset-project-choices, claude mcp add-from-claude-desktop, and claude mcp serve when you want Claude Code itself to act as an MCP server.
MCP configurations live in ~/.claude.json (your local user config) or .mcp.json in the project root (shared with the team). The .mcp.json file is checked into git and prompts teammates for approval on first use. Environment variable expansion works in all configuration fields — use ${VAR:-default} for fallbacks:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}For one-off sessions — quick experiments, CI runs, or sandboxed reproductions — --mcp-config loads MCP servers from JSON files instead of touching your saved config. The flag accepts one or more file paths (space-separated), so a single command can layer a shared config on top of local overrides. Pair it with --strict-mcp-config to ignore every other MCP source for that session, which is the cleanest way to reproduce a bug against a known server set:
# Load a single config file for this session only
claude --mcp-config ./ci-servers.json
# Combine multiple files (space-separated)
claude --mcp-config "./shared-servers.json ./local-overrides.json"
# Reproduce a bug against exactly one server, ignoring user/project config
claude --strict-mcp-config --mcp-config ./repro.jsonMCP servers now connect concurrently by default. When you have multiple servers configured — both local stdio servers and remote claude.ai connectors — they initialize in parallel at startup rather than one at a time. This significantly reduces startup latency for projects with several MCP integrations.
Configure MCP server startup timeout using the MCP_TIMEOUT environment variable (for example, MCP_TIMEOUT=10000 claude sets a 10-second timeout).
MCP connectors configured in Claude.ai can also appear automatically in Claude Code. If you set up a server through the web interface, it becomes available in your CLI sessions without separate local configuration. When the same server is configured both locally and via Claude.ai, duplicates are automatically deduplicated so you don’t end up with two connections to the same service.
Scopes and Tool Discovery
MCP configurations have three scopes. Local scope (stored in ~/.claude.json under your project’s key) is private — just you, just this project. Project scope (.mcp.json) is shared with the team via git. User scope (~/.claude.json globally) applies across all your projects.
When the same server is defined at multiple scopes, the local configuration wins. This lets you override a team-wide server config with a local version for testing without affecting anyone else.
MCP prompts appear as slash commands using the pattern /mcp__servername__promptname. MCP resources can be referenced inline with @server:protocol://resource/path. Tool search is enabled by default — MCP tool definitions are deferred and discovered on demand, so only the tools Claude actually uses for a task enter context (it’s off by default only on Vertex AI and when ANTHROPIC_BASE_URL points to a non-first-party proxy). Override it with the ENABLE_TOOL_SEARCH environment variable: true forces it always on, false loads every definition upfront on every turn, and auto activates tool search only when tool definitions exceed 10% of the context window (auto:N sets a custom percentage). Individual MCP tool descriptions and server instructions are each capped at 2KB to prevent OpenAPI-generated servers from bloating context. A runtime warning appears when an MCP tool’s output exceeds 10,000 tokens. To increase this limit, set the MAX_MCP_OUTPUT_TOKENS environment variable (default 25,000).
To override deferral for a specific server, add alwaysLoad: true to its config — all tools from that server will skip tool-search deferral and always be available in the session:
Subagent-scoped MCP lets you give specific agents access to servers that the rest of the session doesn’t need:
---
name: data-analyst
description: Analyze production data
mcpServers:
- database
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---Practical Usage Patterns
With the GitHub MCP connected, you can work with PRs, issues, and commits using natural language. Claude queries the server, gets live data, and responds:
List all open PRs that haven't been reviewed in more than 3 days.
Create an issue for the login timeout bug with medium priority.
/mcp__github__pr_review 456The database MCP enables natural language queries without writing SQL yourself:
Find all users who placed more than 5 orders in the last 30 days.
What's the average order value by country for Q1 2026?For complex workflows, multiple MCP servers compose naturally. A daily report workflow might: fetch PR metrics from GitHub MCP, query sales data from the database MCP, write a report using the filesystem MCP, and post it via Slack MCP — all in a single session.
MCP elicitation lets a server pause the workflow and request structured input from the user. When a server needs information it can’t get on its own — an OAuth authorization, a confirmation before a destructive action, or a form with project-specific parameters — it triggers an interactive dialog. The user sees form fields or a browser URL, provides the response, and the server resumes where it left off. The Elicitation and ElicitationResult hooks let you intercept or customize these dialogs programmatically.
Security best practices: always use environment variables for credentials, never commit tokens to git, use read-only tokens when you only need to query data, and limit server access scope to the minimum needed. For enterprise deployments, managed-mcp.json lets administrators enforce an allowlist of permitted servers organization-wide.
Other important MCP capabilities worth knowing: MCP servers can send list_changed notifications to dynamically update their available tools, prompts, and resources without requiring reconnection. If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff — up to five attempts, starting at a one-second delay and doubling each time. For initial connections at startup, the same backoff applies but retries up to three times on transient errors such as a 5xx response, a connection refused, or a timeout (as of v2.1.121).
Channels: Push Events Into a Running Session
Channels are MCP servers that push events into your running session so Claude can react while you’re away from the terminal. Unlike standard MCP servers that Claude queries on demand, a channel delivers messages proactively — a chat bridge from Telegram, a CI webhook, or a monitoring alert. Events only arrive while the session is open.
Three channel plugins are included in the research preview (requires Claude Code v2.1.80 or later): Telegram, Discord, and iMessage. Each is installed as a plugin and configured with your own credentials. Install a channel plugin with /plugin install telegram@claude-plugins-official, configure it with the plugin’s /telegram:configure <token> command, then restart with the --channels flag to activate it:
claude --channels plugin:telegram@claude-plugins-officialEach channel maintains a sender allowlist — only IDs you’ve added can push messages. Telegram and Discord use a pairing flow: message your bot, receive a code, then approve it in Claude Code with /telegram:access pair <code> and lock down with /telegram:access policy allowlist. iMessage bypasses pairing for self-chat and lets you add contacts by handle.
Channels require Anthropic authentication (claude.ai or Console API key) and are not available on Bedrock, Vertex AI, or Foundry. Team and Enterprise organizations must enable channels via channelsEnabled in managed settings — they’re blocked by default. Pro and Max users can use channels directly by opting in per session with --channels. Admins can also restrict which plugins are allowed via the allowedChannelPlugins managed setting.
When Claude replies through a channel, the reply appears on the external platform (Telegram, Discord, etc.) — your terminal shows the tool call and confirmation but not the reply text itself.