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

# Introduction

> Connect ChatGPT, Claude, Claude Code, Codex, and Cursor to Roe over OAuth or a Roe API key

Roe hosts an [MCP](https://modelcontextprotocol.io) server that exposes your
agents, tables, jobs, policies, and connections as tools your AI assistant can
call directly — *"list my Roe agents"*, *"run the merchant-risk agent on this
URL"*, *"query my tables"*. One URL, OAuth sign-in, done.

## Set up

Connect your client to:

```text theme={null}
https://mcp.roe-ai.com/mcp
```

(Single-tenant deployment? Use `https://mcp.<tenant>.roe-ai.com/mcp` everywhere
below.) The first time you connect, a browser window opens the Roe sign-in —
approve it once and the client remembers you.

<Tabs>
  <Tab title="ChatGPT">
    **Settings → Connectors → Create** (on Plus/Pro, enable Developer mode under
    Connectors → Advanced first). Name it `Roe`, paste the MCP URL, keep **OAuth**,
    click **Connect**. Enable Roe from the **+ / tools** menu in a chat. Connectors
    are account-wide, so web and desktop share it.
  </Tab>

  <Tab title="Claude">
    **Settings → Connectors → Add custom connector** (same flow on claude.ai and
    Claude Desktop). Paste the MCP URL, click **Add → Connect**, finish the Roe
    OAuth flow. On Team/Enterprise an Owner adds it org-wide first, then members
    connect individually.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http roe https://mcp.roe-ai.com/mcp
    ```

    Then run `/mcp` in a session, pick `roe`, and finish the browser sign-in.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add roe --url https://mcp.roe-ai.com/mcp
    codex mcp login roe --scopes mcp.tools
    ```

    Restart `codex`; check with `codex mcp list`.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` and restart Cursor — it prompts for the OAuth
    sign-in on first use:

    ```json theme={null}
    {
      "mcpServers": {
        "roe": { "url": "https://mcp.roe-ai.com/mcp" }
      }
    }
    ```
  </Tab>
</Tabs>

**Verify:** ask your assistant to *"use the Roe whoami tool"*. A successful
reply returns your `user_id`, `org_id`, and `email`.

### Prefer an API key?

Clients that support custom headers (**Claude Code**, **Cursor**, **Codex**)
can skip OAuth — good for scripts and CI. Send both headers on every call:

| Header                  | Value              | Where to get it                                                              |
| ----------------------- | ------------------ | ---------------------------------------------------------------------------- |
| `Authorization`         | `Bearer <api-key>` | [app.roe-ai.com/settings/api-keys](https://app.roe-ai.com/settings/api-keys) |
| `X-Roe-Organization-Id` | `<org-uuid>`       | **Settings → Organization** in the same Roe app                              |

For example, in Claude Code:

```bash theme={null}
claude mcp add --transport http roe https://mcp.roe-ai.com/mcp \
  --header "Authorization: Bearer your-org-api-key" \
  --header "X-Roe-Organization-Id: your-org-uuid"
```

Cursor takes the same two headers in a `headers` block in `mcp.json`; Codex
needs them bridged through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote).
ChatGPT and Claude's connector UIs don't expose custom headers, so they always
use OAuth.

<Note>
  Want to **build workflows** — agents chained into pipelines with loops,
  branches, and merges — straight from your assistant? Install the
  [Workflow Builder skill](/mcp/skills/workflow-builder); it teaches the model
  every workflow-authoring nuance.
</Note>

## Tools

The exact set depends on your deployment — check the tool list your server
advertises, or ask the assistant to call `get_help`. See the generated
[MCP tools reference](/mcp/tools) for the full current list with inputs and
behavior notes.

`get_agent_job_status` returns an integer: `0` PENDING, `1` STARTED, `2` RETRY,
`3` SUCCESS, `4` FAILURE, `5` CANCELLED, `6` CACHED — stop polling on 3/4/5/6.

For the judgment calls between these tools — sync vs async vs batch, polling,
table-query flow, error handling — install the
[Roe MCP Basics skill](/mcp/skills/roe-mcp-basics).

## Troubleshooting

| Symptom                           | Fix                                                                                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No Roe tools after editing config | Restart the client — MCP config loads at startup.                                                                                                                  |
| `401`                             | OAuth: reconnect through the client's connector UI. API key: check the key isn't revoked and the `X-Roe-Organization-Id` header is present, from the same backend. |
| `503` with `Retry-After`          | Rate-limited or briefly unreachable — back off and retry.                                                                                                          |
| Wrong tenant                      | Use your tenant's MCP URL with a key/org-id minted on that same tenant.                                                                                            |

Need help? Email [support@roe-ai.com](mailto:support@roe-ai.com).