# Local vs remote MCP servers

Run an MCP server locally when it needs direct access to your machine: your
files, your shell, a database on localhost. Connect to a remote server when the
tool lives in the cloud, the vendor hosts it for you, or your team shares one
endpoint. The split comes down to where the work runs and who manages the
process.

If the protocol itself is new to you, read [MCP fundamentals](/guides/mcp-fundamentals)
first. This guide assumes you know what a host, client, and server are, and
focuses on the one decision you face every time you add a server: local or
remote.

## The one-line answer

A local server
runs on your machine as a subprocess that Claude Code launches and talks to over
standard input and output. A remote server
runs somewhere else and Claude Code reaches it over HTTP. Local gives you
machine access and zero network latency. Remote gives you a managed process,
shared state, and access to cloud APIs without you running anything.

## The two transports

The local-versus-remote choice maps directly onto the two transports the
protocol defines.

| Trait | Local (stdio) | Remote (HTTP) |
| --- | --- | --- |
| Where it runs | Your machine, as a subprocess | A server you reach by URL |
| Who starts it | Claude Code launches it | Already running; you connect |
| Connection | stdio | Streamable HTTP |
| Auth | Local credentials, env vars | Tokens, headers, OAuth 2.0 |
| Network | None | Required |
| Reconnect on drop | Not automatic | Automatic, with backoff |
| Shared with a team | One copy per machine | One endpoint, everyone |

stdio
is the local transport. Claude Code spawns the server as a child process and
exchanges newline-delimited JSON-RPC messages over its input and output streams.
Nothing leaves your computer.

Streamable HTTP is the remote transport. The server is an independent process
that handles many clients over HTTP POST and GET, and it can stream responses
back using Server-Sent Events. You point Claude Code at one URL.

You may still see an older SSE
transport mentioned. It is deprecated. Use HTTP for new remote servers.

## When should you run an MCP server locally?

Reach for a local server when the tool has to touch your machine or your private
network.

- The server reads or writes files in your project.
- It runs shell commands or build steps.
- It connects to a database on `localhost` or inside your VPN.
- You are developing the server itself and want to iterate without deploying.
- The data is sensitive and you do not want it crossing a network.

A local database server is the common case. It opens a connection to a Postgres
instance running on your own machine and exposes a tool to query it. There is no
URL, no token, and no network hop.

Add one with `claude mcp add`, the same command covered step by step in
[install your first MCP server](/guides/install-your-first-mcp-server). The double
dash separates Claude Code's own options from the command that launches your
server.

```bash
# A local stdio server (the default transport)
claude mcp add db-tools -- npx -y @example/db-mcp-server

# Pass a secret to the server's environment, not your shell
claude mcp add --env DATABASE_URL=postgres://localhost/app \
  db-tools -- npx -y @example/db-mcp-server
```

Everything after `--` runs untouched. The `--env` flag injects a variable into
the server's process environment, so the secret reaches the server without
living in your shell history. You can pass `--env` more than once. Place at
least one other option between `--env` and the server name, or the CLI reads the
name as another key-value pair and rejects it.

### What does a local server cost you?

You manage the process and its dependencies. If the server needs a specific
runtime version or a package installed, that is on every machine that uses it.
A local server also stops when your session ends, and Claude Code does not
restart a crashed stdio process automatically. State lives only on your machine,
so a teammate who clones the repo gets the config but not your local data.

## When should you use a remote MCP server?

Reach for a remote server when the tool already lives in the cloud or when you
want someone else to run the process.

- A vendor publishes a hosted MCP endpoint for their product.
- Your team wants one shared server instead of one install per person.
- The tool talks to a cloud API that needs OAuth, and you would rather not store
  credentials on every laptop.
- You want the server to keep running and reconnect on its own when the network
  blips.

Many products now ship a hosted endpoint you connect to by URL.

```bash
# A remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A remote server that needs a static auth header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer ${API_TOKEN}"
```

For servers that use OAuth 2.0, you do not paste a token. Add the server, then
run `/mcp` inside Claude Code to start the browser sign-in flow. Claude Code
stores the resulting credentials and refreshes them for you.

### What does a remote server cost you?

