> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve authentication, plan, workspace, consent, and availability issues while connecting an MCP client to Atlas.

## Overview

Most MCP clients summarize connection failures as "action not available" or "authentication required". This page maps the most common signals to their root cause and the next step.

## Check the Atlas endpoint first

Atlas's hosted MCP endpoint is:

```text theme={null}
https://atlas.rebuildingus.org/mcp
```

A compliant client should reach that endpoint over HTTPS and follow Atlas's browser sign-in flow when authentication is required.

## 401 Unauthorized

You haven't authenticated yet, or your client has an expired Atlas session.

**What to do.** Let the client run the OAuth flow. If your client doesn't trigger a browser, check that:

* Your default browser launches when the client opens an HTTPS URL.
* Your client supports remote Streamable HTTP MCP servers with browser-based OAuth.
* A corporate proxy isn't blocking the sign-in window.

If you authenticated and still see 401, disconnect and reconnect to trigger a fresh authorization.

## 403 permission missing

Authentication succeeded; authorization didn't.

**What it means.** Your client does not have the permission needed for that Atlas action.

**What to do.** Reconnect the MCP server. On the consent screen, approve the requested access.

## 403 plan required

**What it means.** Your sign-in worked, but your workspace does not include MCP access. MCP access requires Atlas Pro, Atlas Team, or a Research Pass.

**What to do.** Open [pricing](/docs/account/pricing) and pick Pro, Team, or Research Pass. After the plan is active, reconnect the MCP server in your client.

## 403 "Organization context required"

You see this when an Atlas action that needs a workspace can't find one in your token.

**What it means.** Atlas could not determine which workspace should own the request. This usually means:

* You belong to two or more workspaces and skipped the workspace picker on the consent screen.
* Your only workspace was deleted or your membership changed.

**What to do.** Disconnect and reconnect the MCP server. On the consent screen, pick the workspace you want the client to operate in. If you see no picker and the failure persists, you probably have zero active memberships — go to [atlas.rebuildingus.org/organization](https://atlas.rebuildingus.org/organization) and create or accept one.

## "I never received a sign-in link"

You typed your email into Atlas's sign-in page during the OAuth flow, no error appeared, but no magic link arrived.

**What it means.** Atlas runs an operator allowlist while we're inviting users from the bootstrap list. Unapproved emails get a silent no-op (we don't reveal who's on the allowlist over the open web). When the sign-in page is reached from an OAuth flow it surfaces a hint pointing here so you can act on it.

**What to do.** Request access at [atlas.rebuildingus.org](https://atlas.rebuildingus.org) — once your email is approved, retry the OAuth flow.

## "I authenticated but Atlas actions don't appear"

Authentication succeeded and requests do not return errors, but the client UI does not show Atlas actions.

**What it means.** Most MCP clients cache the available action list and only refetch on a restart. After a successful authorization the client may not have picked up the newly available Atlas actions yet.

**What to do.** Restart the client. If Atlas actions still don't appear, reconnect Atlas from the client's MCP settings.

## "Atlas asked for confirmation and nothing changed"

Atlas does not infer consent for workspace changes. If you decline, cancel, or use a client that does not support the needed confirmation, Atlas does not save list items, create coverage targets, watch resources, or spend research runs.

**What to do.** Try the request again in a client that supports MCP follow-up questions, or complete the equivalent action in the Atlas web app when available.

## Still stuck?

* See the [authentication reference](/docs/api/authentication) for Atlas sign-in and token behavior.
* Check the [MCP Registry](/docs/mcp/registry) page for the prepared namespace and direct server URL.
* Review [Confirmations and follow-up questions](/docs/mcp/elicitation) for consent, decline, cancel, and browser handoff behavior.