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.

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.

Atlas error: MCP server failed to connect

Atlas reports MCP server "<name>" 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.

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 "<name>" 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.

How to fix it

01Run `atlas mcp` and check the server's status row: failed, needs_auth, needs_client_registration, or disabled.
02For a local server, run the exact `command` array from your config by hand in the same cwd and confirm it starts and speaks stdio.
03For a remote server, confirm the `url` is reachable and returns a Streamable HTTP or SSE endpoint, not an HTML page.
04Raise 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.
05Restart Atlas so the MCP layer re-runs connectRemote/connectLocal and re-stores the client.

Frequently asked questions

What does MCP server failed mean in Atlas?: In Atlas, MCP server "<name>" 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.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Atlas with DeepSeek Coder V2 16B Lite (Ollama): The 160K Local Agent Model in 2026

DeepSeek Coder V2 16B Lite (Ollama) gives Atlas a 160K token context from an 8.9GB download, Free (self-hosted). Setup, MoE speed, and the KV cache catch, for 2026.

Atlas with Llama 3.1 405B: The 243GB Landmark in 2026

Llama 3.1 405B in Atlas for 2026: 405 billion openly released parameters, a 128,000 token window, Free (self-hosted), and a 243GB download that decides everything.

Atlas with Gemma 4 31B (Ollama): the Flagship Gemma 4 Tag in 2026

Gemma 4 31B (Ollama) is the largest Gemma 4 tag: 20GB weights, a 256K tokens (262,144) context, Free (self-hosted), plus a 31b-coding-mtp-bf16 variant. Atlas setup.

Atlas with Nebius Token Factory in 2026: EU Infrastructure and the -fast Latency Lever

Atlas with Nebius Token Factory in 2026: EU-operated infrastructure, Qwen3.5-397B-A17B at $0.60/$3.60 per Mtok, and an 8,192 token output cap to plan around.

Atlas with IBM Granite 4 Small-H (Ollama): a 1M-Token Local Window in 2026

IBM Granite 4 Small-H (Ollama) is a hybrid Mamba model with 1M tokens (1,048,576) of context from a 19GB download, Free (self-hosted). Atlas setup and memory notes.

Atlas with Qwen3-Coder 30B-A3B Instruct: The Default Open Agentic Coder in 2026

Qwen3-Coder 30B-A3B Instruct in Atlas: 256K tokens (262,144), $0.45 per Mtok input, $2.25 per Mtok output, and 3.3B active parameters out of 30B total.

Atlas with StarCoder2 (local via Ollama): Auditable Training Data in 2026

StarCoder2 is BigCode's open code model, trained on The Stack v2 with full data provenance. Free self-hosted, 600-plus languages, 16,384 token context. Atlas setup.

Atlas vs JetBrains AI Assistant: Terminal AI Coding Agents in 2026

Atlas and JetBrains AI Assistant comparison for 2026. Atlas offers a terminal-native TUI and BYO model keys, while JetBrains AI Assistant integrates into IDEs with credit-based cloud models.

Browse this resource hub