You depend on the network and on whoever runs the server. A request crosses the
internet, so it carries more latency than a stdio call on the same machine. You
trust the host with whatever data the tool sees. And a remote server cannot
reach your local files or `localhost` services, because it runs somewhere else.A hosted server's `localhost` is its own box, not yours. Pointing a remote database tool at a `localhost` connection string makes it query the host machine, not your laptop, so it returns nothing or hits the wrong database. If the tool must read your files or a local DB, run it as a local stdio server instead.

The upside on reliability: if an HTTP server drops mid-session, Claude Code
reconnects with exponential backoff, up to five attempts starting at a
one-second delay and doubling each time. Stdio servers get no such treatment,
since they are local processes you control.

## What is MCP server scope?

Scope decides which projects load the server and whether the config is shared.
Independent of transport, every server you add lands in a scope.

| Scope | Loads in | Shared with team | Stored in |
| --- | --- | --- | --- |
| `local` | Current project only | No | `~/.claude.json` |
| `project` | Current project only | Yes, via version control | `.mcp.json` in project root |
| `user` | All your projects | No | `~/.claude.json` |

Note the name collision: `local` here is a scope, not the stdio transport. A
local-scoped server can use either transport. Pick scope with `--scope`. It
defaults to `local`.The word "local" means two unrelated things here, and conflating them silently breaks team sharing. A remote HTTP server added at the default `local` scope is perfectly remote in transport, but it lives in your `~/.claude.json` and never reaches a teammate, so people assume the endpoint is broken when it is unshared. When you want everyone to get a server, pass `--scope project` so it writes to the committed `.mcp.json`, regardless of whether the transport is stdio or HTTP.

```bash
# Shared with the team, checked into version control
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# Available across all your own projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
```

Project scope is how a team standardises on one remote endpoint: add it once,
commit the `.mcp.json`, and everyone gets the same tools, the workflow detailed in
[share MCP servers with your team](/guides/share-mcp-servers-with-your-team).
Because that file is shared, Claude Code prompts each person for approval before
using a project-scoped server the first time.

## The config file

Whatever the CLI writes, you can read and edit. A project-scoped `.mcp.json`
holds servers under an `mcpServers` map. Each entry names a transport and the
fields that transport needs.

```json
{
  "mcpServers": {
    "db-tools": {
      "command": "npx",
      "args": ["-y", "@example/db-mcp-server"],
      "env": {
        "DATABASE_URL": "postgres://localhost/app"
      }
    },
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
```

The local entry has a `command` and `args`; Claude Code runs that to launch the
subprocess. The remote entry has a `type` of `http` and a `url`. The `type`
field also accepts `streamable-http` as an alias for `http`, so a config copied
from a vendor's docs works without edits.

You can keep secrets out of the committed file with environment-variable
expansion. Claude Code expands `${VAR}` in `.mcp.json`, so a shared config can
reference a token each developer sets in their own environment.

```json
{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

## A decision you can follow

Walk it in order. If the tool has to read your code, run your shell, or hit a
service on `localhost`, it has to be local; a remote process cannot see your
machine. If the tool is a cloud product or a shared team service, go remote and
let the host manage the process. When neither pulls hard, choose by who you want
running and updating the server: you, or someone else.

## Can you mix local and remote servers?

Nothing forces one choice across a project. A typical setup runs a local server
for file and database work alongside two or three remote servers for cloud
products. Claude Code merges every server's tools into one set the model sees,
so the model does not know or care which transport carried a given tool.

When you ask Claude to combine them, the request fans out naturally.

```text
Using the local db-tools server, find the 10 most recent signups,
then with the notion server, draft a summary page listing them.
```

Claude calls the local server over stdio for the query and the remote server
over HTTP for the page. Two transports, one conversation.

## Confirm what you have

List the servers in the current project and their state with one command.

```bash
claude mcp list
```

A project-scoped server awaiting approval shows as pending until you open Claude
Code interactively and approve it. For full detail on one server, including its
transport and scope, run `claude mcp get `. Once a server connects, its
tools appear automatically, and you teach Claude about them the same way for
local and remote: by asking for the outcome you want.