Claude Code MCP Servers

MCP servers let Claude Code connect to external tools and data sources through the Model Context Protocol. A server can expose tools, prompts, and resources that Claude Code can use during a session.

Think of MCP as a bridge. Instead of pasting issue text, database schemas, browser state, or internal docs into chat, you connect a server that lets Claude Code request the exact external context it needs.

Last checked on May 24, 2026. MCP behavior and Claude Code tool search are moving quickly. Treat every MCP server as code with tool access, not as harmless decoration.

Short Answer

Use MCP when Claude Code needs a real external capability. Do not add servers just because they exist.

When MCP Is Worth It

The best first MCP server is the one attached to a workflow you already repeat every week.

Basic claude mcp add Syntax

The command shape matters:

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

Options such as --transport, --env, --scope, and --header go before the server name. The -- separator means everything after it is passed to the MCP server process.

Example local stdio server:

claude mcp add --transport stdio docs -- npx -y @example/docs-mcp

Example HTTP server:

claude mcp add --transport http stripe https://mcp.stripe.com

Example with environment variable:

claude mcp add --transport stdio --env GITHUB_TOKEN=$GITHUB_TOKEN github \
  -- npx -y @example/github-mcp

If a command fails, check option order first. Many MCP install problems come from putting --env or --scope after the server name.

MCP Scopes

Choose the scope before adding the server.

Project scope is powerful because it makes tools consistent across a team, but it deserves review. Do not commit secrets into .mcp.json.

Project-scoped example:

claude mcp add --transport http --scope project docs https://mcp.example.com/mcp

Result shape:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Managing Servers

Useful commands:

Use /mcp first when a server looks connected but tools are not available.

Transports and Authentication

For remote servers that need OAuth, use /mcp in Claude Code to complete the browser login flow. Store client secrets in secure credential storage or environment variables, not in committed config.

Tool Search and Context

MCP can bloat context if every tool schema loads upfront. Claude Code's tool search helps by deferring tool definitions until Claude needs them. In practice:

• Adding more servers does not always mean every tool consumes full context immediately.
• Large tool outputs still consume context once used.
• Some environments or providers may disable tool search.
• alwaysLoad can force a server's tools to load upfront, but use it sparingly.

If an MCP answer is too large, narrow the request before raising output limits. MAX_MCP_OUTPUT_TOKENS is a last resort, not a default tuning knob.

Safe Setup Checklist

1. Start with one server.
2. Prefer read-only credentials for first tests.
3. Use local scope until the team agrees a server should be shared.
4. Keep secrets out of .mcp.json.
5. Verify server source, package name, and update history.
6. Use Plan Mode before allowing tools that can write, deploy, or mutate data.
7. Watch /mcp status and context size after adding the server.
8. Remove unused servers.

Treat MCP like adding a new integration to your development environment. It deserves the same review as a GitHub app, database client, or CI secret.

Good MCP Prompts

For GitHub:

Use the GitHub MCP server to inspect issue #42 only.
Summarize acceptance criteria, likely files, and risks.
Do not modify code yet.

For docs lookup:

Use the docs MCP server to check the current API shape.
Return only the fields needed for this implementation and link the source.

For databases:

Use the database MCP server in read-only mode.
Inspect the schema for users and subscriptions, then propose a migration plan.
Do not run writes.

Risky prompt:

Read every issue, all tables, and the whole repo, then fix everything.

MCP vs Plugins vs Skills

MCP is strongest when the missing piece is external capability, not when the problem is merely repeated instructions.

Troubleshooting

claude mcp add fails

Check option order and the -- separator. Confirm the command runs outside Claude Code and that required env vars are available.

Server appears but tools are missing

Open /mcp, check status, authentication, and whether the server exposes tools. Some servers expose resources or prompts rather than tools.

.mcp.json prompts for approval

That is expected for project-scoped servers. Review the config before approving. Use claude mcp reset-project-choices if you need to revisit prior approval decisions.

MCP output floods the session

Ask narrower questions, filter at the server level, or summarize resource lists before reading detailed resources. Raising MAX_MCP_OUTPUT_TOKENS should be rare.

Claude.ai connector does not appear in Claude Code

Check /status. Claude.ai connectors only load when the active authentication path is the Claude.ai subscription path, not when API key/provider auth is active.

Related Guides

• MCP directory
• GitHub MCP
• Context7 MCP
• Playwright MCP
• MCP security checklist
• Tools allowlist

Official Sources

• Claude Code MCP docs
• Agent SDK MCP docs
• Managed MCP configuration
• Claude Code commands
• Model Context Protocol