Running a Local MCP Server

A local server is the common case in practice. It is simpler than a remote one and requires nothing to be deployed, but it has its own quirks around launching and debugging.

Why local

Access to things only you have. Files on disk, a local database, a service running on your machine. A remote server cannot reach them.

No network surface. Nothing to authenticate, nothing exposed. For tools with file access that is decisive.

Simpler operation. No service to stand up, keep available and upgrade separately.

An important caveat about privacy: a local server does not make the work private. It restricts access to data, but everything it returns to the agent enters context and therefore reaches the model provider. If content must not leave the perimeter, that is solved by a local model, not by the server.

How it launches

The client starts the server as a child process and talks to it over standard streams. Three consequences follow, and they explain most problems:

The process environment is not your shell. Variables you set in the terminal are invisible to it, and PATH may differ. That is why the config often needs a full path to the executable.

Standard output belongs to the protocol. Any print to stdout breaks the exchange with the client. Server logs go to stderr or to a file, and this is the single most common mistake when writing your own server.

Its lifetime is tied to the client. It starts and dies with the client. State does not persist between sessions unless you persist it yourself.

File permissions

The server runs with your permissions. That means a filesystem server can reach anything you can, including keys in your home directory.

Worth doing:

• Restrict the root directory. Most filesystem servers accept a list of allowed paths. Point them at the working project, not your home directory.
• Separate reads and writes. If the task is analysis, write access is unnecessary.
• Keep secrets out of the working directory. A key file at the project root gets read on the agent’s first file search, and the contents enter context.
• Do not run as administrator. No benefit, and a wider blast radius on mistakes.

On third-party servers specifically: a local server is somebody else’s code running with your permissions. Before connecting one, look at what package it is and who publishes it - see security.

Debugging

An order that covers almost everything:

1. Run the server by hand in a terminal. It should start and wait for input rather than exit. Initialisation errors are immediately visible, while the client often hides them.
2. Check for noise on stdout. Banner messages and debug prints break the protocol.
3. Check environment variables. An empty variable looks like a missing one.
4. Read the client logs. They usually carry the reason the process did not come up.
5. Check dependencies. A server launched through a package manager downloads something on first run; without network access that looks like “it just does not work”.
6. Ask the agent for the tool list. A live server with an empty list is an authentication failure, not a launch failure.

A good habit when writing your own server: log to a file from day one. Without it, diagnosis becomes guesswork, because console output is unavailable.

How to write your own: an MCP server in Python. Configuration and variables: server setup. The overview is in the MCP guide.