Troubleshoot a workstation connection

A workstation server that will not connect almost always has one cause, and the proxy already knows which. This page is how you get that answer out of it.

In a hurry? Run this on the workstation and read the block it prints:

terminal

docker logs mcpm-workstation-proxy --tail 200

Every failure prints an MCP MANAGER DIAGNOSTIC block naming a code such as MCPM_DERP_UNREACHABLE, what it means, what to do, and a link back to this page. Jump to Diagnostic codes to look yours up.

What is actually running

The command MCP Manager gives you starts two containers, and they are not interchangeable:

Container	What it is	Lifetime
the one you ran	The setup TUI — the dashboard you watched during setup.	Exits when you quit. Nothing is kept.
`mcpm-workstation-proxy`	The proxy. It owns the tunnel, runs the connection checks, and produces every diagnosis.	Runs in the background, restarts on reboot.

Troubleshoot the proxy, not the TUI. The TUI is a live view of the proxy’s state; if you closed it, nothing was lost.

Collect the evidence

Two commands. Run them on the workstation itself.

Proxy logs (start here)
Live state as JSON

terminal

docker logs mcpm-workstation-proxy --tail 200

The log opens with a banner naming the build, the port, and every hostname this proxy expects to reach. Each failure then prints a diagnostic block. Both are plain text and safe to share — no tokens, keys or credentials are written to the log.If the container is not there at all, it never started:

terminal

docker ps -a --filter name=mcpm-workstation-proxy

terminal

curl -s localhost:7117/startup-progress

Returns the current state of every connection step. Use the port from the banner if yours is not 7117. This endpoint is local-only and needs no authentication.

{
  "steps": [
    { "id": "tailscale_daemon", "label": "Tailscale daemon started", "status": "completed" },
    { "id": "tailscale_authenticated", "label": "Authenticated on tailnet", "status": "completed" },
    { "id": "ip_dns_assigned", "label": "IP & DNS assigned", "status": "completed" },
    {
      "id": "derp_relays_reachable",
      "label": "Relay servers reachable",
      "status": "error",
      "diagnosticCode": "MCPM_DERP_UNREACHABLE",
      "docsUrl": "https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/workstation-troubleshooting#mcpm-derp-unreachable",
      "unreachableHostnames": ["derp-a.mcpmanager.ai", "derp-b.mcpmanager.ai"],
      "errorMessage": "This machine cannot reach the MCP Manager relay servers. …"
    },
    { "id": "server_roundtrip", "label": "Connected to server", "status": "error" }
  ],
  "allCompleted": false
}

Read diagnosticCode and unreachableHostnames rather than parsing errorMessage — the codes and the hostname list are a stable contract, the prose is not.

Ask an AI assistant

MCP Manager’s documentation is published for AI agents — see Docs for AI agents. If your assistant can read these docs, give it the output and it can take you the rest of the way:

prompt

Here is the log from my MCP Manager workstation proxy. Look up the MCPM_ diagnostic
code in the MCP Manager docs and tell me exactly what to do, including the hostnames
I need to send to my network team.

<paste the output of: docker logs mcpm-workstation-proxy --tail 200>

The diagnostic block is self-contained on purpose: the code, the specifics, the consequence, the fix, and the docs link are all in the same block, so the assistant does not have to stitch together separate log lines.

The connection sequence

The proxy reports five steps, in order. Which one fails tells you where to look; the diagnosticCode on that step tells you what happened. More than one code can land on the same step, so match on the code, not on the step name alone.

Step	What it proves	Codes that can land here
Tailscale daemon started	The tunnel agent reached the coordination server.	`MCPM_COORDINATOR_UNREACHABLE`
Authenticated on tailnet	The pre-auth key was accepted.	The registration token is expired — re-run setup.
IP & DNS assigned	The tunnel has an address.	`MCPM_NO_TAILNET_IP`
Relay servers reachable	Traffic has somewhere to travel.	`MCPM_DERP_UNREACHABLE` · `MCPM_RELAY_CHECK_FAILED` · `MCPM_RELAY_CHECK_SKIPPED`
Connected to server	MCP Manager reached back to this machine, end to end.	`MCPM_ROUNDTRIP_TIMEOUT` · `MCPM_ROUNDTRIP_LOST`

Green through “IP & DNS assigned” is not success. That is the single most misread state: the tunnel authenticated, so the first three steps go green, and then traffic has nowhere to go. It looks like a credentials or server problem and it is neither — it is a blocked relay. See MCPM_DERP_UNREACHABLE.

Diagnostic codes

`MCPM_DERP_UNREACHABLE` — the relay servers are blocked

What it means. Your machine sits behind NAT and opens no inbound port, so MCP Manager’s servers never reach it directly. All traffic travels over the relay servers. The tunnel authenticated perfectly and then had nowhere to send packets. What is not wrong: your identity, your credentials, your MCP server. None of them are involved at this stage. The fix. Ask your network or security team to allow outbound HTTPS (TCP 443) to the hostnames the log names — normally both:

hostnames

derp-a.mcpmanager.ai
derp-b.mcpmanager.ai

Also exempt them from TLS/SSL inspection. An allow rule alone is not enough if the proxy re-signs the certificate. Allowlist by hostname, not IP — the addresses change.

There is no derp.mcpmanager.ai. The relay hostnames are derp-a and derp-b, exactly as written above. If an assistant suggested a single relay hostname, it invented it.

If the proxy runs in Docker, confirm the rule covers the container’s network path, not just the host’s browser traffic.

`MCPM_COORDINATOR_UNREACHABLE` — the coordination server is blocked

