Claude Code MCP Servers Guide

Claude Code MCP Servers connect the assistant to external APIs and databases. Learn transport protocols, tool search, scopes, and multi-server configuration.

Claude Code MCP Servers: What You’ll Learn

In this guide to Claude Code MCP Servers, you’ll work through practical, hands-on steps with real examples. Claude Code MCP Servers is explained from the ground up so you can apply it immediately in your own projects.

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 quickest 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 migrated 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 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.json

MCP 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 456

The 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-code-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-code-plugins-official

Each 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.

Real-World MCP Server Examples

Example 1: GitHub MCP Server Configuration

Connect Claude Code to GitHub repositories, issues, and pull requests:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Or via CLI: claude mcp add --transport http github https://api.github.com/mcp

Example 2: Filesystem MCP Server

Give Claude Code access to files in a specific directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Example 3: Multi-Server Configuration

Configure multiple MCP servers in a single .mcp.json file for project-scoped access:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": { "SLACK_TOKEN": "${SLACK_TOKEN}" }
    }
  }
}

Team members will see an approval prompt when first encountering this project-scoped config.

Pro Tips

• Always use environment variables for credentials — never hardcode tokens in .mcp.json. Use ${GITHUB_TOKEN} syntax and store values in your shell profile. Commit .mcp.json to git with only env var placeholders.
• Use read-only tokens when possible — grant minimum permissions needed for each MCP server (least privilege). Rotate tokens monthly. Use OAuth for external services when available.
• Be aware of tool description limits — Claude Code enforces a 2KB cap per MCP server for tool descriptions. When tool descriptions exceed 10% of context, tool search activates automatically to select relevant tools efficiently.
• Monitor MCP output limits — outputs over 10K tokens show a warning; 25K tokens are truncated by default; results over 50K characters persist to disk. Increase the limit with export MAX_MCP_OUTPUT_TOKENS=*** if needed.
• Use alwaysLoad: true sparingly — mark a server's tools as always available only when needed on every turn. Every always-loaded tool consumes context that could otherwise surface more relevant tools via search.

Hands-On Challenge

Set up a multi-MCP server configuration that integrates external services into your Claude Code workflow.

Task: Build a Multi-Server MCP Configuration

Configure a project with three MCP servers — GitHub, Database, and Filesystem — and use them together in a real workflow.

Steps

1. Create a .mcp.json file in your project root with three MCP server configurations: GitHub, Database (PostgreSQL), and Filesystem.
2. Use environment variable expansion for all credentials: "GITHUB_TOKEN": "${GITHUB_TOKEN}" — never hardcode secrets in the config.
3. Add the servers via CLI as backup: claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github
4. Set up environment variables in your shell profile: export GITHUB_TOKEN="ghp_...code> and export DATABASE_URL="postgresql://..."
5. Run claude /mcp to verify all three servers connect and show non-zero tool counts.
6. Test the integration by asking Claude to "List all open PRs and cross-reference them with database records for deployed features."
7. Save the .mcp.json to git (with env var placeholders only) so teammates can use the same configuration.

Expected Outcome

All three MCP servers show as connected in /mcp with their tool counts. Claude can seamlessly query GitHub for PRs, check the database for deployment records, and read/write files — all in a single conversation. Teammates who pull the repo and set their own env variables get the same setup instantly.

Hint

Use the ${VAR:-default} syntax for environment variable expansion with fallback defaults. When MCP tool descriptions exceed 10% of context, Claude Code automatically enables tool search. Mark critical servers with "alwaysLoad": true to skip tool-search deferral. Check the multi-MCP workflow example in the MCP guide for a daily report generation pattern.

Knowledge Check

Test your understanding of Claude Code MCP Servers with these questions:

