Adding MCP Servers to Claude Code: Local, Remote, and Project-Scoped

MCP servers are how Claude Code reaches beyond your filesystem — into GitHub, your database, your issue tracker, a headless browser, your docs. The protocol is open, the ecosystem is in the thousands of servers, and wiring one up is a single command. The decisions that actually matter are the transport, the scope, and how much you trust the thing — this guide covers all three.

One command, two transports

Local (stdio) servers run on your machine as a child process Claude Code launches. This is most open-source servers — anything you'd run with npx, uvx, or docker run:

# the -- separator is critical: everything after it is the server's own command
claude mcp add postgres --env DATABASE_URI="postgresql://localhost:5432/mydb" \
  -- uvx postgres-mcp --access-mode=restricted

Remote (HTTP) servers are hosted by the vendor — nothing runs on your machine, and auth is usually OAuth:

claude mcp add --transport http linear https://mcp.linear.app/mcp
claude mcp add --transport http notion https://mcp.notion.com/mcp

If a remote server takes a token instead of OAuth, pass it as a header: claude mcp add --transport http --header "Authorization: Bearer <token>" name url. You'll also see --transport sse in older docs — SSE is deprecated; prefer HTTP wherever the vendor offers it.

Manage what you've added with claude mcp list (with connection status), claude mcp get <name>, and claude mcp remove <name>.

Scopes: who gets the server

The team play is project scope. A committed .mcp.json means "these are this repo's integrations" — new teammates get them on clone, and Claude Code asks each person to approve the file's servers before their tools activate (you'll see them as pending in /mcp until then).

Secrets stay out of the committed file via environment expansion — .mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url, and headers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

Each teammate exports GITHUB_PAT their own way; the repo never holds a token.

Authentication: the /mcp flow

Hosted servers that return a 401 want OAuth. The flow is built in: run /mcp inside a session, select the server, choose Authenticate, and finish in the browser. Claude Code stores the token securely and refreshes it automatically. /mcp is also your status panel — per-server connection state, tool counts, and reconnects live there.

What a connected server actually gives you

Three things, not one:

• Tools — the headline feature. They appear to the model as mcp__<server>__<tool> and participate in the permission system under exactly that name, so you can allow mcp__github__get_issue while denying mcp__github__* writes.
• Resources — reference server data inline with @server:resource mentions (e.g. @github:issue://123), fetched and attached to your prompt.
• Prompts — servers can ship reusable prompts that surface as slash commands: /mcp__github__list_prs.

Two operational limits worth knowing: server startup has a timeout (raise with MCP_TIMEOUT=60000 claude for slow Docker-based servers), and tool output is capped — about 25k tokens by default, configurable via MAX_MCP_OUTPUT_TOKENS — so a tool that dumps a whole database will get truncated, by design.

Trust is the real configuration

An MCP server is code that runs with the credentials you hand it, feeding text straight into your agent's context. That has two failure modes: a malicious or compromised server (supply chain), and a legitimate server returning attacker-controlled content (prompt injection — a web-fetching tool reading a hostile page). So:

• Vet provenance before adding — prefer official vendor servers and well-known projects; read the source of small community ones. The Add MCP Server command walks this checklist, and MCP Inspector lets you poke a server's tools directly before trusting it in a session.
• Scope credentials down — read-only tokens and modes where offered; many servers ship them precisely for this.
• Don't hoard servers — every connected server's tool definitions ride along in context. Keep the per-project set tight, and disable ones you're not using (the enableAllProjectMcpServers setting auto-approves a repo's full set — convenient, but understand what you're signing).

Building your own server instead of consuming one? Start with Building an MCP Server, then deploy it remotely when the team needs it — and once you're running more than a handful, governance becomes the next problem.