> ## 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

> Common issues and how to resolve them.

## MCP connection issues

For a setup-specific path, start with [MCP overview](/docs/mcp/overview). For
permission and scope problems, keep [Scopes and permissions](/docs/mcp/scopes) open
next to this page.

### "Connection failed" or timeout

1. Check that `https://atlas.rebuildingus.org/mcp` is reachable from your network
2. If you're behind a corporate proxy, ensure it allows outbound HTTPS to `atlas.rebuildingus.org`
3. Verify your internet connection is stable

### OAuth window doesn't open

* Make sure your default browser is set correctly in your OS settings
* Some terminal-based clients need a working `open` / `xdg-open` command
* Try manually navigating to the URL printed in the terminal

### "Unauthorized" after connecting

Your OAuth token may have expired. Disconnect the Atlas server from your MCP client and reconnect to trigger a fresh authorization flow.

### Tools don't appear after connecting

* Restart your MCP client after connecting
* Some clients (Claude Desktop, VS Code) require a window reload to discover newly available tools
* Verify the connection status in your client's MCP settings

### "Transport not supported" or SSE errors

Atlas uses **Streamable HTTP** transport only. SSE-only clients cannot use the hosted Atlas MCP server.

## API issues

### 401 Unauthorized

* **Missing key:** Add `X-API-Key: your-key` header to the request
* **Invalid key:** Verify the key in your account settings — it may have been revoked
* **Wrong header:** The header is `X-API-Key`, not `Authorization` (unless using OAuth)

Read [Authentication](/docs/api/authentication) for the difference between
public reads, API keys, and OAuth.

### 429 Rate Limited

You've exceeded your plan's request limit. Check these headers in the response:

* `X-RateLimit-Remaining` — how many requests you have left
* `X-RateLimit-Reset` — when the window resets (Unix timestamp)
* `Retry-After` — how many seconds to wait before retrying

Options:

* Wait for the rate limit to reset
* Upgrade to [Atlas Pro, Team, or Research Pass](/docs/account/pricing) for higher limits
* Cache API responses to reduce requests

See [Rate limits](/docs/api/rate-limits) for limits by access pattern.

### 404 Not Found for an entity

Entity IDs are UUIDs. Common issues:

* Truncated ID (check you're using the full UUID)
* The entity was deleted or merged with another
* Typo in the place key format (use `kansas-city,missouri`, not `Kansas City, MO`)

### Empty results

* Check your query parameters — misspelled issue area slugs return no matches
* Use `GET /api/issue-areas` to see valid slugs
* Try a broader search (remove filters one at a time)

For local searches, compare your request with [Research a place](/docs/api/guides/places)
and [Issue areas & domains](/docs/taxonomy).

## Account issues

### Can't sign in

Atlas is passkey-first. Check:

* That you're using the same email you signed up with
* That your browser or password manager can offer the passkey for Atlas
* That third-party browser extensions are not blocking the WebAuthn prompt
* That your device clock is correct

### API key not working

* Keys are tied to your account — make sure you're using a key from the right account
* Keys can be revoked — check your account settings
* Free accounts don't have API key access — you need [Atlas Pro, Team, or Research Pass](/docs/account/pricing)

## Still stuck?

* Check the [GitHub repository](https://github.com/RebuildingAmerica/atlas) for known issues
* Open an issue if you've found a bug