1. What are the supported transport protocols for MCP servers?
A) HTTP (recommended for remote), Stdio (recommended for local), SSE (deprecated) | B) WebSocket (recommended), REST, gRPC | C) TCP, UDP, HTTP | D) Stdio (recommended), HTTP, SSE
Answer: A — HTTP is recommended for remote servers. Stdio is for local processes (most common currently). SSE is deprecated but still supported.
2. How do you add a GitHub MCP server via CLI?
A) claude mcp install github | B) claude mcp add --transport http github https://api.github.com/mcp | C) claude plugin add github-mcp | D) claude connect github
Answer: B — Use claude mcp add with --transport flag, a name, and the server URL.
3. What happens when MCP tool descriptions exceed 10% of the context window?
A) They are truncated | B) Tool Search auto-enables to dynamically select relevant tools | C) Claude shows an error | D) Extra tools are disabled
Answer: B — MCP Tool Search auto-enables when tools exceed 10% of context. It requires Sonnet 4 or Opus 4 minimum.
4. How do you use environment variable fallbacks in MCP config?
A) ${VAR || "default"} | B) ${VAR:-default} | C) ${VAR:default} | D) ${VAR ? "default"}
Answer: B — ${VAR:-default} provides a fallback value if the environment variable is not set.
5. What happens when a team member first encounters a project-scoped .mcp.json?
A) It loads automatically | B) They get an approval prompt to trust the project’s MCP servers | C) It’s ignored unless they opt in via settings | D) Claude asks the admin to approve
Answer: B — Project-scoped .mcp.json triggers a security approval prompt on each team member’s first use to prevent untrusted MCP servers.

Additional Resources

Claude Code MCP Servers gives you a solid, repeatable workflow. Bookmark this Claude Code MCP Servers guide and revisit the steps whenever you need them.

A Worked Example: Connecting a GitHub MCP Server

Reading about MCP Servers configuration only gets you so far — the fastest way to understand the moving parts is to wire one up end to end. Here's what actually happens when you add a GitHub MCP server to a real project, from the first command to the point where a teammate clones the repo and hits the same server.

1. Add the server with a stdio transport. From inside your project directory, run:

   claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

   This launches the GitHub server as a local subprocess over stdio rather than connecting to a remote HTTP or SSE endpoint. Claude Code manages the process lifecycle for you — no separate terminal, no manual restart.

2. Store the token as an environment variable, never inline. The GitHub server needs a personal access token. Do not paste it directly into the command or into `.mcp.json`. Instead export it in your shell profile or an `.env` loaded before Claude Code starts:

   export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

   Then reference it in the server's env block using expansion syntax, which supports a fallback default if the variable is unset:

   {
     "mcpServers": {
       "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-github"],
         "env": {
           "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN:-}"
         }
       }
     }
   }

3. Know where the config lands. If you ran `claude mcp add` without a `--scope` flag while inside the repo, Claude Code writes the entry to a project-scoped `.mcp.json` at the repo root — meant to be committed so the whole team shares the same server definitions. If you'd added `--scope local`, it would instead land in your personal `~/.claude.json`, visible only to you and never checked into the repo. For a shared GitHub server, project scope is almost always the right call, with the actual secret kept out of the file via `${GITHUB_TOKEN}` expansion.

4. What a teammate sees after pulling. When a colleague pulls the branch containing the new `.mcp.json`, Claude Code detects an unapproved project-scoped server on their next session start and prompts them to approve it before it's allowed to run — a deliberate guardrail so nobody's session silently executes an arbitrary subprocess just because it showed up in git. Once they approve it, Claude Code expands `${GITHUB_TOKEN}` from their own shell environment, so each teammate authenticates with their own token even though the server definition is shared.

5. Verify the connection. Run the `/mcp` slash command inside a Claude Code session. It lists every configured MCP server, its transport, and connection status — confirm `github` shows as connected before relying on it.

6. Adding a second and third server stays lean thanks to tool search. As you add a database server and an internal deploy server alongside GitHub, the combined tool list from all three MCP servers could easily balloon your context. Claude Code's tool search indexes tool descriptions instead of loading every schema up front, so the model discovers and loads only the tools relevant to the current request — keeping a multi-server setup fast even as your roster of MCP Servers grows.

MCP Servers: Common Mistakes to Avoid

These are the mistakes that show up most often when teams start managing MCP Servers across a shared codebase — most are avoidable with a five-minute config review.

