Claude Code MCP lets the agent call external tools (databases, GitHub, Slack, your own services) through a single open protocol. Add a server with claude mcp add, manage connections with /mcp, and the tools show up in your next session.
Out of the box, Claude Code can read your files and run shell commands. MCP is how it reaches everything else. The Model Context Protocol is the open standard Anthropic shipped in late 2024 to connect AI agents to external systems, and Claude Code is its reference implementation. Once you wire up an MCP server, Claude Code can query your Postgres database, open GitHub PRs, post to Slack, or pull Linear tickets, in context and mid-task, without copy-pasting anything. This guide is the practical path: add a server, understand the three transports, scope it correctly, and fix it when it breaks.
What MCP Is (and Why Claude Code Leans on It)
An MCP server is a small program that advertises a set of tools. A Postgres MCP server exposes "run a read-only query." A GitHub server exposes "list issues," "open a pull request," "comment on a PR." Claude Code connects to the server, sees those tools, and decides when to call them based on what you asked.
The reason this matters: without MCP, every integration would be bespoke glue code. With it, the integration is a reusable server that any MCP-capable agent can use. Anthropic created the protocol, so Claude Code's support is the deepest in the market: stdio, HTTP, and SSE transports, plus OAuth for servers that need authenticated access. The same server you configure today also works with Codex or Gemini CLI tomorrow; the protocol is the contract, not the agent.
One distinction worth keeping straight early: an MCP server adds tools the agent can call. A skill adds instructions the agent follows. They solve different problems and are often used together. A skill that says "use the database server to validate the schema before migrating" only works if the MCP server is connected.
How to Add an MCP Server to Claude Code
There is one command. Everything else is detail. To add a local server that Claude Code launches as a subprocess:
claude mcp add github -- npx -y @modelcontextprotocol/server-githubThe part after -- is the command Claude Code runs to start the server. To add a remote server reachable over HTTP:
claude mcp add --transport http linear https://mcp.linear.app/mcpPass environment variables (API keys, tokens) the server needs with -e:
claude mcp add postgres -e DATABASE_URL=postgres://localhost/mydb \
-- npx -y @modelcontextprotocol/server-postgresThen start Claude Code and run /mcp. You'll see each server's connection state and, for OAuth servers, a prompt to authenticate in your browser. Once a server shows connected, its tools are live for that session, with no restart needed. To see everything configured without opening Claude Code, use claude mcp list.
The Three Transports, and When Each One Fits
"Transport" just means how Claude Code talks to the server. Picking the wrong one is the single most common setup mistake, so it's worth 60 seconds of clarity.
| Transport | How it runs | Use it for |
|---|---|---|
| stdio | Claude Code spawns the server locally as a subprocess | Local tools: filesystem, a local database, anything that runs on your machine |
| HTTP | Claude Code calls a running remote endpoint (streamable HTTP) | Hosted services: a vendor's managed MCP server or a shared internal server |
| SSE | Remote endpoint using server-sent events for streaming | Older remote servers that predate streamable HTTP |
Rule of thumb: if the server is a package you install and run, it's stdio. If it's a URL someone gave you, it's HTTP (or SSE if their docs say so). Mixing these up (adding a URL as stdio) produces a server that never connects and gives no useful error, which is why the troubleshooting section below leads with it.
Scoping: Who Gets the Server
The same server can be configured at three levels, and the level decides who and what it applies to:
- Local:only you, only this project. Good for experiments and personal API keys you don't want in the repo.
- Project:committed to the repo as a
.mcp.jsonfile. Everyone who clones the project gets the same servers. This is how a team standardizes its toolchain. - User:available in every project you open. Good for servers you always want, like a personal notes or search server.
When a name collides across scopes, the narrower scope wins: local overrides project, project overrides user. Commit project scope deliberately: a .mcp.json that references a teammate's localhost service will fail for everyone else, so project-scoped servers should be ones the whole team can actually reach.
MCP Servers Worth Connecting First
The ecosystem is large and uneven. These are the categories that pay for themselves on day one for most developers:
- Version control:a GitHub or GitLab server turns "open a PR for this" into something Claude Code does itself instead of dictating
ghcommands. - Database:a Postgres or SQLite server lets the agent read your real schema before it writes a migration, which eliminates a whole class of guessed-column bugs.
- Issue tracking:Linear or Jira servers let the agent pull ticket context so "implement PROJ-412" actually means something.
- Browser/automation:a Puppeteer or Playwright server gives the agent a real browser for scraping, screenshots, and end-to-end checks.
Rather than hand-configuring each one, you can install a skill from PolySkill that bundles the server configuration and the usage instructions together, and every skill in the registry is security-scanned before listing. That matters more for MCP than almost anywhere else, since a malicious server runs with whatever access you grant it.
When MCP Is the Wrong Tool
Most guides only sell the upside, so here's the counterweight. MCP is not free: every connected server adds tool definitions to the context window and a connection to maintain. Three cases where you should not reach for it:
One-off tasks. If you need a value from an API exactly once, asking Claude Code to curl it is faster than standing up a server. MCP earns its cost through repeated use.
Things shell already does well. Reading and writing local files, running tests, git operations: Claude Code does these natively. A filesystem MCP server on top of that is usually redundant overhead.
Untrusted servers. An MCP server is code running with the access you give it. A community server with database write access is a supply-chain risk, not a convenience. Treat server selection with the same caution as any dependency: prefer official or scanned sources, and scope credentials tightly.
Troubleshooting MCP Connections
Server shows "failed" or never connects
Run the server's start command directly in a plain terminal first. If it doesn't run there, Claude Code can't run it either; it's a command, path, or dependency problem, not an MCP problem. Most "MCP is broken" reports are a missing npx package or a wrong binary path.
Connected, but the tools never get used
The server is fine; the agent just doesn't see a reason to call it. Be explicit ("use the postgres server to check the schema"), and confirm the tools are listed under /mcp. A server with zero advertised tools is misconfigured on the server side.
OAuth server stuck unauthenticated
Run /mcp, select the server, and complete the browser flow. Tokens expire. If a previously working server starts failing, re-authenticating through /mcp is the first thing to try.
Works for you, breaks for the team
A project-scoped .mcp.json referencing localhost or a personal key will fail for everyone else. Project scope must point at resources the whole team can reach; keep personal endpoints in local scope.
Start With One Server
Don't wire up ten servers on day one. Add the single one that removes your most repetitive copy-paste (for most people that's GitHub or a database) and use it for a week until reaching for it is reflex. Add the next only when a real task demands it. An over-stuffed MCP config is just context-window tax you pay on every prompt; a lean one is leverage.
Browse next: How to Add Skills to Claude Code (2026) | Claude Code Marketplace (2026) | Codex vs Claude Code (2026) | Claude Code Router (2026)
MCP Questions, Answered
How do I add an MCP server to Claude Code?
Run claude mcp add <name> -- <command> for a local stdio server, or claude mcp add --transport http <name> <url> for a remote one. The server's tools become available in your next session. Use /mcp inside Claude Code for connection status and OAuth.
What is MCP in Claude Code?
MCP (Model Context Protocol) is an open standard created by Anthropic for connecting AI agents to external tools and data. An MCP server exposes tools (querying a database, reading GitHub issues) and Claude Code calls them in context. It supports stdio, HTTP, and SSE transports with OAuth.
Where are Claude Code MCP servers configured?
Three scopes: local (just you, this project), project (committed to the repo in .mcp.json so the whole team gets it), and user (all your projects). Narrower scope wins on a name collision: local over project over user.
Why is my Claude Code MCP server not connecting?
Usually: a wrong command/path (test it in a plain terminal first), a missing environment variable or key, an OAuth server not yet authenticated (run /mcp), or a transport mismatch (a remote URL added as stdio). claude mcp list shows what's configured.
Do MCP servers work with agents other than Claude Code?
Yes. MCP is an open protocol, so the same server works with any MCP-capable client (Claude Code, Codex, Gemini CLI, and others). The integration isn't locked to one agent.