> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot a workstation connection

> How to diagnose a workstation server that will not connect: read the proxy container's logs, query its live connection state as JSON, and look up the diagnostic code it reports. Written so you — or an AI assistant reading these docs — can go from a stuck setup screen to the exact hostname your network team needs to allow.

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.

<Info>
  **In a hurry?** Run this on the workstation and read the block it prints:

  ```bash terminal theme={null}
  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](#diagnostic-codes) to look yours up.
</Info>

## 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.

<Tabs>
  <Tab title="Proxy logs (start here)">
    ```bash terminal theme={null}
    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:

    ```bash terminal theme={null}
    docker ps -a --filter name=mcpm-workstation-proxy
    ```
  </Tab>

  <Tab title="Live state as JSON">
    ```bash terminal theme={null}
    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.

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

## Ask an AI assistant

MCP Manager's documentation is published for AI agents — see [Docs for AI agents](/get-started/use-docs-with-ai). If your assistant can read these docs, give it the output and it can take you the rest of the way:

```text prompt theme={null}
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`](#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`](#mcpm-no-tailnet-ip)                                                                                                                         |
| **Relay servers reachable**  | Traffic has somewhere to travel.                      | [`MCPM_DERP_UNREACHABLE`](#mcpm-derp-unreachable) · [`MCPM_RELAY_CHECK_FAILED`](#mcpm-relay-check-failed) · [`MCPM_RELAY_CHECK_SKIPPED`](#mcpm-relay-check-skipped) |
| **Connected to server**      | MCP Manager reached back to this machine, end to end. | [`MCPM_ROUNDTRIP_TIMEOUT`](#mcpm-roundtrip-timeout) · [`MCPM_ROUNDTRIP_LOST`](#mcpm-roundtrip-lost)                                                                 |

<Warning>
  **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`](#mcpm-derp-unreachable).
</Warning>

## Diagnostic codes

<div id="mcpm-derp-unreachable" />

### `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:

```text hostnames theme={null}
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.

<Note>
  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.
</Note>

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

<div id="mcpm-coordinator-unreachable" />

### `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.

<Note>
  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.
</Note>

<div id="mcpm-roundtrip-timeout" />

### `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`](#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.

<div id="mcpm-roundtrip-lost" />

### `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:

```bash terminal theme={null}
docker restart mcpm-workstation-proxy
```

<div id="mcpm-no-tailnet-ip" />

### `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:

```bash terminal theme={null}
docker logs mcpm-workstation-proxy --tail 400
```

<div id="mcpm-relay-check-skipped" />

### `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-derp-unreachable).

<div id="mcpm-relay-check-failed" />

### `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.

```bash terminal theme={null}
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.

## Further reading

* [Workstation MCP Servers](/mcp-gateway-concepts/mcp-servers/workstation) — how the tunnel works, and the full network requirements
* [Connect a workstation server](/tutorials/connect-a-workstation-server) — the end-to-end walkthrough
* [Docs for AI agents](/get-started/use-docs-with-ai) — point your assistant at these docs