# MCP (AI Assistants) The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external data sources. Roam's MCP server exposes the Roam API as MCP tools — giving your AI assistant direct access to your meetings, transcripts, chat, calendar, and more. You can ask questions like "What did we decide about pricing in last week's meeting?" and get answers grounded in your actual conversations, or have the assistant post a chat message or create a calendar event on your behalf. ## Connections **OAuth MCP connections** (Claude, ChatGPT, Codex, Grok via the connect card) are **personal** — each is created by an individual user and scoped to that user's own meetings, chats, calendar, and groups. They never receive roam-wide meeting access (`admin:meetings:read` is org-only). Custom MCP clients can also send a **Personal Access Token** (`rmp-…`) or an **organization API key** (`rmk-…`) as a Bearer token. A PAT is still Personal access. An API key is Organization access: the bot persona, group membership, and org scopes (including `admin:meetings:read` when granted). MCP is outbound only — it does not make Grok a DM-able bot in Roam chat. For that, see [Grok Bot](/docs/integrations/grok). ## Admin Controls Roam admins control whether MCP connections are allowed in your workspace. By default, new connections require admin approval before they can access data. Admins can change the approval policy in **Administration > Developer**: | Policy | Behavior | | ------------------------------ | -------------------------------------------------------- | | **Require Approval** (default) | New connections are pending until an admin approves them | | **Auto-Approve** | New connections are approved automatically | | **Disabled** | MCP connections are not allowed | When a user creates a new connection with the **Require Approval** policy, admins will be notified and can approve or deny the request from the Administration panel. ![Administration > Developer showing approval policy options and token list with Approve/Reject/Revoke actions](/img/mcp/admin-approval-policy.png) ## Scopes & Permissions Every tool maps to a Roam API endpoint that requires a specific OAuth **scope** (for example, `meetings:read` to read meetings, or `chat:send_message` to post a chat message). The [Tool Reference](#tool-reference) lists the scope each tool needs. MCP uses the same OAuth scopes as the rest of the Roam API. The full set the MCP server supports is published in its [protected-resource metadata](https://api.ro.am/.well-known/oauth-protected-resource) under `scopes_supported`, so clients can discover it programmatically. :::warning `calendar_list` needs `calendar:read` Reading connected calendars requires `calendar:read`. This used to fall under `meetings:read`, which grants it only for clients registered **before 2026-07-29T00:00Z** — anything registered on or after that date must hold `calendar:read`, or `calendar_list` returns a [missing-scope `403`](/docs/guides/error-codes). Only `calendar_list` is affected; the `meeting_*` tools still use `meetings:read`. See [Scopes](/docs/guides/scopes#calendarread-and-meetingsread). ::: How scopes are granted depends on the client: - **OAuth assistants (Claude, ChatGPT, Codex, Grok)** can't present a Roam scope picker, so each connection is granted the **default MCP scope set** automatically — the same set published in `scopes_supported`. It's a broad set that covers every MCP tool, including write tools such as `chat_post`, `calendar_event_create`, and the OnAir tools. - **Personal Access Tokens** and other custom clients let you choose exactly which scopes to grant (see [Custom MCP Clients](#custom-mcp-clients)) — grant only what your integration needs. The server **advertises every tool regardless of your granted scopes**; calling a tool whose scope you weren't granted returns a permission error (`403`). In practice this only affects Personal Access Tokens created with a narrow scope selection — a default OAuth connection receives the full set and can call every tool. :::note Per-connection scope selection for OAuth assistants is a planned future capability. Today these connections receive the full default MCP scope set; use a Personal Access Token if you need tighter, least-privilege scoping. ::: ## Claude [Claude](https://claude.ai) supports MCP natively through its Connectors feature. No token or manual configuration is needed — Claude handles authentication via OAuth.
Connect to Claude
The button opens Claude's custom-connector dialog with **Name** `Roam` and **URL** `https://api.ro.am/mcp` already filled in. Click **Add**, then **Connect**, and complete the OAuth consent flow. Roam is not in Claude's connector directory, so searching **Suggested Connectors** won't find it — use the button above, or add a custom connector by hand: 1. Open **Settings > Connectors**. 2. Click **Add custom connector**. 3. Enter a name (e.g. "Roam") and the Remote MCP Server URL: `https://api.ro.am/mcp` 4. Click **Connect** and complete the OAuth consent flow. ![Claude Settings > Connectors showing the "Add custom connector" dialog with Roam configured](/img/mcp/claude-connector-setup.png) Once connected, Roam's tools are available in your conversations. ### Using Prompts To use a built-in prompt, click the **+** button in the message composer, select **Add from Roam**, and choose a prompt (e.g. `morning_brief` or `weekly_digest`). ![Claude + menu showing "Add from Roam" with available prompts](/img/mcp/claude-add-prompt.png) ## ChatGPT ChatGPT supports MCP through its Apps feature. To connect Roam: > Using OpenAI's **Codex** coding agent instead of the ChatGPT app? It's a different product > configured separately — see [Codex](#codex). 1. Open **Settings > Apps > Advanced Settings**. 2. Turn on **Developer Mode**. 3. Click **Create app**. 4. Enter a name (e.g. "Roam") and the MCP URL: `https://api.ro.am/mcp` 5. Click **Create**. ![ChatGPT Settings > Apps > Advanced Settings with Developer Mode enabled](/img/mcp/chatgpt-developer-mode.png) ![ChatGPT New App dialog with Roam name and MCP server URL configured](/img/mcp/chatgpt-create-app.png) Once connected, you can use Roam in a conversation by clicking **+** > **More** > **Roam**. ![ChatGPT + menu showing Roam app under More](/img/mcp/chatgpt-roam-app.png) Try asking about your recent meetings or chat messages. :::note ChatGPT does not support MCP prompts. Use the tools directly by asking questions in natural language. ::: ![ChatGPT conversation analyzing a meeting using Roam tools](/img/mcp/chatgpt-mcp-example.png) ## Codex OpenAI's [Codex](https://developers.openai.com/codex) coding agent is **not** the ChatGPT app — it connects to MCP servers through Codex's own settings, not through ChatGPT's Apps settings, so the [ChatGPT](#chatgpt) steps above don't apply. Roam is served over **Streamable HTTP**, which current Codex versions support natively. Connect it from the command line or the Codex app; either way the connection authenticates over OAuth and receives the [default scope set](#scopes--permissions), the same as Claude and ChatGPT. ### Command line Register Roam with the `codex mcp` CLI: ```bash codex mcp add roam --url https://api.ro.am/mcp ``` Because Roam advertises OAuth, Codex detects it and opens your browser to Roam's consent flow automatically — there's no token to copy and no separate login step: ``` Added global MCP server 'roam'. Detected OAuth support. Starting OAuth flow… Successfully logged in. ``` Verify with `/mcp` inside Codex — Roam should appear as connected, with its tools listed. (To re-authenticate later, run `codex mcp login roam`.) :::note Troubleshooting If `codex mcp add` can't load the server — for example an error like ``missing field `command` in `mcp_servers.roam` `` — your Codex version is too old to use URL-based (Streamable HTTP) servers and only understands `command`-based stdio servers. Upgrade to the latest Codex and the `url` entry will load. ::: ### Codex app In the Codex app, open **Settings > MCP servers** and click **Add server**. Fill in the form: - **Name**: `Roam` - Select the **Streamable HTTP** transport. - **URL**: `https://api.ro.am/mcp` - Leave **Bearer token env var** and the header fields empty — Roam uses OAuth. Click **Save**. ![Codex "Connect to a custom MCP" form with Streamable HTTP selected and the Roam server URL entered](/img/mcp/codex-app-add-server.png) Back on the **MCP servers** list, the new server shows an **Authenticate** button. Click it to complete Roam's OAuth consent flow. ![Codex MCP servers list showing the Roam server with an Authenticate button](/img/mcp/codex-app-authenticate.png) :::note Codex does not support MCP prompts. Use the tools directly by asking questions in natural language. ::: ## Grok xAI has three products that connect to MCP. Setup does not carry over between them. This section is **outbound** (Grok calls Roam tools). For a Grok Bot people DM **inside Roam**, see [Grok Bot](/docs/integrations/grok). Short version for each product: ### Grok Bot [Grok Bot](https://docs.x.ai/grok-bot/overview) has no config file. In a conversation: > Add a custom MCP server called roam at https://api.ro.am/mcp Say **custom server** — there is no Roam marketplace plugin yet. Confirm, then complete the OAuth connect card (Personal access). For an org bot, tell it to add the same URL with header `Authorization: Bearer rmk-…`. Type `@` and attach **roam** before asking about meetings or chat. ### Grok chat 1. Open [grok.com/connectors](https://grok.com/connectors) 2. **New Connector → Custom** 3. URL: `https://api.ro.am/mcp` 4. Complete Roam OAuth (Personal) On Grok Business / Enterprise, a team admin must provision the custom server first. ### Grok Build ```bash grok mcp add --transport http roam https://api.ro.am/mcp ``` Roam advertises OAuth, so Grok Build opens a browser to the consent flow. For a PAT or org API key instead: ```bash grok mcp add --transport http roam https://api.ro.am/mcp \ --header "Authorization: Bearer ${ROAM_TOKEN}" ``` `grok mcp doctor roam` verifies the connection. ## Custom MCP Clients You can connect any MCP-compatible client to Roam's server. **Server URL:** `https://api.ro.am/mcp` **Transport:** Streamable HTTP **Authentication:** Bearer token in the `Authorization` header. Clients can complete the OAuth flow (the server supports Dynamic Client Registration), send a Personal Access Token (`rmp-…`), or send an organization API key (`rmk-…`). OAuth and PATs are Personal access; an API key is Organization access. ### OAuth details For the general third-party OAuth install flow (non-MCP), token lifetimes, and refresh, see **[OAuth & Authentication](/docs/guides/oauth)**. MCP-specific discovery and DCR notes continue below. Clients that implement the [MCP authorization](https://modelcontextprotocol.io/specification/basic/authorization) flow can discover everything they need from Roam's standard metadata: | Item | Value | | ----------------------------- | -------------------------------------------------------------------------- | | Protected-resource metadata | `https://api.ro.am/.well-known/oauth-protected-resource` | | Authorization-server metadata | `https://ro.am/.well-known/oauth-authorization-server` | | Resource (audience) | `https://api.ro.am/mcp` | | Authorization endpoint | `https://ro.am/oauth/authorize` | | Token endpoint | `https://ro.am/oauth/token` | | Registration endpoint (DCR) | `https://ro.am/oauth/register` | | PKCE | Required for public clients; `S256` only | | Token endpoint auth methods | `none` (public client + PKCE), `client_secret_post`, `client_secret_basic` | | Scopes | See `scopes_supported` in the protected-resource metadata | Both public clients (`token_endpoint_auth_method: none` with PKCE) and confidential clients (with a client secret) are supported. Public clients **must** use PKCE with `code_challenge_method=S256` — `plain` is rejected. Dynamically registered assistants that don't request specific scopes receive the [default MCP scope set](#scopes--permissions). **Using `mcp-remote`:** the most reliable setup passes a Personal Access Token as a bearer header: ```bash npx mcp-remote https://api.ro.am/mcp --header "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" ``` `mcp-remote`'s built-in OAuth (Dynamic Client Registration) support is version-dependent, and some releases mishandle the PKCE code verifier (`No code verifier saved for session`). If its OAuth flow fails, use the bearer-token form above. ### Create a Personal Access Token A Personal Access Token (PAT) is the simplest way to authenticate a custom client, and — unlike an OAuth connection — it lets you choose exactly which scopes to grant. 1. In Roam, open **User Settings > Developer**. 2. Click **Create Personal Access Token**. 3. Give it a descriptive name (e.g. "MCP Inspector"). 4. Select the scopes you need. The [Tool Reference](#tool-reference) lists the scope each tool requires — for example, `chat:history` for `chat_history`, `calendar:write` for `calendar_event_create`, or `onair:read` for the OnAir read tools. Grant only what your integration uses. 5. Click **Create Token** and copy it (it starts with `rmp-…`). ![Personal Access Token creation dialog with scopes](/img/mcp/personal-access-token-creation.png) ### Testing with MCP Inspector The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser-based tool for testing MCP servers. Use it to verify your connection and explore available tools. 1. Launch the inspector: ```bash npx @modelcontextprotocol/inspector ``` 2. In the inspector UI: - Set **Transport Type** to **Streamable HTTP**. - Set **URL** to `https://api.ro.am/mcp`. - Under **Request Headers**, add: - Header name: `Authorization` - Header value: `Bearer YOUR_PERSONAL_ACCESS_TOKEN` - Click **Connect**. ![MCP Inspector configured with Roam server URL and Authorization header](/img/mcp/mcp-inspector-connect.png) 3. Once connected, click the **Tools** tab to see all available tools. Click any tool to view its input schema and try it out. 4. Click the **Prompts** tab to see built-in prompts like `morning_brief` and `weekly_digest`. ## Troubleshooting | Symptom | Likely cause | Fix | | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_client` / "Client authentication failed" at token exchange | A public client omitted PKCE, or a confidential client sent its secret in a way the endpoint didn't read | Public clients: register with `token_endpoint_auth_method: none` and use PKCE (`S256`). Confidential clients: send the secret via `client_secret_post` or HTTP Basic. | | Browser says authentication completed, but the client still shows "not logged in" | The browser callback succeeded but the background token exchange failed | Check the token-endpoint auth method and that the `resource` parameter is `https://api.ro.am/mcp`. | | `code_challenge is required` or `code_challenge_method must be S256` | A public client started the flow without S256 PKCE | Send `code_challenge` with `code_challenge_method=S256`. Public clients must use S256; `plain` is rejected. | | A tool is listed but returns `403` when called | Your token lacks that tool's scope | Use a token that includes the scope (see the [Tool Reference](#tool-reference)). Default OAuth connections already include the full [default scope set](#scopes--permissions); narrow Personal Access Tokens may not. | | MCP endpoint returns `401` with `no bearer token` | Expected unauthenticated response | Follow the `WWW-Authenticate` header to the protected-resource metadata, then send a bearer token in the `Authorization` header. | | `No code verifier saved for session` (with `mcp-remote`) | PKCE-state bug in some `mcp-remote` releases | Use the bearer-token form (`--header "Authorization: Bearer …"`) or upgrade `mcp-remote`. | ## Tool Reference Roam's MCP server exposes the tools below, grouped by category. Each tool requires the listed OAuth **scope**. Remember that a default OAuth connection (Claude, ChatGPT, Codex, or Grok) is granted only the [default scope set](#scopes--permissions) — tools whose scope falls outside it require a Personal Access Token until per-connection scope selection ships. ### User & Token | Tool | Description | Scope | | -------------------------- | -------------------------------------------------------------------------------------- | ------------------------- | | `token_info` | Get info about the current token (client, user, org, scopes, expiration) | — | | `get_me` | Get the authenticated user's profile (name, image, email, status) | — | | `user_info` | Resolve a member, guest, or automated principal by ID (or a workspace member by email) | `user:read` | | `user_list` | List active workspace members, or hydrate up to 100 principals with `ids` | `user:read` | | `user_status_bubble_get` | Get the live thought bubble shown over a user's assigned office seats | `user:read.statusBubble` | | `user_status_bubble_set` | Set or replace a user's thought bubble | `user:write.statusBubble` | | `user_status_bubble_clear` | Clear a user's thought bubble | `user:write.statusBubble` | `user_info` returns required `type: "user" | "bot"` and is available to Personal connections. `user_list` without `ids` remains the member directory; pass one comma-separated `ids` value to hydrate message/webhook actor IDs in request order. See [Identity & Principals](/docs/guides/identity-and-principals). Status-bubble tools accept a user ID or workspace member email. Personal connections may target only their owner; organization connections may target any active workspace member. OAuth MCP connections created before these tools shipped must be removed and reconnected to receive the new default scopes if a call returns a missing-scope error. ### Chat | Tool | Description | Scope | | ------------------- | ---------------------------------------------------------------------------------------- | ------------------- | | `chat_list` | List conversations (DMs, channels, team Roam, meeting channels) | `chat:read` | | `chat_history` | Read messages from a chat or thread, including sender `userType` | `chat:history` | | `chat_post` | Post a message to a chat, channel, or thread | `chat:send_message` | | `chat_update` | Update a bot-posted message | `chat:send_message` | | `chat_delete` | Delete a bot-posted message (destructive) | `chat:send_message` | | `chat_search` | Full-text search across chats, with sender/date/attachment filters and sender `userType` | `chat:history` | | `search` | Simplified search alias (ChatGPT compatibility — accepts only `query`) | `chat:history` | | `resolve_chat_link` | Resolve a Roam chat link URL to its chat/thread IDs | `chat:history` | | `create_chat_link` | Create a shareable Roam link to a chat message | `chat:history` | ### Reactions | Tool | Description | Scope | | ----------------- | --------------------------------------- | ------------------- | | `reaction_add` | Add an emoji reaction to a message | `chat:send_message` | | `reaction_remove` | Remove an emoji reaction from a message | `chat:send_message` | | `reaction_list` | List emoji reactions on a message | `chat:history` | ### Groups | Tool | Description | Scope | | ------------ | -------------------------------------------------- | ------------ | | `group_info` | Get a group/channel's info by ID or name | `group:read` | | `group_list` | List groups/channels, with search and type filters | `group:read` | | `group_join` | Join a public group as the calling identity | `group:write` | ### Meetings | Tool | Description | Scope | | ---------------------- | ------------------------------------------------------------------ | ------------------- | | `meeting_list` | List meetings, with optional summary/action-item/chapter expansion | `meetings:read` | | `meeting_info` | Get details about a specific meeting | `meetings:read` | | `meeting_participants` | List a meeting's participants | `meetings:read` | | `meeting_transcript` | Get a meeting transcript (VTT) | `meetings:read` | | `meeting_search` | Search meetings by keywords or natural language | `meetings:read` | | `meeting_prompt` | Ask an AI question about a meeting's transcript | `meetings:read` | | `meeting_link_create` | Create a meeting link | `meetinglink:write` | | `meeting_link_info` | Get details about a meeting link | `meetinglink:read` | | `meeting_link_update` | Update a meeting link | `meetinglink:write` | ### Calendar | Tool | Description | Scope | | ----------------------- | ---------------------------------------------------------------- | ---------------- | | `calendar_list` | List scheduled events from connected calendars (Google, Outlook) | `calendar:read` | | `calendar_event_create` | Create a calendar event with a Roam meeting link | `calendar:write` | ### OnAir | Tool | Description | Scope | | ----------------------- | ------------------------------------------ | ------------- | | `onair_event_list` | List OnAir broadcast events | `onair:read` | | `onair_event_info` | Get details about an OnAir event | `onair:read` | | `onair_event_create` | Create an OnAir event | `onair:write` | | `onair_event_update` | Update an OnAir event | `onair:write` | | `onair_event_cancel` | Cancel an OnAir event | `onair:write` | | `onair_guest_list` | List an OnAir event's guests | `onair:read` | | `onair_guest_info` | Get details about an OnAir guest | `onair:read` | | `onair_guest_add` | Add guests to an OnAir event | `onair:write` | | `onair_guest_update` | Update an OnAir guest | `onair:write` | | `onair_guest_remove` | Remove a guest from an OnAir event | `onair:write` | | `onair_attendance_list` | List attendance records for an OnAir event | `onair:read` | ### Magicast | Tool | Description | Scope | | --------------- | ---------------------------------- | --------------- | | `magicast_list` | List Magicasts (metadata only) | `magicast:read` | | `magicast_info` | Get Magicast details, transcript, and video | `magicast:read` | | `magicast_share_link` | Get or create a shareable player URL | `magicast:read` | ### Folders | Tool | Description | Scope | | ------------------------ | --------------------------------------------------------- | --------------- | | `folder_list` | List folders of meetings and Magicasts | `folders:read` | | `folder_info` | Get a folder's name, item count, and your role | `folders:read` | | `folder_contents` | List meetings and Magicasts filed in a folder | `folders:read` | | `folder_members` | List a folder's members and their roles | `folders:read` | | `folder_create` | Create a folder | `folders:write` | | `folder_rename` | Rename a folder | `folders:write` | | `folder_delete` | Delete a folder (destructive) | `folders:write` | | `folder_add_contents` | File meetings and Magicasts into a folder | `folders:write` | | `folder_remove_contents` | Remove meetings and Magicasts from a folder (destructive) | `folders:write` | | `folder_add_members` | Add members or change their roles (destructive) | `folders:write` | | `folder_remove_members` | Remove members (destructive) | `folders:write` | Personal connections see folders the user belongs to, with that person's role (`admin` or `viewer`), and need the `admin` role to change one. A folder the user creates makes them its `admin`. `folder_contents` returns item metadata; `meeting_transcript`, `meeting_prompt`, and `magicast_info` are the follow-ups for the full item, and those tools need their own scopes. Folder members can read every item filed in the folder through those tools. `folder_add_members` is marked destructive because it can demote an `admin` to `viewer`. OAuth connections created before these tools shipped must be removed and reconnected if a call returns a missing-scope error for `folders:read` or `folders:write`. ### Lobbies | Tool | Description | Scope | | -------------------- | ------------------------- | ------------ | | `lobby_list` | List configured lobbies | `lobby:read` | | `lobby_booking_list` | List bookings for a lobby | `lobby:read` | ### Webhooks | Tool | Description | Scope | | --------------------- | ------------------------------------ | --------------- | | `webhook_subscribe` | Subscribe to webhook events at a URL | `webhook:write` | | `webhook_unsubscribe` | Unsubscribe from a webhook | `webhook:write` | ## Prompts Built-in **prompts** provide ready-made workflows. In Claude, add them from the **+** menu (see [Using Prompts](#using-prompts)). Some prompts take an argument. | Prompt | Description | | ------------------- | ------------------------------------------------------------------------------------ | | `action_item_radar` | Action items by urgency and ownership, highlighting carry-over and at-risk work | | `meeting_prep` | A concise prep brief for your next meeting | | `morning_brief` | Yesterday's meetings and action items, today's schedule, and recent chat activity | | `chat_recap` | Recent activity across your conversations, highlighting items needing a response | | `group_digest` | Activity summary for a specific group _(argument: `group`)_ | | `decision_log` | Decisions from recent meetings: what, when, and by whom | | `project_status` | Status report for a specific project, from meetings and chat _(argument: `project`)_ | | `weekly_digest` | Comprehensive weekly summary with key decisions and action items | :::note ChatGPT does not support MCP prompts. Use the tools directly by asking questions in natural language. :::