Claude Code MCP Servers: Setup Guide + The Best Ones

What Is an MCP Server (in Claude Code)?

An MCP server is a small program that exposes a set of tools to Claude Code over the Model Context Protocol. Once it's configured and connected, Claude Code can call those tools the same way it calls its built-in file, bash, and search tools. MCP is the plug; the server is what you plug in.

Out of the box, Claude Code MCP support is what lets the agent reach beyond the repo it was launched in. Each server bundles a related set of capabilities behind one connection. Add a filesystem server and Claude can move assets between projects. Add a browser server and it can click through your deployed site. Add a code-navigation server and it reads functions and references instead of dumping whole files into context.

The two kinds of MCP server

Every server you add falls into one of two categories, and the category decides how you configure it:

• Local (stdio) servers run on your machine. Claude Code launches them with a command and args (for example npx or uvx). They have no transport type — they talk over standard input/output. Serena, Desktop Commander, and Playwright are local.
• Remote (HTTP) servers live at a URL. You give Claude Code a url, usually an Authorization header with a key, and a type that names the transport. Jina and Stripe are remote. The type is where the famous gotcha lives.

How to Add an MCP Server

Adding a Claude Code MCP server is two decisions: where the config lives, and (for remote servers) which transport to declare. Get both right and the rest is copy-paste.

Step 1: Pick where the config goes

MCP servers are declared under an mcpServers object. There are three places that object can live:

Step 2: Add the server

A local stdio server is just a command Claude Code runs. Here's Serena, which adds semantic code navigation:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide-assistant"
      ]
    }
  }
}

A remote server points at a URL, carries a key, and — critically — declares a type. Here's a streamable-HTTP server:

{
  "mcpServers": {
    "jina": {
      "type": "http",
      "url": "https://mcp.jina.ai/",
      "headers": {
        "Authorization": "Bearer YOUR_JINA_API_KEY"
      }
    }
  }
}

Prefer the CLI? You can add either kind without hand-editing JSON, then list what's registered:

# local stdio server
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant

# remote http server
claude mcp add-json jina '{"type":"http","url":"https://mcp.jina.ai/",
  "headers":{"Authorization":"Bearer YOUR_JINA_API_KEY"}}'

claude mcp list   # verify what's registered

After any change, fully restart Claude Code. MCP servers load at startup, so an edit made mid-session does nothing until you relaunch.

The http-vs-sse gotcha (read this twice)

This is the single most common reason a remote Claude Code MCP server "won't connect" even though the config looks perfect. Remote servers speak one of two transports, and the type in your config has to match what the endpoint actually serves:

• Streamable HTTP — the current standard. Use "type": "http". A modern endpoint such as /mcp almost always wants this.
• SSE (server-sent events) — the older transport, still used by some legacy endpoints. Use "type": "sse".

Two rules keep you out of trouble. Don't guess the transport from the URL — an /sse path usually means sse, but check the server's docs. And remember that local command-based servers have no type at all; only remote url servers need one.

The Best MCP Servers for Claude Code

You don't need thirty servers. A long list bloats your tool palette and slows startup. This is the focused set we actually use for client work — each one earns its slot by doing a job the built-in tools can't.

Serena — the token saver

Serena reads your code as symbols rather than dumping entire files into context. On a large codebase that's the single biggest token reduction available: an agent can find and read just the relevant function instead of a 2,000-line file. It runs locally via uvx, so it needs uv installed, and it indexes the project on first run. If your bills are the problem, pair it with our notes on Claude Code token optimization.

Desktop Commander — files and shell

Desktop Commander handles file and command operations that reach beyond the repo Claude Code was launched in — useful for multi-project workflows, moving assets, and batch operations. It's broad and powerful: it can touch anything your user account can, so keep destructive actions behind a confirmation step. There's a full walkthrough on our Desktop Commander MCP page.

Playwright, Jina, and Stripe

Playwright gives an agent a real browser, which is how a shipper agent confirms the live site actually works instead of assuming. Jina turns any URL into clean markdown and adds web search, which is what a researcher reaches for when the answer is online. Stripe lets you stand up a product or payment link from inside the terminal. Both Jina and Stripe are remote streamable-HTTP servers, so they use type: "http" — and for Stripe, always use a restricted, test-mode key while you build.

Verifying a Server Is Connected

Adding the config is half the job. Confirming the server is actually live is the other half — and the step most people skip, which is why they think MCP "doesn't work."

• Restart, then run /mcp. This in-session command lists every configured server and whether it connected. A healthy setup shows each one as connected.
• Run claude mcp list. From the CLI, this shows what's registered and its scope, which helps when a server is defined in one file but you expected another.
• Exercise a tool. Ask the agent to use the server for something concrete — "use Serena to list the symbols in this file," or "use Playwright to open example.com and tell me the H1." A successful call proves the connection end to end, not just that the config parsed.

MCP + Subagents: Giving Your Agent Team Real Hands

MCP servers get far more powerful when you combine them with subagents. A subagent runs in its own context window and can be granted its own set of tools — including MCP tools. That lets you build a team where each role has exactly the hands it needs and nothing more.

Map the servers above onto a real five-agent team and the picture is clear:

• Researcher — read-only. Gets Serena (scan code by symbol) and Jina (read the web). It investigates and cites; it never writes.
• Implementer — gets Desktop Commander to write files and run commands. It makes the change the researcher scoped.
• Reviewer — read-only again, Serena only. It checks the change against the plan without the power to "fix" things itself.
• Shipper — gets Playwright to load the deployed page and verify it before declaring done.

Because each subagent has its own context, a heavy research sweep with Serena and Jina never bloats the implementer's window. This is where MCP stops being a list of toys and becomes the nervous system of an agent team. The same idea drives our Claude Code skills and the standards you set in your CLAUDE.md file. The free agent team starter pack ships this exact wiring.

Troubleshooting MCP Connections

When a Claude Code MCP server misbehaves, the cause is almost always one of a handful of things. Work the list in order.

If you remember nothing else: transport, then key, then restart. That sequence clears the vast majority of connection problems. The http-vs-sse flip alone resolves most "won't connect" cases, because the failure is silent and the config genuinely looks correct.

MCP Best Practices

A few habits keep your MCP setup fast, safe, and predictable.

• Only load what you use. Every connected server adds tools to the palette and time to startup. Install a server when you have a job for it, not in case you might. Five focused servers beat thirty idle ones.
• Least privilege per subagent. Read-only roles (researcher, reviewer) should get read-only tools. Don't hand a reviewer the ability to write files — the point of the role is that it can't.
• Restricted, test-mode keys. For anything that touches money or production (Stripe especially), use a restricted key scoped to what you need, and a test-mode key while building.
• Keep keys out of git. Put keyed servers in .claude/settings.local.json (gitignored) and keyless ones in the committed config. Or use ${VAR} expansion so a committed file references Bearer ${JINA_API_KEY} while the real value stays in your shell profile or a gitignored .env.
• Scope deliberately. Global config for tools you want everywhere (Serena, Desktop Commander, Playwright); project config for servers tied to one repo.

Frequently Asked Questions