Atlas shows the "MCP Authentication Required" toast because connectRemote detected an UnauthorizedError from the transport, stored the pending transport for the OAuth callback, and set the server status to needs_auth instead of retrying the next transport. Fix it by running `atlas mcp auth <name>`, completing the browser consent step, and re-running `atlas mcp` to confirm the status flipped from needs_auth to connected.
Why does Atlas say MCP Authentication Required
Atlas raises the "MCP Authentication Required" toast when connectRemote sees an UnauthorizedError, or an OAuth error message, come back from the transport. connectRemote then stores the pending transport for the OAuth callback and sets that server's status to needs_auth, retrying 0 further transports.
needs_auth is not a failure state in Atlas, it is a paused state. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, and a server sitting in needs_auth is telling Atlas that it will hand those tools over once a login completes. The important detail in connectRemote is that it stops trying other transports. A server in needs_auth will not quietly recover on its own or fall back to an unauthenticated connection. The toast text is explicit about the next move: Server "<name>" requires authentication. Run: atlas mcp auth <name>. That command is the only path forward.
How to authenticate an MCP server in Atlas
Authenticate an Atlas MCP server in 4 steps: run `atlas mcp auth <name>`, complete the browser consent screen, copy the printed authorization URL by hand if the browser never opens, then re-run `atlas mcp` to confirm the status flipped from needs_auth to connected.
`atlas mcp auth <name>` starts the OAuth flow for that specific server. Atlas holds the pending transport keyed by server name until the callback lands, so the login is bound to that one entry and not to your whole config. Complete the consent step in the browser Atlas opens. If no browser appears, Atlas emits an mcp.browser.open.failed event and prints the authorization URL, and copying that URL into a browser manually works exactly the same way. This matters on headless boxes, in containers, and over SSH, where launching a browser is not possible at all.
How to verify the MCP OAuth login worked
Verify the Atlas MCP login by re-running `atlas mcp` after the browser consent step and reading 1 line, the status row for that server. It should have flipped from needs_auth to connected. A row still reading needs_auth means the callback never landed and the pending transport was never exchanged.
`atlas mcp` is the check that matters because the status row is written by the same connectRemote path that set needs_auth in the first place. Once the row reads connected, the server's tools are exposed to the agent again, and each of those tool calls is permission-gated against allow, ask, and deny rules before it runs. If the row still reads needs_auth, the OAuth flow did not complete: the browser tab may have been closed before consent, or the callback may never have reached Atlas. Re-run `atlas mcp auth <name>` and complete the flow in one pass.
What to do when the browser does not open for atlas mcp auth
When `atlas mcp auth <name>` cannot launch a browser, Atlas emits an mcp.browser.open.failed event and prints the authorization URL instead. Copy that 1 URL into any browser, including one on a different machine, and complete the consent step there. The pending transport stays keyed by server name.
Atlas is a terminal-native TUI, so it runs in exactly the environments where automatic browser launching tends to fail: remote servers, SSH sessions, containers, and headless CI boxes. The mcp.browser.open.failed event is Atlas telling you plainly that it could not open a browser, not that the OAuth flow broke. The printed authorization URL is the same URL Atlas would have opened. Paste it into a browser and finish consent. Atlas holds the pending transport keyed by server name until the callback lands, which is what lets the manual path work at all.
needs_auth versus failed in the Atlas MCP dialog
In the Atlas MCP dialog, needs_auth and failed mean 2 different things. needs_auth means connectRemote reached the server and got an UnauthorizedError, so the fix is `atlas mcp auth <name>`. failed means no transport connected at all, so the fix lives in that server's `command` or `url`.
Reading the status row correctly saves a lot of wasted debugging in Atlas. A needs_auth server is reachable. The transport talked to it, the server demanded credentials, and connectRemote stored the pending transport for the OAuth callback rather than retrying. Running `atlas mcp auth <name>` is the whole fix. A failed server is a different problem entirely: nothing connected, and no amount of authentication will help. Atlas exposes both states in the same `atlas mcp` listing precisely so you can tell them apart in one command before changing anything.
How to fix it
- 01Run `atlas mcp auth <name>` to start the OAuth flow for that server.
- 02Complete the browser consent step; Atlas holds the pending transport keyed by server name until the callback lands.
- 03If the browser does not open, copy the printed authorization URL manually (Atlas emits an mcp.browser.open.failed event when it cannot launch one).
- 04Re-run `atlas mcp` and confirm the status flipped from needs_auth to connected.
Frequently asked questions
- How do I authenticate an MCP server in Atlas?
- Run `atlas mcp auth <name>` and complete the browser consent step. Atlas holds the pending transport keyed by server name until the callback lands, then the status flips from needs_auth to connected.
- What does needs_auth mean in the Atlas MCP dialog?
- needs_auth means connectRemote detected an UnauthorizedError or an OAuth error message from the transport and paused instead of retrying the next transport. The server is reachable and is waiting for you to run `atlas mcp auth <name>`.
- Atlas shows MCP Authentication Required but no browser opened, what now?
- Atlas emits an mcp.browser.open.failed event when it cannot launch a browser and prints the authorization URL instead. Copy that URL into any browser manually and complete consent; the flow finishes the same way.
- How do I confirm my MCP server is authenticated in Atlas?
- Re-run `atlas mcp` after finishing the browser step and check the status row for that server. It should have flipped from needs_auth to connected. A row still reading needs_auth means the callback never landed.
- Why did Atlas stop trying other MCP transports after the auth error?
- By design. connectRemote treats an UnauthorizedError as a signal to store the pending transport for the OAuth callback and set status needs_auth, rather than retrying the next transport. Authentication is the blocker, so another transport would fail the same way.
- Can I run atlas mcp auth over SSH or in a container?
- Yes. Atlas is a terminal-native TUI and prints the authorization URL when it cannot open a browser, signalling this with an mcp.browser.open.failed event. Open that URL from any machine to complete the consent step.
- My MCP server tools disappeared in Atlas, is that the same as needs_auth?
- If the status row reads needs_auth, yes: Atlas exposes Model Context Protocol tools to the agent only for connected servers. Run `atlas mcp auth <name>` and the tools return once the status reaches connected.
Try SeaShell in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install SeaShellRelated guides
Atlas with Magistral Medium in 2026: Deep Reasoning for Complex Code
In 2026, Atlas developers can leverage Magistral Medium for deep, multi-hop root-cause analysis across services, utilizing its 128,000 token context window.
Atlas with IBM Granite 4 Small-H (Ollama) in 2026
Explore Atlas with IBM Granite 4 Small-H (Ollama), a 32B hybrid Mamba model offering a 1M token context window for free, self-hosted use in 2026. Ideal for local, long-context code tasks.
Atlas with Gemma 4 12B (Ollama) in 2026
Explore Atlas with Gemma 4 12B (Ollama), a free, self-hosted model offering a 256K token context window. Ideal for long-context planning and code review in 2026.
Atlas for Bun: Terminal-Native AI Coding in 2026
Atlas is a terminal-native AI coding agent for Bun. Swap Node compatibility shims for Bun.serve and bun:sqlite, iterate with bun test, and format with bun fmt in 2026.
Atlas for Ruby on Rails in 2026
Atlas is a terminal-native AI coding agent for Ruby on Rails in 2026. Run it in a Rails app with a config/application.rb and review every diff before it lands.
Atlas with Mistral Large 3 (2512) in 2026
In 2026, Atlas developers can leverage Mistral Large 3 (2512) for extensive code generation and large unified diffs. With a 262,144 token context window and competitive pricing, it's ideal for substantial code
Atlas with Magistral Small in 2026
Explore Atlas with Magistral Small, Mistral AI's first open reasoning model. It offers a 128,000 token context window and explicit reasoning traces for $0.50 / 1M input tokens.
Atlas vs Gemini CLI: Terminal AI Coding Agents in 2026
Comparing Atlas and Gemini CLI in 2026: Atlas offers terminal-native TUI, detailed change review, and BYO model flexibility. Gemini CLI provides a million-plus token context and a generous free tier.