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

---

Path A — Claude or ChatGPT (OAuth)

Prerequisites

• Workspace admin has not Disabled MCP / Personal access (Access Models)
• 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 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

export ROAM_TOKEN='rmp-…'

2. Configure your MCP client

{
  "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:

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.

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 — Personal Bot (PAT) or Org Bot (API key)
• Hermes — same personal / org split

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

---

Next steps

• Access Models — Personal vs Organization data and identity
• meeting.prompt / meeting.search — AI over transcripts via REST
• Streaming messages — token-by-token bot replies
• Lobby booking for AI agents — public booking API without a Roam account