Claude Code MCP Servers

Connect Claude Code to MCP servers safely: choose local or remote transport, grant MCP tool permissions, debug failures, and manage tool search.

Model Context Protocol, or MCP, lets Claude Code connect to external tools and context sources. Use it when Claude needs something outside the repository, such as GitHub issue context, browser automation, current documentation, internal APIs, or a controlled database query.

Quick Answer

Add an MCP server only when it gives Claude Code a concrete capability that the built-in file, search, edit, and shell tools do not already provide. Start with read-only workflows, grant explicit MCP tool permissions, and document why each server exists.

Use MCP for	Avoid MCP for
Reading GitHub issues, PRs, and repo metadata	Replacing normal file search inside the repo
Browser checks against a local preview	Giving broad browser automation to every session
Current framework docs or API references	Fetching docs that can be linked directly
Internal tools with clear auth boundaries	Tools with unclear ownership or token scope
Shared team context that changes often	One-off notes better stored in `CLAUDE.md`

How MCP Fits Claude Code

An MCP server exposes tools, prompts, or resources to Claude Code. Claude can discover those capabilities and request to use them during a task.

The important security point: MCP tools are still tools. They need permission rules just like file edits, shell commands, WebFetch, and subagents.

Layer	What it controls
Server configuration	Which MCP servers Claude Code can connect to.
Tool permission	Which MCP tools Claude Code may call.
Credential scope	What the underlying API token or OAuth grant can access.
Prompting	Whether you ask for a specific MCP workflow or vague external access.

Choose The Right Server Type

Server type	Good fit	What to verify
Local stdio	Local tools, scripts, filesystem helpers, test services	Command path, package manager, environment variables, working directory.
Remote HTTP	Hosted tools, SaaS integrations, organization services	URL, OAuth flow, headers, organization access, uptime.
Remote SSE	Legacy servers that have not moved to HTTP	Whether an HTTP endpoint exists; SSE is deprecated where HTTP is usable.
Project-scoped config	Team-shared setup for one repository	Whether `.mcp.json` should be committed and approved by each developer.
Managed MCP	Organization-controlled MCP servers	Admin allowlist, denylist, managed settings, and policy source.

Choose The Right Installation Scope

The transport decides how Claude Code connects to the server. The scope decides where the configuration lives and who receives it.

Scope	Loads in	Shared with team	Stored in	Use it for
`local`	Current project only	No	`~/.claude.json`	Personal experiments, private credentials, one-off servers.
`project`	Current project only	Yes	`.mcp.json` in the repo root	Team-standard servers everyone should review and approve.
`user`	All your projects	No	`~/.claude.json`	Personal utilities used across many repos.

Use the --scope flag when adding a server:

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

When the same server name appears in multiple places, Claude Code uses the highest-precedence definition: local, then project, then user, then plugin-provided servers, then Claude.ai connectors.

For team-shared .mcp.json, keep secrets out of the file and use environment variable expansion such as ${API_KEY} or ${API_BASE_URL:-https://api.example.com}. Claude Code asks for approval before using project-scoped servers from .mcp.json, so treat that file like code review material.

Minimal Setup Workflow

Pick one workflow, such as "read GitHub issues" or "query current library docs."
Add one MCP server using the official server documentation.
Run /mcp in Claude Code and confirm the server connects.
Grant only the MCP tools needed for the workflow.
Test on a small repository before using the server on production work.
Document the server purpose, owner, credentials, and permission boundary.

Permission Pattern

MCP tools follow a naming pattern like:

mcp__<server-name>__<tool-name>

For example, a GitHub server might expose tools such as:

mcp__github__list_issues
mcp__github__get_pull_request

Grant specific tools when possible. Use wildcards only when the whole server is trusted for that workflow:

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__get_pull_request",
      "mcp__context7__*"
    ]
  }
}

Do not rely on acceptEdits to approve MCP access. Official docs distinguish file edit approval from MCP tool approval. If you need MCP access, configure MCP tool permissions directly.

Tool Search And Context Cost

Some MCP servers expose many tools. Loading every tool into context can make Claude Code slower and less focused. Claude Code can defer MCP tools and discover them through Tool Search when needed.

Situation	Recommendation
Small server with a few always-used tools	Loading upfront is usually acceptable.
Large server with many rarely-used tools	Let Tool Search discover tools on demand.
A core internal tool needed every session	Consider an always-loaded server only if the context cost is justified.
Tool output is huge	Ask for a filtered query or summary instead of dumping everything.

Your prompt should name the server and action:

Use the GitHub MCP server to read issue 42 and summarize reproduction steps. Do not edit files.

This is better than:

Look at GitHub.

Debugging Checklist

If the MCP server fails, check in this order:

Symptom	What to inspect
Server not listed	Run `/mcp`, verify config location, server name, and JSON syntax.
Server listed but disconnected	Run the command or remote URL outside Claude Code.
Tool visible but denied	Check `permissions.allow`, deny rules, and organization policy.
OAuth fails	Re-run provider auth and confirm account or organization access.
Tool output too large	Narrow the query, request pagination, or ask for a summary.
Works locally but not for teammates	Check environment variables, `.mcp.json`, and whether approval is project-scoped.

Team Security Checklist

Keep tokens out of CLAUDE.md, prompts, screenshots, and committed config.
Prefer read-only tokens for new MCP servers.
Grant one server for one workflow before expanding.
Avoid broad wildcards on write-capable tools.
Review shared .mcp.json changes like code.
Record server purpose and owner in project docs.
Disable or remove MCP servers that are no longer used.

Official Sources

Next: Custom Commands - Create repeatable shortcuts once your tool surface is stable.

Claude Code MCP Servers

On this page