Local MCP boundary
Check where your coding agent actually runs.
Hronaut's MCP server listens on the loopback address of the computer it runs on. Before you edit any client configuration, confirm the client process sees that same loopback.
The rule
127.0.0.1 belongs to the client process's network namespace.
“Running on my computer” is not enough. WSL, Docker or Podman, a Dev Container, a VM, Remote SSH, and a hosted agent may each have their own loopback interface.
Support matrix
Identify the client runtime before changing anything.
Only the native same-host path is release-tested. By default Hronaut listens only on loopback. For every separate runtime below, the safe fix is the same: run the coding-agent client natively on the computer running Hronaut.
| Client runtime | What 127.0.0.1 means | Support | Safe next action |
|---|---|---|---|
| Native Windows, macOS, or Linux process | The same host loopback used by Hronaut. | Supported and release-tested | Use the current endpoint and generated setup from Hronaut Home, then run the preflight below. |
| WSL | The Linux environment's loopback; forwarding behavior varies by WSL and Windows networking mode. | Unsupported / experimental | Run the coding-agent client natively on Windows. Do not assume a machine-specific forwarding rule is a Hronaut guarantee. |
| Docker, Podman, or Dev Container | The container's own loopback, not the desktop host. | Unsupported / experimental | Run the coding-agent client natively on the Hronaut host. |
| Local virtual machine | The guest operating system's loopback. | Unsupported | Run the client in the host OS alongside Hronaut. |
| Remote SSH | The remote machine's loopback. | Unsupported | Use a local client process on the Hronaut host instead of changing the listener. |
| Hosted or cloud agent | The provider's remote runtime, never your desktop loopback. | Unsupported by design | Use the agent's native local mode, if it has one, on the Hronaut host. |
Release-tested path
Verify health → MCP discovery → one harmless browser read.
Run every check from the environment that actually launches the coding agent. Copy the current endpoint and client setup from Hronaut Home. For the first check only, replace /mcp with /healthz.
- 1
Check listener reachability
With Hronaut open, run this copy-safe, status-only probe in the client's shell.
macOS or Linux
curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" http://127.0.0.1:47812/healthzWindows PowerShell
curl.exe --silent --show-error --output NUL --write-out "%{http_code}`n" http://127.0.0.1:47812/healthz200: the endpoint is reachable and this profile accepts the request.401: the endpoint is reachable, but authentication is required.- Refused or timed out: no listener is reachable from this runtime.
- 2
Initialize MCP and list tools
Install the exact client configuration copied from Hronaut Home, restart or refresh the client, and run its MCP status or tool-list command. Confirm Hronaut initializes and lists tools including
browser_statusandbrowser_snapshot. For an independent check from the same runtime, use the MCP Inspector guide. - 3
Read synthetic public content
Ask the connected client: “Create a Hronaut workspace named topology-check, open https://example.com inside it, take a semantic snapshot, and report the page heading. Start with clean scratch storage.” A visible isolated workspace and the heading Example Domain prove the browser works, without touching a private page.
A new profile requires its MCP token, so use the token-file or environment-placeholder setup that Hronaut Home generates. Never paste the bearer token or token-file contents into a command transcript, issue, chat, screenshot, or public diagnostic.
Copy-safe diagnosis
Report the failed boundary, not private data.
These reason names are safe to share. They name the stage that failed, without tokens, private paths, account identifiers, cookies, private URLs, page content, or customer information.
| Reason | Meaning | Next check |
|---|---|---|
app_not_running | Hronaut Home is not open or its local listener has not started. | Start Hronaut and confirm Home says the MCP server is online. |
endpoint_unreachable_from_client_namespace | Home says the listener is online, but the status-only health probe cannot reach it from the client runtime. | Recheck the topology table and move the client to the Hronaut host OS. |
authentication_required | The health probe returns 401, or MCP rejects a configuration without the current credential. | Copy the generated protected-profile setup from Hronaut Home. Do not reveal the token. |
mcp_handshake_failed | Health succeeds, but MCP initialization or tool discovery does not. | Check client transport, endpoint, authentication placeholder, and client logs; then use MCP Inspector from the same runtime. |
browser_not_ready | MCP tools are visible, but the isolated public-page read cannot complete. | Open Hronaut Home, review the copy-safe MCP readiness panel, and retry browser_status or browser_snapshot in the task-owned workspace. |
Security boundary
Do not solve reachability by exposing browser control.
Hronaut listens on loopback by default, on purpose. Do not change it to a LAN or public bind, add an unauthenticated proxy, or publish the endpoint through a tunnel to fix reachability. Those workarounds expand browser-control authority beyond the tested local boundary.
Platform-specific forwarding paths stay unsupported until Hronaut deliberately tests and documents them. The supported recovery is a native client process on the same host.
What about the LAN setting in Hronaut?
Settings → MCP security has an explicit, off-by-default opt-in, Allow connections from other computers, for deliberate access from another machine on a trusted network. It takes effect after a restart, listens on all IPv4 interfaces, and uses unencrypted HTTP. Authentication is a separate setting. Treat it as a deliberate decision to widen access, not as a workaround for an unreachable loopback endpoint.
Next step
Now configure the client, without moving the boundary.
Once the native same-host preflight passes, open the focused guide for your client and keep Hronaut Home open while you verify the connection. For connection details, see the technical reference ↗.