Coding agents
Let coding agents run your dev servers through localhost
localhost mcp is the Model Context Protocol (MCP) server of localhost app (getlocalhost.app), the free, MIT-licensed desktop process manager for local dev servers on macOS, Windows and Linux. It lets AI coding agents such as Claude Code, Cursor and Codex list, start, stop and inspect the dev servers, databases and workers of your local Projects through localhost instead of a shell, while you see and control the same Services in the localhost app.
You configure each Project once in the app. From then on, you and your agent start, stop and read the same Services, with the same Ports, environment and logs, and nothing the agent starts runs where you can’t see it.
Why shouldn’t coding agents run dev servers in their own shell?
Ports that collide
An agent runs pnpm dev while yours is already up, and the second copy fails on a taken port, or picks another port nobody told you about.
Processes left behind
A dev server started in the agent’s shell can outlive the chat, holding its port and memory until you go looking for its pid.
Logs nobody can see
Its output goes to a shell you can’t read, and the agent only sees what it captured, so a crash looks like silence.
How does localhost app fix it?
- One core for the app and the agent. The app and
localhost mcpdrive one localhost core in the background. A Service the agent starts is Running in the app, with its logs, and one you start in the app is running for the agent. A stop from either stops the same Run, andstatussays who started each one ("startedBy": "app"or"agent"). - Your commands, run the same way. Each Service runs in your login shell with its Project’s variables, Environment Profile and Secrets, after its Dependencies, exactly as when you press Start in the app.
- Never twice. A Service that is already running isn’t started again, and one a
localhost upruns in a terminal shows as running in another session, so the agent neither starts a second copy nor stops it. - Nothing left behind. Stopping ends the whole process tree. When the agent disconnects, the Services it started stop, unless the app is open: then they keep running there, until you stop them.
- Structured answers. Results are JSON, failures carry a
kindsuch asportConflictorcommandNotFoundwith a message saying what to do next, and logs are bounded (200 lines by default, at most 2,000). - Your configuration stays yours. The agent can’t add or change Projects or Services, and it reads only the Secrets of the Services it starts.
Which MCP tools does localhost expose?
Nine tools. Projects and Services are named by their Key, as list_projects shows them.
| Tool | What it does |
|---|---|
list_projects | Every Project: Key, name, folder and Service Keys. |
list_services | A Project’s Services as configured: command line, working directory, Port, URL, Dependencies. |
status | Each Service’s state, pid, Port, URL and uptime; for a Failed one, why, with its last output. |
start_service | Starts one Service after its Dependencies and waits (up to 45 s) until it is Running, Exited or Failed. Optionally on another port, for that Run only. |
stop_service | Stops one Service and waits until its whole process tree has ended. Dependents keep running. |
start_project | Start All: every Service in dependency order, waiting for each the same way. |
stop_project | Stops every running Service of the Project, dependents first. |
logs | The latest Run’s output of one Service or the whole Project: the last 200 lines by default (at most 2,000), optionally only recent lines or lines containing some text. |
ports | Who listens on which port: one of your Services, a process in a Project’s folder, or something unmanaged. |
Example workflows
Test a change in the running app
list_projectsfinds the Project whose folder holds the codestart_service{ project: "my-saas", service: "web" } starts its Dependencies firststatusonlyrunningcounts as up; it gives the URLlogs{ service: "web", lines: 50 } after the request
A port is taken
start_servicefails with kindportConflict, naming the port, when the Run can’t move to a free oneportsshows who holds it: one of your Services, a process in a Project’s folder, or something unmanagedstart_service{ port: 3001 } for this Run only, or the agent tells you and asks
Something failed
statusthe Failed Service’s reason, such ascommandNotFound, and its last outputlogs{ contains: "error", since_seconds: 120 } to read only what matters
How do I connect Claude Code, Cursor or Codex?
1. Install the localhost command
localhost mcp is part of the localhost command, which isn’t in the release downloads yet. Build it from source with Rust, and add your Projects in the app first: the command reads the same Projects.
git clone https://github.com/marcellosso/localhost
cargo install --path localhost/core/localhost-cli2. Connect your agent
Claude Code
claude mcp add localhost -- localhost mcpCursor: in .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project.
{
"mcpServers": {
"localhost": { "command": "localhost", "args": ["mcp"] }
}
}Codex: codex mcp add localhost -- localhost mcp, or in ~/.codex/config.toml:
[mcp_servers.localhost]
command = "localhost"
args = ["mcp"]Other MCP clients, such as Claude Desktop, take the same command and args in their own configuration file. If one can’t find localhost, give it the full path, e.g. ~/.cargo/bin/localhost.
3. Give it the skill
The server tells the agent how to use it when it connects. The localhost-mcp skill makes it the default: Services through localhost, never a shell; status before saying anything runs; logs andports when something fails. Copy it to ~/.claude/skills/localhost-mcp/ for Claude Code or~/.agents/skills/localhost-mcp/ for Codex.
Does it work on macOS, Linux and Windows?
The background core listens on a socket in localhost’s data folder on macOS and Linux, and on a named pipe on Windows; only your user can open either. On Windows, agents run Projects on Windows itself. A Project in a WSL distro runs only from the app, and an agent asked to start one is told so. On macOS, the Keychain asks the first time localhost mcp reads each Secret, since it is a different program than the app.
FAQ
What is localhost mcp?
localhost mcp is the MCP server of localhost app, run over stdio (standard input and output) by your coding agent. It gives the agent nine tools (list_projects, list_services, status, start_service, stop_service, start_project, stop_project, logs and ports) over the Projects and Services you configured in the localhost app.
Which coding agents does it work with?
Any MCP client that starts a server over standard input and output: Claude Code (claude mcp add localhost -- localhost mcp), Cursor (.cursor/mcp.json), Codex (codex mcp add localhost -- localhost mcp), Claude Desktop and others.
Do the app and the agent see the same Services?
Yes. The app and localhost mcp drive one localhost core in the background. A Service the agent starts is Running in the app, with its logs, and one you start in the app is running for the agent. A stop from either stops the same Run, and status says who started each one.
What happens to the Services an agent started when it disconnects?
They stop, with their whole process tree, unless the localhost app is open: then they keep running there, and you stop them when you like. Nothing keeps running unseen.
Can an agent change my configuration or read my Secrets?
It can’t add or change Projects or Services. Secrets reach only the Services it starts, and their Dependencies; listing, status, logs and ports read none. On macOS, the Keychain asks before localhost mcp reads each Secret the first time.
Is the localhost command in the release downloads?
Not yet. Build it from source with Rust: cargo install --path localhost/core/localhost-cli after cloning the repository. Add your Projects in the app first; the command reads the same Projects.
Every detail is in the docs: Coding agents (MCP), Agent skill andInstall. The source is on GitHub, MIT licensed.