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

# Use Atlas with an AI assistant

> Ask an MCP-compatible assistant to find civic actors, verify sources, save research, and track coverage in Atlas.

## Overview

Atlas supports the [Model Context Protocol](https://modelcontextprotocol.io/)
(MCP), an open standard that lets compatible assistants work with external
systems. In Atlas, that means you can ask an assistant to find civic actors,
check source trails, compare place coverage, save useful records, and start
new source-linked research from the conversation.

The assistant performs the MCP operations. You stay in control of the choices
that affect your workspace, budget, account, or saved research.

**Example conversation with Claude:**

> **You:** Who's working on housing issues in Kansas City?
>
> **Claude:** I found 23 entities working on housing in Kansas City. Here are the most prominent...
>
> **You:** What are the coverage gaps?
>
> **Claude:** Kansas City has strong coverage on housing affordability and tenant organizing, but limited coverage on homelessness services and community land trusts...

## What you need

<Warning>
  MCP access requires **Atlas Pro** or **Atlas Team**. Free accounts cannot connect AI assistants. [See pricing](/docs/account/pricing).
</Warning>

1. **An Atlas account** — [Sign up](https://atlas.rebuildingus.org) if you haven't already.
2. **Atlas Pro, Team, or Research Pass** — MCP access requires a paid plan ([see pricing](/docs/account/pricing)). Free-tier sign-ins can complete, but Atlas assistant capabilities stay unavailable until a plan is active.
3. **An MCP-compatible client** — Claude Desktop, Claude Code, VS Code with Copilot, Gemini CLI, Codex CLI, or Copilot CLI.

<Note>
  **Before you connect**

  * **Bootstrap allowlist.** Atlas runs an operator allowlist while we're inviting users from the bootstrap list. If your email isn't on it and you don't have a workspace invitation, the OAuth sign-in won't deliver a magic link. Request access at [atlas.rebuildingus.org](https://atlas.rebuildingus.org) before connecting an MCP client.
  * **Workspace binding.** After signing in, your primary workspace is selected automatically. Multi-workspace users see a workspace picker on the consent screen.
  * **Session lifecycle.** Most MCP clients keep the connection fresh automatically. If Atlas asks you to sign in again, complete the browser flow.
</Note>

## What Atlas can help with

After you connect Atlas, you can ask an assistant to:

* Find people, organizations, initiatives, campaigns, and events by place,
  issue area, source type, or search text.
* Show where a claim came from by opening the sources behind an actor or
  research run.
* Compare civic coverage across places and issue areas, including where Atlas
  has strong evidence and where coverage is thin.
* Save selected actors to private workspace lists.
* Create private coverage targets that help your workspace track a place,
  issue, actor type, or evidence gap.
* Watch actors or coverage targets for source-backed changes.
* Start a new research run when existing Atlas coverage is not enough.
* Open Atlas account settings from the conversation when you need to manage
  billing or API-key setup.

## Connection details

Atlas runs a remote MCP server at:

```
https://atlas.rebuildingus.org/mcp
```

When you connect this server, your assistant can request Atlas search,
discovery, workspace, and account actions through the MCP client. On first use,
the client opens a browser for Atlas sign-in and access approval.

Atlas also lets compatible clients reopen selected research outputs later,
including source-linked briefs, source trails, and place coverage summaries.
Atlas does not publish the entire entity catalog as a browsable MCP resource.

## Available capabilities

Once connected, your assistant can use these Atlas capabilities:

| Capability             | What you can ask for                                                    |
| ---------------------- | ----------------------------------------------------------------------- |
| Actor search           | Find civic actors by place, issue, type, source, or text                |
| Source verification    | See the public sources behind an actor, source trail, or research run   |
| Place context          | Get demographic context, issue signals, and coverage gaps for a place   |
| Relationship discovery | Explore how actors are connected through Atlas relationships            |
| Issue-area mapping     | Turn plain-language topics into Atlas issue categories                  |
| Research history       | Reopen completed Atlas research runs and briefs                         |
| New research           | Start a source-linked research run when existing coverage is not enough |
| Saved work             | Save selected actors to private workspace lists                         |
| Coverage tracking      | Create private coverage targets and watch them for changes              |
| Account handoff        | Open Atlas account settings with browser consent                        |

<Tip>
  See [Atlas capabilities reference](/docs/mcp/tools) for the operation names,
  parameters, and example requests used by MCP-compatible assistants.
</Tip>

## Available resources

Atlas resources let compatible clients reopen selected research outputs:

| Resource                                  | What it provides                    |
| ----------------------------------------- | ----------------------------------- |
| `atlas://discovery-runs/{run_id}`         | Structured discovery-run record     |
| `atlas://discovery-runs/{run_id}/brief`   | Source-linked research brief        |
| `atlas://discovery-runs/{run_id}/sources` | Sources referenced by a run summary |
| `atlas://entities/{entity_id}/sources`    | Public source trail for one entity  |
| `atlas://cities/{place_key}/coverage`     | City coverage summary               |
| `atlas://states/{state}/coverage`         | State coverage summary              |

`resources/list` returns only a short set of recent research runs and Atlas UI
resources. Ask your assistant to find the relevant records first, then use
returned `resource_uri` values to open the same records later.

<Tip>
  See [Available resources](/docs/mcp/resources) for resource templates and large
  catalog behavior.
</Tip>

## Guided research starters

Some MCP clients can show Atlas research starters as selectable commands. Use
them when you want a guided starting point for common civic research jobs:
researching a place, finding civic actors, inspecting an entity's source trail,
assessing coverage gaps, or creating a brief from an existing discovery run.

Research starters are read-only in this version. They help the assistant follow
the right Atlas source-checking steps, but they do not create discovery runs or
modify workspace data.

<Tip>
  See [Guided research starters](/docs/mcp/prompts) for the available starting points
  and what information they may ask for.
</Tip>

## Clarification and confirmations

Atlas may ask for a small clarification or confirmation before the assistant
continues. Read-only requests use this only when a choice materially changes
the result, such as an ambiguous place or issue-area match. Workspace actions
require explicit confirmation before saving actors, creating coverage targets,
watching resources, or spending a research run.

Sensitive interactions stay on Atlas-owned browser pages. Billing settings use
browser consent instead of passing payment information through the MCP client.

See [Confirmations and follow-up questions](/docs/mcp/elicitation) for the full
privacy and troubleshooting boundary.

## Long-running research runs

Most Atlas answers come from data that already exists. New research runs create
fresh source-linked research, so compatible clients receive a task handle and
can check progress while the run finishes.

Clients without task support receive an explicit error. Use
`list_discovery_runs` or `get_discovery_run` to check on runs started elsewhere.

## Workspace admin activity

Workspace admins can see successful integration activity by surface: total calls, API calls, MCP calls, top paths, and last-seen timestamps. Atlas does not expose request payloads, prompts, raw metadata, private notes, or session replay in that view.

See [Workspace integration activity](/docs/workspace/integration-activity) for the access requirements and data boundary.

## Connect from a compliant client

Every supported client uses the same Atlas endpoint. Use your MCP client's
built-in flow for adding a remote MCP server, then provide the Atlas server URL:

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

Atlas expects a client that can connect to hosted MCP servers and complete
browser sign-in. Local-only MCP clients cannot connect to the hosted Atlas
server.

After connecting, see [Atlas capabilities reference](/docs/mcp/tools), [Available resources](/docs/mcp/resources), or [Tutorial: Research a city](/docs/mcp/tutorials/research-city) for a complete session.

## Troubleshooting

**"Connection failed" or timeout**
Check that `https://atlas.rebuildingus.org/mcp` is reachable from your network. If you're behind a corporate proxy, ensure it allows outbound HTTPS.

**OAuth window doesn't open**
Make sure your default browser is set correctly and your MCP client supports remote OAuth login.

**"Unauthorized" after connecting**
Your OAuth token may have expired. Disconnect and reconnect the server in your client to trigger a fresh authorization flow.

**Atlas actions don't appear**
Restart your MCP client after connecting. Some clients require a reload to discover newly available Atlas actions.

For more help, see [MCP troubleshooting](/docs/mcp/troubleshooting) or the general [Troubleshooting](/docs/resources/troubleshooting) guide.

## References

Atlas publishes the hosted server URL, required plan, available capabilities, scopes, and Atlas-side troubleshooting. Client-specific menus and command names belong in the client documentation.

* [MCP Registry](/docs/mcp/registry) — Atlas's prepared registry namespace and metadata status.
* [MCP resources](/docs/mcp/resources) — Research outputs that can be opened again.
* [Authentication reference](/docs/api/authentication) — Token lifecycle, refresh rotation, and discovery URL catalog.