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

> The complete claude mcp add reference — stdio vs HTTP transports, local/project/user scopes, .mcp.json with env expansion, OAuth via /mcp, and the gotchas.

Connect an MCP server to Claude Code with one command: claude mcp add <name> -- <command> for local stdio servers, or claude mcp add --transport http <name> <url> for hosted ones. Pick a scope (--scope local, project, or user), authenticate remotes with OAuth via /mcp, and commit .mcp.json so your whole team gets the same servers.

MCP servers are how [Claude Code](/tools/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`:

```bash
# 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:

```bash
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

| Scope | Stored in | Who sees it |
| --- | --- | --- |
| `local` (default) | `~/.claude.json` (this project's entry) | You, this project only |
| `project` | `.mcp.json` at the repo root — **committed** | Everyone who clones the repo |
| `user` | `~/.claude.json` (global) | You, every project |

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`:

```json
{
  "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](/guides/configuration/claude-code-settings-permissions) 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](/commands/workflow/add-mcp-server) command walks this checklist, and [MCP Inspector](/tools/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).

> [!TIP]
> Not sure which servers are worth connecting? Start with the [best MCP servers in 2026](/guides/mcp/best-mcp-servers-2026) — the short list that covers docs, GitHub, browsers, and databases for most developers.

Building your own server instead of consuming one? Start with [Building an MCP Server](/guides/advanced/building-an-mcp-server), then [deploy it remotely](/guides/mcp/deploy-remote-mcp-server) when the team needs it — and once you're running more than a handful, [governance](/guides/mcp/govern-mcp-servers) becomes the next problem.

---

_Source: https://agentscamp.com/guides/mcp/claude-code-mcp-setup — Guide on AgentsCamp._