# 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 gives your AI assistant direct access to your meetings, transcripts, chat messages, and calendar — so you can ask questions like "What did we decide about pricing in last week's meeting?" and get answers grounded in your actual conversations.

## Personal vs. Org Connections

Roam supports two types of MCP connections:

| | Personal | Org |
|---|---|---|
| **Created by** | Individual users in **User Settings > Developer** | Admins in **Administration > Developer** |
| **Data access** | Scoped to the user's own meetings, chats, and calendar | Access to all meetings and public group chats |
| **Use case** | Connecting your own AI assistant | Building integrations that serve the whole team |
| **Required for** | `list_calendar_events` | — |

Most users will want a **Personal** connection to use with Claude or ChatGPT.

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

## What You Can Do

Roam's MCP server exposes **11 tools** and **5 prompts**:

| Category | Tools | Description |
|----------|-------|-------------|
| **Meetings** | `search_meetings`, `list_meetings`, `get_meeting`, `get_meeting_transcript` | Search recordings by content, list transcripts, get summaries and chapters |
| **Chat** | `search_chat_messages`, `list_chats`, `list_groups`, `list_chat_messages`, `send_chat_message` | Search messages, browse conversations, send messages |
| **People** | `list_users` | List and search active users in your workspace |
| **Calendar** | `list_calendar_events` | List upcoming events from connected Google Calendar or Outlook |

Built-in **prompts** provide ready-made workflows:

| Prompt | Description |
|--------|-------------|
| `morning_brief` | Summarize yesterday's meetings, action items, today's schedule, and recent chats |
| `weekly_digest` | Comprehensive weekly summary with key decisions and action items |
| `project_status` | Status report for a specific project based on meetings and chats |
| `action_item_radar` | Action items grouped by urgency and ownership |
| `decision_log` | Decisions from recent meetings: what, when, and by whom |

## Claude

[Claude](https://claude.ai) supports MCP natively through its Connectors feature. No token or manual configuration is needed — Claude handles authentication via OAuth.

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:

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)

## Custom MCP Clients

You can connect any MCP-compatible client to Roam's server.

**Server URL:** `https://api.ro.am/mcp`

**Authentication:** Bearer token in the `Authorization` header

### Create a Personal Access Token

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 (Chat Read, Chat Send, Meetings Read, User Read).
5. Click **Create Token** and copy it.

![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.

<!-- SCREENSHOT: mcp-inspector-tools.png
Show the MCP Inspector connected to Roam, with the Tools tab open displaying the list of tools (search_meetings, list_chats, etc.).
-->

4. Click the **Prompts** tab to see built-in prompts like `morning_brief` and `weekly_digest`.

<!-- SCREENSHOT: mcp-inspector-prompts.png
Show the MCP Inspector Prompts tab with the list of available prompts.
-->