What it means. The tunnel could not start at all. The agent opens an outbound connection to headscale.mcpmanager.ai on TCP 443 to authenticate and fetch its network map, and that connection did not complete. The usual cause is a corporate secure web gateway or TLS-inspection proxy — Zscaler Internet Access, Netskope, Cisco Umbrella, Cloudflare Gateway, Palo Alto Prisma Access, Forcepoint, Broadcom/Symantec Web Security Service, Microsoft Entra Internet Access, and similar. The fix. Allow outbound HTTPS (TCP 443) to headscale.mcpmanager.ai, exempt from TLS/SSL inspection. To confirm the cause quickly, disable the proxy on the machine temporarily — then add the permanent allowlist entry.

Blocking outbound UDP alone does not cause this. The tunnel falls back to the relays over TCP 443. A stall here almost always means TCP 443 to headscale.mcpmanager.ai is itself blocked or intercepted.

`MCPM_ROUNDTRIP_TIMEOUT` — MCP Manager cannot reach this machine

What it means. The tunnel authenticated, but MCP Manager’s servers got no answer when they reached back. This is a network path problem between MCP Manager and this machine — not your identity, not your MCP server. The fix. Check the Relay servers reachable step first; blocked relays are the usual cause, and the proxy reports MCPM_DERP_UNREACHABLE instead when it can prove it. If the relays are reachable and this still times out, the path is being interrupted somewhere else — a split-tunnel VPN and an aggressive host firewall are the common candidates. The proxy keeps running and retrying throughout. It recovers on its own once the path works; you do not need to re-run setup.

`MCPM_ROUNDTRIP_LOST` — a working connection stopped

What it means. The connection was established and then went away. The proxy is still running and still retrying. The fix. Usually nothing — it recovers by itself. If it does not, check whether the machine changed networks, went to sleep, or picked up a new firewall or VPN policy. Restarting the proxy re-runs every check from the top:

terminal

docker restart mcpm-workstation-proxy

`MCPM_NO_TAILNET_IP` — the tunnel never got an address

What it means. The tunnel started but was never assigned a tailnet IP, so MCP Manager has no route to this machine. This is a tunnel setup failure, not an authentication problem. The fix. Restart the proxy. If it repeats, look earlier in the log — the tunnel subprocess error that preceded this is the real cause, and it is the part support needs:

terminal

docker logs mcpm-workstation-proxy --tail 400

`MCPM_RELAY_CHECK_SKIPPED` — relay reachability is unknown

What it means. This workstation was registered before MCP Manager started sending the relay list, so the proxy had no hostnames to test. Relay reachability is unknown — not confirmed good. The fix. Re-register the workstation from MCP Manager to pick up the relay list; the check then runs on the next start. If the connection is also failing at Connected to server, treat blocked relays as the first thing to rule out — see MCPM_DERP_UNREACHABLE.

`MCPM_RELAY_CHECK_FAILED` — the check itself broke

What it means. The relay reachability check could not run. This is a fault in the check, not evidence that your network is blocking anything. The tunnel may well be working. The fix. Re-run the workstation command. If it repeats, collect the proxy logs and contact support — this one is ours, not yours.

If none of these match

Collect both outputs and send them with your request. They contain no credentials.

terminal

docker logs mcpm-workstation-proxy --tail 400
curl -s localhost:7117/startup-progress

For deeper output, restart the proxy with debug logging from MCP Manager’s workstation setup screen, reproduce the failure, and capture the log again.

Get Started

MCP Gateway Concepts

Features

Industries

Tutorials

MCP Server Guides

Security

Deployment

Enterprise

Admin API & MCP

Build Your Own MCP Server

Advanced

Troubleshoot a workstation connection

What is actually running

Collect the evidence

Ask an AI assistant

The connection sequence

Diagnostic codes

`MCPM_DERP_UNREACHABLE` — the relay servers are blocked

`MCPM_COORDINATOR_UNREACHABLE` — the coordination server is blocked

`MCPM_ROUNDTRIP_TIMEOUT` — MCP Manager cannot reach this machine

`MCPM_ROUNDTRIP_LOST` — a working connection stopped

`MCPM_NO_TAILNET_IP` — the tunnel never got an address

`MCPM_RELAY_CHECK_SKIPPED` — relay reachability is unknown

`MCPM_RELAY_CHECK_FAILED` — the check itself broke

If none of these match

Further reading

​What is actually running

​Collect the evidence

​Ask an AI assistant

​The connection sequence

​Diagnostic codes

​MCPM_DERP_UNREACHABLE — the relay servers are blocked

​MCPM_COORDINATOR_UNREACHABLE — the coordination server is blocked

​MCPM_ROUNDTRIP_TIMEOUT — MCP Manager cannot reach this machine

​MCPM_ROUNDTRIP_LOST — a working connection stopped

​MCPM_NO_TAILNET_IP — the tunnel never got an address

​MCPM_RELAY_CHECK_SKIPPED — relay reachability is unknown

​MCPM_RELAY_CHECK_FAILED — the check itself broke

​If none of these match

​Further reading

What is actually running

Collect the evidence

Ask an AI assistant

The connection sequence

Diagnostic codes

`MCPM_DERP_UNREACHABLE` — the relay servers are blocked

`MCPM_COORDINATOR_UNREACHABLE` — the coordination server is blocked

`MCPM_ROUNDTRIP_TIMEOUT` — MCP Manager cannot reach this machine

`MCPM_ROUNDTRIP_LOST` — a working connection stopped

`MCPM_NO_TAILNET_IP` — the tunnel never got an address

`MCPM_RELAY_CHECK_SKIPPED` — relay reachability is unknown

`MCPM_RELAY_CHECK_FAILED` — the check itself broke

If none of these match

Further reading