What are MCPs?
are external processes running on your machine (or Anthropic's servers) that give Claude new tools it doesn't natively have. They're real server processes that expose callable tools — Claude calls them the same way it calls its built-in tools like Read or Bash.
Think of MCPs as plugins for Claude's tool system. Claude Code ships with built-in tools (file reading, editing, shell commands, web search), but MCPs extend that set with arbitrary new capabilities.
How MCPs Work
When you configure an MCP, you're telling Claude Code to:
- Start a process (e.g., a Node.js script, a Python server)
- Register its tools (the process declares what tools it offers)
- Make those tools available to Claude during the session
Claude doesn't know or care that a tool comes from an MCP rather than being built-in. It sees browser_navigate the same way it sees Read — as a callable tool with parameters and return values.
What is an MCP server in Claude Code?
Popular MCPs
These are the most widely used MCPs in the ecosystem, based on community adoption:
| MCP | What It Does | Why It's Useful |
|---|---|---|
| GitHub | Read issues, review PRs, interact with repos | Understands the why behind code by reading ticket context |
| Playwright | Browser automation — navigate, click, fill forms, screenshot | Verify that the UI Claude built actually works |
| Context7 | Fetch live documentation for libraries | Avoids deprecated API usage in fast-moving frameworks |
| Sequential Thinking | Structured step-by-step reasoning tool | Forces Claude to plan before acting on complex refactors |
| Database (Bytebase) | Query databases via natural language | Debug data issues without writing SQL manually |
| Brave Search | Web search with privacy | Give Claude access to current information |
| Sentry | Pull error data and investigation context | Faster debugging with real production telemetry |
Configuring MCPs
MCPs are configured in JSON — either globally (~/.claude.json) or per-project (.claude/settings.json):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"],
"env": {}
}
}
}This tells Claude Code: "When a session starts, run npx @playwright/mcp@latest and register whatever tools it exposes."
You can also manage MCPs from the command line:
# Add an MCP server
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest
# List configured MCPs
claude mcp list
# Remove an MCP
claude mcp remove playwrightHow does Claude treat tools from MCPs compared to its built-in tools?
Local vs Platform MCPs
| Type | Where It Runs | How You Configure It |
|---|---|---|
| Local MCPs | On your machine as child processes | command + args in JSON config |
| Platform MCPs | On Anthropic's servers | Through Claude.ai's "Connected Apps" settings, via OAuth |
From Claude's perspective, the tools work the same way regardless of where the server runs.
MCP Scopes
Where you configure an MCP determines who sees it:
| Scope | Config Location | Use Case |
|---|---|---|
| Local | .mcp.json in project root | Project-specific tools, shared via git |
| User | ~/.claude.json | Personal tools across all projects |
| Project | .claude/settings.json | Project settings (not always in git) |
For team use, putting MCP config in .mcp.json at the project root means everyone gets the same tools when they clone the repo.
What is the difference between local MCPs and platform MCPs?
Tool Search and Token Management
This is a practical issue that catches people off guard: each MCP's tool descriptions consume context window space. A single MCP (like GitHub) can add ~46,000 tokens of tool descriptions — roughly 25% of your available context window — before you've even typed a prompt.
Claude Code includes a tool search feature that loads tool descriptions on-demand rather than all at once. This is enabled by default for most MCPs. If you're running multiple MCPs and notice degraded performance or context limits, this is likely why.
Practical tips:
- Only install MCPs you actively use
- Prefer MCPs with fewer, focused tools over "kitchen sink" servers
- Use
claude mcp listto audit what's running
What makes MCPs unique among the five building blocks?
MCPs vs Plugins
Many in the marketplace are just MCP wrappers — they configure an MCP so you don't have to write the JSON manually. The plugin and the manual configuration produce identical results.
| Approach | Pros | Cons |
|---|---|---|
| Plugin install | One-click, auto-updates | Less control over config |
| Manual MCP config | Full control over args, env vars, flags | Manual setup, no auto-updates |
Practical rule: If you already have an MCP configured and working, don't install the plugin version — you'd get duplicate tools, which confuses Claude.
Troubleshooting
MCP configuration is the most common source of technical frustration. Here are the issues you'll likely hit:
| Problem | Likely Cause | Fix |
|---|---|---|
| "Connection refused" or server won't start | Wrong command or args in config | Test the command manually in your terminal first |
| MCP tools don't appear | Config file in wrong location | Run claude mcp list to verify; check scope |
| OAuth errors | Server requires preconfigured credentials | Check the MCP's docs for auth setup; use /mcp in-session to authenticate |
| Windows: "Connection closed" | npx needs a cmd /c wrapper on Windows | Use "command": "cmd", "args": ["/c", "npx", ...] |
| Slow responses / hitting context limits | Too many MCP tools loaded | Remove unused MCPs; rely on tool search |
Back up before editing config files. Some troubleshooting guides suggest editing .claude.json directly — but a malformed edit can overwrite authentication tokens and settings. Always back up the file first, or use the claude mcp add/remove commands instead of manual edits.
Security
MCP servers are powerful — they can read files, query databases, make network requests. This creates real security surface area:
- Third-party MCP servers are unverified. Anthropic's docs explicitly warn that community-built servers could expose you to prompt injection or data leakage.
- Prompt injection via MCPs: If an MCP fetches content from untrusted sources (web pages, emails, user input), that content could contain instructions that manipulate Claude's behaviour.
- Credential exposure: MCPs that require API keys or database credentials should use environment variables, not hardcoded values in config files that get committed to git.
For teams, Claude Code supports allowlists and denylists to control which MCP servers can be used across your organisation.
- Installing every MCP you find. Each MCP is a process registering tools Claude has to consider. More tools = more noise in tool selection = slower, less accurate responses. Install only what you actively use.
- Duplicating plugin and manual config. If you've manually configured an MCP, don't also install the plugin version — duplicate tools confuse Claude.
- Committing API keys in MCP config. Use environment variables or
.envfiles for secrets. Never commit credentials to version control. - Ignoring the token cost of tool descriptions. Each MCP adds tool descriptions to your context. Five MCPs can consume half your context window before you've even asked a question.
Key Takeaway
MCPs are the mechanism for giving Claude genuinely new capabilities. They're programs, not prompts — the only building block that adds new tools. But they come with operational costs: token overhead, config complexity, and security surface area. Use them deliberately, keep the set minimal, and secure them properly.