What is a local MCP server?
A local MCP server is a Model Context Protocol server that your AI client launches as a program on your own computer, usually over the stdio transport: the client writes JSON-RPC messages to the process's standard input and reads replies from its standard output. Because it runs where you do, it can reach your files, shell and local tools.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Your client reads a config entry with a command and its arguments, such as a Node or Python script, and starts that program as a child process.
The client writes one JSON-RPC message per line to the process's stdin. The server answers one message per line on stdout.
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}Anything the server wants to log goes to stderr. If it prints anything else to stdout, the client reads it as a broken message.
The most common local server bug is a stray print statement.
The server works with your permissions: it reads the folder you pointed it at, runs the command, or opens the browser you are signed in to.
When you quit the client, it closes stdin and waits for the process to exit, then kills it if it hangs. Each client gets its own copy of the server.
Local versus remote MCP servers
"Local" says where the server runs, not what it does. The MCP docs describe it the same way: a server the client launches over stdio runs on the same machine, and that is what people call a local server; one you reach at a URL over Streamable HTTP is a remote server. The protocol above the transport is identical. Tools, resources and prompts look exactly the same to the model, so a server can offer both ways in and behave the same.
What differs in practice is reach and lifetime. A local server has your user account's permissions and sits on your network, so it can read a repository, query a database that only your VPN can see, or drive a browser you are already signed in to. It also lives and dies with the client. Over stdio each client launches its own process, which means two agents open on one laptop are running two copies, each with its own memory.
When to use a local server
Reach for one when the work needs your machine: files, a shell, a local database, a signed-in browser, a device on your desk. It is also the right shape when the tool is yours alone and setting it up per person is acceptable. Prefer a remote server when many people need the same data, when credentials should be issued and revoked in one place, or when the client cannot start a subprocess at all, which is the case for hosts that run in a browser.
Credentials are the quiet trade-off. A local server reads its secrets from environment variables in the client's config or from files on disk. That works offline and needs no sign-in flow, but the key is now on every laptop that runs the server, and anyone who can read that config can act as you.
Common mistakes
- Printing to stdout. The spec is strict: the server must write nothing to stdout except MCP messages. A debug line or a startup banner corrupts the stream and the client drops the connection. Log to stderr instead; the client may show it or ignore it.
- Treating it as a shared service. Over stdio there is one process per client. State kept in memory is not visible to the next agent that starts its own copy.
- Installing without reading. A local server runs as you. Before you add one from a registry, look at what commands it runs and what it can reach. This is the same care you take with any package.
- Expecting it to outlive the client. When the client exits it closes the server's stdin, and a well-behaved server quits at once. Long-running state belongs somewhere else.
FAQ
- Does a local MCP server have to use stdio?
- No, but almost all do. A server can also listen on localhost over Streamable HTTP and hand the client a URL. The spec then asks it to bind only to 127.0.0.1 and to validate the Origin header, so a web page you visit cannot reach it.
- Can two agents share one local MCP server?
- Not over stdio. Each client launches its own process, so two agents on the same laptop run two copies with separate state. If you need one shared instance, run the server over HTTP instead.
- Where does a local MCP server get its API keys?
- From environment variables in the client's config entry, or from files it reads on your machine. That is simple and works offline, but the key lives on every laptop that runs the server, and rotating it means editing each one.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.