Claude Code MCP Servers Guide — Setup, Examples, Troubleshooting

9 min read · Claude Code integration guide

Claude Code is useful on its own, but the moment you want it to read a Postgres schema, open a GitHub issue, or list files outside your repo, you hit a wall. That wall is the point where MCP servers start mattering. MCP — the Model Context Protocol — is the standard interface Claude Code uses to talk to external tools and data sources, and knowing how to wire one up cleanly is the difference between a terminal agent that can only see your repo and one that can act across your whole stack.

This guide covers what MCP actually is, when you need a server and when you don't, how Claude Code discovers servers across three config scopes, a copy-pasteable .mcp.json example, how to verify a server is connected, the failure modes worth knowing in advance, and the security model you should assume by default. If you want the adjacent primitives, see the Claude Code hooks guide and the slash commands reference.

What is the Model Context Protocol?

MCP is an open specification for how an AI client (Claude Code, Claude Desktop, Zed, and others) talks to external tools and data sources. An MCP server is a small program — typically a Node or Python process — that exposes three kinds of things over a standard JSON-RPC protocol: tools (functions Claude can call, like query_database or open_issue), resources (read-only data Claude can fetch, like file contents or API responses), and prompts (reusable prompt templates the server ships). Claude Code spawns the server as a child process (stdio transport) or connects to it over HTTP, then routes tool calls across the protocol during a session.

The spec and current SDK list live at modelcontextprotocol.io. The headline point: you don't have to write one to use one. A growing catalog of community and official servers already covers most of what a coding agent wants to reach.

When you actually need MCP servers

Most Claude Code sessions don't need any MCP server. If the task lives inside your repo, the built-in file tools are enough. You start reaching for MCP when the work crosses a boundary:

• Databases. Reading schemas, running read-only queries, or inspecting row counts in Postgres or SQLite without copy-pasting into the terminal.
• GitHub. Opening issues, reading PR comments, listing workflow runs, or searching across repos you don't have checked out.
• Filesystems outside the project. Reading a sibling repo, a design-doc folder, or a shared notes directory that isn't under your current cwd.
• Team tools. Slack, Linear, Notion, Google Drive — pulling context that lives in chat or a doc, not a file.
• Browsers. Puppeteer or Playwright servers that let Claude Code open a page, click, screenshot, and read the DOM.
• Custom internal APIs. A thin MCP wrapper around your company's own service so Claude can hit it without you pasting curl output.

The anti-pattern is adding a server because it sounds useful. Each server adds startup time, a config surface, and a security boundary. Add them when a specific recurring task justifies the cost.

How Claude Code loads MCP servers

Current Anthropic docs describe three MCP config scopes: local, project, and user. The terminology matters because the storage files are not always what the scope name would suggest.

