# Quickstart: AI Agent / MCP

Connect an AI assistant to **your** Roam meetings, chat, and calendar via the
hosted MCP server — or wire a Personal Access Token into a custom agent. This
path uses **Personal access** (what you can see and do as yourself).

## Pick a path

| Path | Best for | Auth |
|------|----------|------|
| **A. Claude / ChatGPT connector** | Asking questions about meetings in the assistant UI | OAuth via MCP (no token to copy) |
| **B. Personal Access Token + MCP** | Custom MCP clients, scripts, local tools | PAT (`rmp-…`) |
| **C. Packaged agent (OpenClaw / Hermes)** | A bot that lives in Roam chat | PAT or API key — see those guides |

Full MCP reference: [MCP (AI Assistants)](/docs/integrations/mcp).

---

## Path A — Claude or ChatGPT (OAuth)

### Prerequisites

- Workspace admin has not **Disabled** MCP / Personal access
  ([Access Models](/docs/guides/access-models#admin-policy-for-personal-access))
- Default policy is **Require Approval** — an admin may need to approve your connection

### Claude

1. Open **Settings → Connectors**
2. **Add custom connector**
3. Name: `Roam` · URL: `https://api.ro.am/mcp`
4. **Connect** and complete Roam OAuth (Personal access)
5. If pending, ask an admin to approve under **Administration → Developer**

Try: *“Summarize my meetings from yesterday and list action items.”*

### ChatGPT

Use the same remote MCP URL (`https://api.ro.am/mcp`) in ChatGPT’s connector /
app UI and complete OAuth. Exact menu labels vary by ChatGPT product surface;
see the [MCP guide](/docs/integrations/mcp) for the current steps.

---

## Path B — PAT + custom MCP client

### 1. Create a Personal Access Token

1. **User Settings → Developer → Create Personal Access Token**
2. Name it (e.g. `local-mcp`)
3. Grant at least: meetings read, chat read/search, chat send (if the agent should post)
4. Copy the token (`rmp-…`) and wait for admin approval if required

```bash
export ROAM_TOKEN='rmp-…'
```

### 2. Configure your MCP client

```json
{
  "mcpServers": {
    "roam": {
      "type": "streamable-http",
      "url": "https://api.ro.am/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Paste this into your client’s MCP config (Cursor, Claude Desktop custom, etc.),
substituting `$ROAM_TOKEN`.

### 3. Smoke-test the REST API (optional)

MCP tools call the same v1 API. Confirm the token works:

```bash
curl -sS -H "Authorization: Bearer $ROAM_TOKEN" \
  https://api.ro.am/v1/token.info | jq .

curl -sS -H "Authorization: Bearer $ROAM_TOKEN" \
  "https://api.ro.am/v1/meeting.list?limit=5" | jq .
```

### Useful tools (via MCP)

| Area | Examples |
|------|----------|
| Meetings | `meeting_search`, `meeting_list`, `meeting_info`, `meeting_transcript` |
| Chat | `chat_search`, `chat_list`, `chat_history`, `chat_post` |
| People | `user_list` |
| Calendar | `calendar_list` |

The full list, with the scope each tool needs, is in the
[MCP Tool Reference](/docs/integrations/mcp#tool-reference).

Built-in prompts include `morning_brief`, `weekly_digest`, `action_item_radar`.

---

## Path C — Bot that lives in Roam chat

If you want an agent users can @-mention or DM inside Roam:

- [OpenClaw](/docs/integrations/openclaw) — Personal Bot (PAT) or Org Bot (API key)
- [Hermes](/docs/integrations/hermes) — same personal / org split

Those guides cover webhook setup, streaming replies, and access control.

---

## Next steps

- [Access Models](/docs/guides/access-models) — Personal vs Organization data and identity
- [meeting.prompt](/docs/api/meeting-prompt) / [meeting.search](/docs/api/meeting-search) — AI over transcripts via REST
- [Streaming messages](/docs/api/chat-start-stream) — token-by-token bot replies
- [Lobby booking for AI agents](/docs/integrations/lobby-agents) — public booking API without a Roam account