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 Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Magistral Medium: Multi-Hop Root-Cause Debugging in 2026
Magistral Medium reasons across a 128,000 token window at $2.00 / 1M input tokens and $5.00 / 1M output tokens. Atlas setup, the 16,384 token output cap, tradeoffs.
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 Gemma 4 12B (Ollama): 256K Context from a 7.6GB Download in 2026
Gemma 4 12B (Ollama) is a 7.6GB download with a 256K tokens (262,144) context, Free (self-hosted). The longest Gemma window that fits a mid-range GPU. Atlas setup.
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): Big Diffs, EU Hosted, 2026
Mistral Large 3 (2512) drives Atlas with a 262,144 token context and a matching 262,144 token output at $0.50 / 1M input tokens and $1.50 / 1M output tokens.
Atlas with Magistral Small: Open Reasoning for the Plan Agent in 2026
Magistral Small is Mistral's first open reasoning model: 128,000 tokens at $0.50 / 1M input tokens and $1.50 / 1M output tokens. Atlas setup, costs, and tradeoffs.
Atlas vs Gemini CLI: A Developer's Guide to Terminal AI Agents in 2026
Atlas vs Gemini CLI in 2026: Compare terminal AI coding agents. Atlas offers permission-gated tool calls and diff-based approvals. Gemini CLI provides a million-plus token context and a free tier.