MCP server
Let Claude Code or Codex see which URL belongs to which project, and register new ones.
One-click install
The last onboarding step — also available any time from Settings — installs the stdio MCP server into Claude Code or Codex in one click. It edits only that client's config file, preserves every other key, and refuses rather than overwrites if the file is not valid JSON.
| Client | Config file | Format |
|---|---|---|
| Claude Code | ~/.claude.json | a mcpServers.localhost-aliases entry |
| Codex | ~/.codex/config.toml | an [mcp_servers.localhost-aliases] table |
If you would rather paste it yourself, the same screen shows the exact snippet. In an installed app the server is a compiled binary inside the bundle and runs directly; in a git checkout it is a TypeScript entry point run by Bun, so the command differs between the two and the UI shows the one that applies to you.
~/.codex/config.toml (installed app)
[mcp_servers.localhost-aliases] command = "/Applications/LocalhostAliases.app/Contents/Resources/mcp" args = []
What the agent can do
| Tool | What it does | Prompts? |
|---|---|---|
list_aliases | every alias with its hostname, target port, loopback IP and live status | No |
list_projects | the folders that have at least one alias linked | No |
create_alias | creates http://<name>.<tld> pointing at 127.0.0.1:<port> | Yes |
delete_alias | removes an alias by hostname, name or id | Yes |
link_project | attaches a folder, imports its declared aliases | Only if it creates one |
get_usage_instructions | the full mechanism, so the agent explains it correctly | No |
The agent cannot approve the prompt for you
create_alias and delete_alias raise the macOS admin prompt that you must accept in person. The server's own instructions tell the model not to call them speculatively.It needs the app running
The MCP server is a thin client of the dashboard's HTTP API on 127.0.0.1:7788, and the dashboard is embedded in the menu-bar app. If a tool reports the dashboard is unreachable, the fix is to open Localhost Aliases — not to retry.
The server is also told, in its own instructions, that project aliases are http:// only, so your agent should never suggest https://myapp.test.