Guide

Claude Code MCP servers: what they are and how to set them up

Claude Code MCP servers are small programs that connect the agent to external tools and data over a standard protocol, so it can do far more than edit local files and run shell commands. MCP stands for the Model Context Protocol — an open, vendor-neutral way for an AI agent to discover and call tools that live outside it. Plug in a GitHub server and Claude Code can open pull requests; plug in a Postgres server and it can run read-only queries against your database; plug in Sentry, Linear, or Playwright and it can pull production errors, file issues, or drive a real browser. The server is the adapter; the protocol is what makes one set of plumbing work across every MCP-aware agent.

The mental model is simple: an MCP server advertises a list of tools, and the agent calls them the same way it calls its built-in ones. You don't teach Claude Code about GitHub's API; you connect a GitHub MCP server, and the agent sees a handful of new tools it can invoke when a task needs them. This guide covers the three pieces you need to get there: the scopes and where config lives, the real claude mcp add command, and a few servers worth starting with — plus an honest warning, because every server you add is code you're trusting.

What MCP is

MCP is a standard for connecting AI agents to outside systems. Before it existed, every integration was a one-off: someone hard-coded GitHub support into one tool, Slack into another, and none of it transferred. The protocol fixes that by defining a common language for a client (Claude Code) and a server (the integration) to talk — the server says “here are the tools I offer and what arguments they take,” and the client calls them. Write a server once and it works in any MCP-aware client.

Servers come in two flavors. A stdio server is a local process Claude Code launches and talks to over standard input/output — good for tools that need direct access to your machine, like a filesystem or a local database. A remote server runs elsewhere and is reached over HTTP; this is the recommended shape for hosted services (the older SSE transport still exists but has been deprecated in favor of HTTP). Either way, the agent doesn't care — it just sees tools it can call.

Scopes and the config file

Claude Code stores MCP server configuration at one of three scopes, and picking the right one is half the setup. The scope decides who can see the server and which file the config lands in.

• local (the default) — available only to you, only in the current project. Config goes into ~/.claude.json, keyed to that project's path. Use it for personal, machine-bound tools you don't want to share.
• project — shared with everyone working in the repo, via a .mcp.json file at the project root. This is the file you commit to git so your whole team gets the same servers. Use it for the tools the project itself depends on.
• user — available to you across all your projects. Like local, it lives in ~/.claude.json, but it isn't tied to one repo. Use it for tools you want everywhere, like a personal issue tracker.

When the same server name exists at more than one scope, the more specific scope wins — a project-level entry overrides a user-level one of the same name, so a team can standardize a setup without stepping on anyone's personal config. The project file, .mcp.json, uses an mcpServers object keyed by server name. A minimal entry looks like this (note the literal braces — this is JSON):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "env": { "PGPASSWORD": "..." }
    }
  }
}

The three fields you'll use most are command (the executable, on your PATH or an absolute path), args (an array of arguments), and env (a map of environment variables, all string values). Remote servers swap command for a type of http and a url instead. Keep real secrets out of a committed .mcp.json — point env at variables your shell already exports rather than pasting tokens into the file.

Adding a server with claude mcp add

You rarely edit the JSON by hand. The claude mcp add command writes the right entry to the right file for the scope you choose. The one rule that trips people up: all the flags go before the server name, and a bare -- separates the name from the command a stdio server should run.

For a local stdio server — here, a filesystem server scoped to your whole user account:

claude mcp add --scope user filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/code

For a remote HTTP server — the hosted GitHub server, shared with the project so your team gets it:

claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/

Pass headers for authenticated remotes with --header (for example --header "Authorization: Bearer $TOKEN"), and inject environment variables into a stdio server with --env KEY=value. Once a server is added, run claude mcp list to see what's connected and claude mcp remove <name> to drop one. Inside a session you can type /mcp to inspect connected servers and their tools. Command surfaces do shift between releases, so check Anthropic's official MCP documentation for the current flags rather than trusting a copied snippet.

Useful servers to start with

You don't need a wall of integrations. A couple of well-chosen servers cover most of what makes the agent feel connected rather than sandboxed. Good first picks:

• GitHub — read issues and pull requests, open PRs, review diffs. The single highest-leverage server for most repos.
• Linear (or your tracker) — let the agent read the ticket it's working on and update status, so context lives where your team already keeps it.
• Postgres — run read-only queries against a database so the agent can check a schema or sanity-check data without you copy-pasting rows.
• Sentry — pull production errors and stack traces so a “fix this bug” task starts from the real exception, not a vague description.
• Playwright — drive a real browser to test a flow or scrape a page the agent can't otherwise reach.

Start with one. Adding ten servers at once buries the agent in tool definitions and makes it harder to reason about what it might do. Connect GitHub, use it for a week, and add the next one when a task actually calls for it.

A trust warning

Here's the part the quick-start guides skip: an MCP server is third-party code running with the access you hand it. A Postgres server has your database credentials. A GitHub server can push code. A compromised or simply careless server can read data it shouldn't and trigger actions you didn't intend — and because the agent calls these tools on its own, a bad one can do damage without an obvious prompt. This is the same exposure as installing any dependency, except the consumer is an autonomous agent.

Two habits keep it sane. First, vet the source. Prefer official servers from the vendor whose service they wrap, read what a community server does before connecting it, and scope every token as narrowly as the task allows — read-only where read-only will do. Second, don't rely on the agent's judgment alone. Pair MCP with a pre-approval policy so genuinely risky tool calls pause for a human instead of executing silently; our guide to Claude Code pre-approval policies covers exactly how to draw that line, and Claude Code hooks are the mechanism that enforces it.

Where notifications come in

The moment you give the agent real tools, the “just walk away” dream gets complicated. An MCP tool that can open a PR or write to a database is exactly the kind of action you'll want gated behind an approval — and an approval is only useful if you actually notice it. Otherwise the agent stalls, waiting on a permission prompt you never saw, and the autonomy you set up evaporates into a terminal you have to keep checking.

That's the gap ambient notifications fill: when an MCP tool call needs your sign-off, the right thing is a glanceable nudge that pulls you in, not a buried prompt that pauses the run indefinitely. The more capable your server roster, the more this matters — powerful tools and good attention routing are two halves of the same setup.

Frequently asked questions

Where Backgrind fits

Backgrind is the layer that makes MCP-powered autonomy actually hands-off. It wraps your real Claude Code CLI in an always-on-top overlay and turns approval prompts — including the ones from MCP tool calls — into ambient toasts: when a server's tool needs your sign-off, the window flashes and the right tab gets an accent ring, so you answer with a keystroke instead of hunting for a stalled terminal. If you're still getting set up, install Claude Code first, then connect a server; for picking an engine, see our take on the best AI coding agent in 2026, and for the workflow files that pair with MCP, CLAUDE.md vs AGENTS.md. Then watch it run in the live demo.