• Hardcoding tokens directly in `.mcp.json` instead of using `${VAR}` expansion. Writing `"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_realtoken123"` straight into the env block means the secret is now sitting in plain text in a file meant to be committed. Use `${GITHUB_TOKEN}` (or `${GITHUB_TOKEN:-default}` if you want a safe fallback) so the actual value only ever exists in each user's own shell environment.
• Committing a project `.mcp.json` with real secrets instead of placeholders. Even when a token is meant to be shared with `${VAR}` syntax, it's easy to accidentally commit a working copy that still has a literal value from local testing. Diff `.mcp.json` before every commit that touches MCP server config, and keep a `.mcp.json.example` with placeholder values for onboarding.
• Granting a server a broader, write-scoped token when a read-only token would do. A GitHub server used only for searching code and reading issues doesn't need a token with `repo` write and `delete_repo` scopes. Over-scoped credentials turn a compromised or misbehaving MCP server into a much bigger blast radius than the task requires — mint the narrowest token the server's actual usage justifies.
• Ignoring the 2KB tool-description cap and `MAX_MCP_OUTPUT_TOKENS` truncation on a chatty server. Some MCP servers return large payloads — full database rows, verbose API responses — that get silently truncated once they exceed `MAX_MCP_OUTPUT_TOKENS`, leaving Claude Code working from an incomplete result without an obvious error. Similarly, an overly long tool description gets cut at the 2KB cap, which can drop the exact detail that was supposed to steer tool selection. Keep tool descriptions concise and pair verbose servers with pagination or filtering arguments instead of relying on truncation to bail you out.

Claude Code MCP Servers: Best Practices

• Add only the MCP servers you trust; each one widens what the assistant can reach.
• Use tool search so large servers expose only the tools a task needs.
• Scope servers per project when their credentials differ.
• Prefer official servers for common APIs before building your own.
• Review server permissions the same way you review any third-party integration.

MCP Servers: Frequently Asked Questions

If a tool name exists in local, project, and user scope at once, which MCP server wins?

Claude Code resolves scope precedence local first, then project, then user. A local-scoped server defined in your personal `~/.claude.json` for a specific project overrides a project-scoped `.mcp.json` entry with the same name, which in turn overrides a global user-scoped definition. This lets you override a shared team server temporarily — say, pointing at a staging endpoint — without editing the committed config.

When should an MCP server use SSE, HTTP, or stdio transport?

Use stdio for local subprocess servers you run and manage yourself, like a local database or filesystem tool — it's the simplest and lowest-latency option. Use HTTP for remote MCP Servers exposed as a stateless request/response API. Use SSE when a remote server needs to push streaming or long-lived updates back to the client, such as progress notifications on a slow operation, since it keeps a persistent connection open rather than requiring the client to poll.

What does tool search do automatically, and when should I set `alwaysLoad: true`?

With `ENABLE_TOOL_SEARCH` on, Claude Code indexes tool descriptions from every configured server instead of injecting every tool schema into context up front, then loads only the tools relevant to the current request as it works. Mark a tool `alwaysLoad: true` when it's small and used constantly enough that the lookup overhead isn't worth it — for everything else, letting tool search handle discovery keeps sessions with many MCP Servers from bloating context.

What is MCP elicitation, and how do the Elicitation hooks fit in?

Elicitation lets an MCP server pause mid-call and ask the user a follow-up question — for example, a deploy server confirming which environment to target before it acts. Claude Code exposes this through `Elicitation` and `ElicitationResult` hooks, so you can intercept the prompt, log it, or auto-respond in automated contexts instead of leaving every elicitation waiting on interactive input.

How are Channels (Telegram, Discord, iMessage) different from a standard MCP server?

A standard MCP server extends what Claude Code can do inside a session — tools, resources, prompts. Channels are push-oriented: once `channelsEnabled` and a channel like Telegram or Discord are paired, Claude Code can notify you or resume a conversation from an external message, rather than only responding to requests you initiate locally. They ride on the same connection and reconnection machinery as other MCP Servers, including `list_changed` notifications and backoff on reconnect, but the interaction model is inverted — the server can reach you, not just the other way around.