# Atlas: MCP Authentication Required, server needs_auth > Run `atlas mcp auth `, finish the browser consent step, then re-run `atlas mcp` and confirm the status flipped from needs_auth to connected. 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 `, completing the browser consent step, and re-running `atlas mcp` to confirm the status flipped from needs_auth to connected. ## Symptom A warning toast titled "MCP Authentication Required" appears: Server "" requires authentication. Run: atlas mcp auth . The server status becomes needs_auth and its tools are not offered to the agent. ## Cause connectRemote detects an UnauthorizedError (or an OAuth error message) from the transport, stores the pending transport for the OAuth callback, and sets status needs_auth instead of retrying the next transport. ## Fix 1. Run `atlas mcp auth ` to start the OAuth flow for that server. 2. Complete the browser consent step; Atlas holds the pending transport keyed by server name until the callback lands. 3. If the browser does not open, copy the printed authorization URL manually (Atlas emits an mcp.browser.open.failed event when it cannot launch one). 4. Re-run `atlas mcp` and 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 "" requires authentication. Run: atlas mcp auth . 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 `, 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 ` 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 ` and complete the flow in one pass. ## What to do when the browser does not open for atlas mcp auth When `atlas mcp auth ` 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 `. 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 ` 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. ## FAQ ### How do I authenticate an MCP server in Atlas? Run `atlas mcp auth ` 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 `. ### 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 ` and the tools return once the status reaches connected. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/mcp-server-requires-authentication Source of truth: aeo_pages row `/resources/troubleshooting/mcp-server-requires-authentication` (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.