# Atlas error: MCP server failed to connect > Run `atlas mcp`, confirm the status row says failed, test the server's command or url by hand, raise `timeout`, then restart Atlas to reconnect. Atlas reports MCP server "" failed because MCP.connectTransport could not complete client.connect inside withTimeout for any configured transport, so the server was stored with status failed. Fix it by running `atlas mcp` to read the status row, testing the server's `command` or `url` outside Atlas, raising the `timeout` on that server entry if it boots slowly, and restarting Atlas so connectRemote/connectLocal run again. ## Symptom Atlas prints: MCP server "" failed. Note, Atlas does not support MCP authentication yet. The server shows status "failed" in the MCP dialog, and none of its tools are offered to the agent. ## Cause MCP.connectTransport wraps client.connect in withTimeout and closes the transport on failure. When every configured transport fails, the server is stored with status failed and the MCPFailed named error is surfaced by the CLI error formatter. ## Fix 1. Run `atlas mcp` and check the server's status row: failed, needs_auth, needs_client_registration, or disabled. 2. For a local server, run the exact `command` array from your config by hand in the same cwd and confirm it starts and speaks stdio. 3. For a remote server, confirm the `url` is reachable and returns a Streamable HTTP or SSE endpoint, not an HTML page. 4. Raise the connect timeout with `timeout` on the server entry (it defaults to DEFAULT_TIMEOUT in mcp/index.ts) if the server is slow to boot. 5. Restart Atlas so the MCP layer re-runs connectRemote/connectLocal and re-stores the client. ## Why does Atlas report MCP server failed to connect Atlas reports a failed MCP server when MCP.connectTransport exhausts every configured transport. connectTransport wraps client.connect in withTimeout and closes the transport on failure, and once 0 transports remain, the server is stored with status failed and the MCPFailed named error reaches the CLI error formatter. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, so a failed connection means the whole tool surface of that server disappears from the session. The failure is not partial. Atlas does not keep a half-open client around. connectTransport closes the transport when the connect attempt does not complete, tries the next configured transport, and when none of them succeed, stores the server with status failed. The message you see, MCP server "" failed, plus the note that Atlas does not support MCP authentication yet, is the formatted MCPFailed error rather than raw transport output. That distinction matters when debugging: the real reason lives in the server process or the endpoint, not inside Atlas. ## How to fix a failed MCP server in Atlas Fix a failed MCP server in Atlas with 5 steps: run `atlas mcp` to read the status row, run the local `command` array by hand in the same cwd, confirm a remote `url` returns Streamable HTTP or SSE, raise `timeout` on the entry, then restart Atlas. Start with `atlas mcp`. The status row tells you which of the four states you are in: failed, needs_auth, needs_client_registration, or disabled. Only failed points at the connect path described here. For a local server, copy the exact `command` array out of your config and run it yourself from the same cwd. If it does not start, or it prints logs to stdout instead of speaking stdio, Atlas can never connect. For a remote server, fetch the `url` and check that it returns a Streamable HTTP or SSE endpoint. A login redirect or an HTML page is a very common cause. If the server does boot but boots slowly, set `timeout` on the server entry; it defaults to DEFAULT_TIMEOUT in mcp/index.ts. ## How to verify the MCP connection is fixed Verify the fix by restarting Atlas so the MCP layer re-runs connectRemote/connectLocal and re-stores the client, then running `atlas mcp` again. The status row for that server should no longer read failed, and its tools should be offered to the agent within 1 turn. Atlas re-runs the connect path at startup, so a config change without a restart proves nothing. After restarting, `atlas mcp` is the single check that matters: the status row is written by the same code that stored the failure. If the row still reads failed, the transport is still failing and the fix has not landed. If it reads needs_auth or needs_client_registration instead, the connection now works and you have moved on to a different, separate problem in the OAuth path. Once the server is connected, the agent can call its tools, and every one of those tool calls is permission-gated against allow, ask, and deny rules before it runs. ## Local stdio servers versus remote MCP servers in Atlas Atlas treats local and remote MCP servers through 2 different connect paths, connectLocal and connectRemote. A local server is launched from a `command` array and speaks stdio. A remote server is reached at a `url` that must serve a Streamable HTTP or SSE endpoint, not an HTML page. Knowing which path your server takes narrows the debugging by half. A local Atlas MCP server fails when the command is not on PATH, when the cwd is wrong, or when the process exits immediately. Reproduce it by running the exact `command` array yourself. A remote Atlas MCP server fails when the `url` is unreachable, when a proxy sits in front of it, or when the endpoint returns HTML instead of a protocol response. Note the honest caveat in the message Atlas prints: Atlas does not support MCP authentication yet in this path, so a server that expects a login will not simply work by fixing the URL. Check the `atlas mcp` status row for needs_auth in that case. ## When raising the MCP timeout is the right fix Raising `timeout` on an Atlas MCP server entry is the right fix in exactly 1 situation: the server boots correctly when you run it by hand, but takes longer than DEFAULT_TIMEOUT in mcp/index.ts to complete client.connect. Raising the timeout on a broken command only delays the same failure. MCP.connectTransport wraps client.connect in withTimeout, so a slow server and a dead server produce the same failed status. Separate them before touching config. Run the local `command` array by hand and time it, or fetch the remote `url` and time the response. If the server genuinely needs more seconds to be ready, set `timeout` on that server entry and restart Atlas. If the server never becomes ready, no timeout value helps, and the real fix is in the command, the cwd, or the endpoint. Atlas snapshots file changes as git patches, so any config edits Atlas itself makes on your behalf can be diffed and rolled back if a timeout change makes things worse. ## FAQ ### What does MCP server failed mean in Atlas? In Atlas, MCP server "" failed means MCP.connectTransport could not complete client.connect on any configured transport. Each attempt is wrapped in withTimeout and the transport is closed on failure, after which the server is stored with status failed. ### How do I check MCP server status in Atlas? Run `atlas mcp`. The status row for each server reads failed, needs_auth, needs_client_registration, or disabled. failed points at the connect path; the other three point at OAuth or at a server you turned off. ### How do I increase the MCP connect timeout in Atlas? Set `timeout` on that server's entry in your Atlas config. It defaults to DEFAULT_TIMEOUT in mcp/index.ts. Raise it only when the server boots correctly by hand but boots slowly, then restart Atlas. ### Why do my MCP tools not show up in Atlas? When an Atlas MCP server is stored with status failed, none of its tools are exposed to the agent. Atlas connects to Model Context Protocol servers and exposes their tools only for servers that reached a connected state, so fix the connection first. ### Does Atlas support MCP authentication? The failed-connection message Atlas prints includes the note that Atlas does not support MCP authentication yet. If your server needs a login, look for a needs_auth status row in `atlas mcp` rather than expecting the plain connect path to succeed. ### Do I need to restart Atlas after fixing my MCP config? Yes. Restarting Atlas is what makes the MCP layer re-run connectRemote/connectLocal and re-store the client. A config change without a restart leaves the old failed status in place. ### My remote MCP server url loads in a browser, so why does Atlas still fail? A url that loads in a browser is often returning an HTML page, not a Streamable HTTP or SSE endpoint. Atlas needs the protocol endpoint. Confirm the `url` returns Streamable HTTP or SSE, not HTML, then restart Atlas. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/mcp-server-failed-to-connect Source of truth: aeo_pages row `/resources/troubleshooting/mcp-server-failed-to-connect` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.