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 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.

Rendering diagram…

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. The double dash separates Claude Code's own options from the command that launches your server.

# 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.

# 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.Common gotchaA 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.Common gotchaThe 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.

# 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. 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.

{
  "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.

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

A decision you can follow

Rendering diagram…

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.

Try this prompt

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.

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 <name>. 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.

In short