• User scope — machine-wide server entries, stored in ~/.claude.json (not ~/.claude/settings.json — that's a separate settings file). Configure these with claude mcp add --scope user <name> ... or by editing the JSON directly. Servers here load in every Claude Code session on this machine. Good for personal tokens and per-machine conveniences.
• Project scope — .mcp.json at the repo root. This is the only scope whose file lives inside the repo, so it's what teammates see on clone. Important: Claude Code does not auto-enable project-scoped servers. The first time a session sees a new or changed .mcp.json entry, it prompts you for approval before loading that server. This is a deliberate supply-chain guardrail — pulling a branch with a malicious MCP entry can't silently run code.
• Local scope — per-project entries that are not committed. Also stored in ~/.claude.json (keyed by project path), managed via claude mcp add --scope local .... Good for your own overrides: dev-only servers, secrets, or something you don't want landing in .mcp.json.

When the same server name appears in more than one scope, local wins, then project, then user.

.claude/settings.local.json is a general Claude Code settings file — it is not an MCP server scope. Don't put server definitions there; they won't load. For the authoritative layout and any per-release changes, read docs.anthropic.com/claude-code/mcp — this guide covers the mechanism and the stable shape of the config.

Popular MCP servers compared

A representative slice of what's actually useful day-to-day. This is not exhaustive — check the MCP site and the community catalog for the current list.

A minimal working .mcp.json

Drop this at the root of your repo. Claude Code reads it on session start. This example wires up the filesystem server (scoped to a shared notes folder) and the GitHub server (using an env var — never inline a token).

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/notes",
        "/Users/you/shared-docs"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Field-by-field:

• mcpServers — top-level map keyed by the name Claude Code will show for each server. Keep names short and unique; collisions across scopes resolve by the precedence rules above.
• command — the executable to launch. Prefer an absolute path for stability; npx works but depends on PATH and can hang on first run while it downloads.
• args — arguments passed to the command. For the filesystem server, trailing args are the directories to expose — every path listed is readable and writable by the server.
• env — env vars injected into the child process. Reference shell env vars with ${VAR} syntax. Never paste raw tokens into the committed .mcp.json; put the token in your shell profile or a local override file.

How to verify a server is actually connected

Two reliable signals, both release-stable:

• Session start output. Claude Code surfaces loaded MCP servers when a session begins. If a server you configured isn't in that list, it either failed to start or was masked by a narrower scope.
• Ask the model. At any prompt, ask "what MCP tools do you have available?" The response enumerates the tool names and the server they came from. If your expected tools aren't there, the server isn't connected — move to the failure-mode checklist below.

The exact chrome for this (labels, pane names, keybindings) shifts between Claude Code releases. For per-release detail, treat docs.anthropic.com/claude-code as the source of truth and this guide as the mechanism-level reference.

Common failure modes and fixes

• Server fails to start. Usually a bad command path or missing executable. Run the exact command from your .mcp.json in a plain shell and see if it launches. If npx, check that your node is new enough and that the first-run download finished. Permissions on the binary matter too — a non-executable script will silently fail.
• Tools don't show up even though the server started. The server is connected but its tools require env vars that weren't injected. Confirm every var in the env block is set in the shell that launched Claude Code, and confirm you configured the server in the right scope — a user-scope server won't see a project-scope env override.
• Server hangs or stops responding. The child process is stuck or its stdin/stdout pipe is full. Kill the Claude Code session, kill any orphaned child processes from that server (check ps for the binary name), then start a fresh session. If it hangs again on the same task, that specific call is the culprit — narrow it down and file an issue against the server.
• Server leaks secrets into logs. Some servers echo request bodies or env at DEBUG verbosity. Never enable debug logging for a server that handles credentials unless you're in a sandbox. Use the server's own redaction flags, and keep tokens in scoped-narrow config files (see the token-hygiene callout above) so a leak has a small blast radius.

Security considerations you should default to

MCP servers fall into two broadly different threat models. Reason about each one separately before connecting a server — the "safe" defaults for one class aren't defaults at all for the other.

Local stdio servers

These are programs spawned on your machine as child processes of Claude Code. They run with your user's permissions and can read or write anything your shell can.

• A postgres server with write credentials can run DROP TABLE. Nothing in the protocol stops it.
• A filesystem server rooted at / can read SSH keys, shell history, browser cookies — anything on disk your user can see.
• A github server with a classic PAT can act as you across every repo that token touches.

Defaults that keep blast radius small:

• Scope filesystem servers to specific directories, never to the home directory or /. The filesystem server takes its exposed paths as arguments — list exactly what's needed.
• Use read-only credentials where possible. A Postgres role with SELECT-only privileges is still useful for schema review and analytics and cannot delete anything.
• Separate credentials per server. Rotating or revoking one token shouldn't blast the others.
• Never commit secrets to .mcp.json. Reference env vars only; keep tokens in user-scope config or your shell profile.

Remote HTTP / SSE servers (including OAuth)

Remote MCP servers reach a cloud endpoint rather than a local binary. The threat model is different — and often more consequential than local risk, because data flows off-box and actions run under delegated credentials.

• Data egress. Anything you ask a remote server about — file contents, query results, meeting notes — leaves your machine. Treat a remote MCP server like any SaaS integration: know who operates the endpoint and what they log.
• OAuth scope minimization. Claude Code supports OAuth-authenticated remote servers. Grant the narrowest scope that makes the tool useful; revoke unused tokens from the provider's dashboard.
• Prompt injection from fetched content. A server that pulls untrusted web pages, issue bodies, or third-party docs can return content that instructs the model to take actions you didn't intend. Anthropic explicitly flags this risk for third-party servers. Don't enable web-fetching MCP servers in the same session as privileged local tools (filesystem write, shell-exec, DB-write) without reading what comes back.
• Vendor review, not just install review. A remote endpoint can change behavior server-side without a new install. A server you vetted last month can ship a new tool next week.

Across both classes: if you didn't write the server, read its tool list in the source or README before enabling. "Looks useful" is not a review.

Frequently asked questions

Two kits that cover the Claude Code + Cursor workflow

MCP servers are one piece of a Claude Code workflow. The Claude Code Starter Kit covers the rest — CLAUDE.md templates, slash commands, hooks patterns — so a new repo is productive on day one. The Cursor Rules kit covers the adjacent surface if some of your team drives from the IDE instead of the terminal.