Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Roam MCP server

Vendor MCP
Open markdown

The Roam MCP connector routes your AI agent's tool calls to Roam's own MCP server through Scalekit. Each user signs in to Roam once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 70 tools.

Tools
70
What they doRead · write · destructive
33 · 33 · 433 read33 write4 destructive
Users sign in with
OAuth app
Scalekit's or your own

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Roam MCP connection

    In AgentKit > Connections, create a Roam MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Roam MCP server, so you don't need to register an OAuth app.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'roammcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Roam MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'roammcp_get_me',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • roammcp_calendar_listList scheduled calendar events within a date range from the user's connected calendars (Google Calendar, Outlook).Read-only

    List calendar events

    List scheduled calendar events within a date range from the user's connected calendars (Google Calendar, Outlook). Returns upcoming meetings with times, attendees, and recurrence info. Note: returns scheduled events, not completed meeting transcripts — use meeting_list for transcripts.

    Inputs

    endDatestring
    End of the date range to list events for, as a YYYY-MM-DD date. Defaults to startDate plus 7 days.
    startDatestring
    Start of the date range to list events for, as a YYYY-MM-DD date. Defaults to today in the user's time zone.
  • roammcp_chat_historyRead messages from a specific chat conversation.Read-only

    Get chat history

    Read messages from a specific chat conversation. A chat target is required — provide exactly one of chatId, groupId, or userIds: - chatId: UUID of an existing conversation (from chat_list results) - groupId: UUID of a group (from group_list results) — reads the group's channel - userIds: UUID(s) of users — opens or creates a DM conversation When "after" is specified, returns messages in forward chronological order (oldest first). Otherwise, returns messages in reverse chronological order (newest first). Parameters: - chatId (optional): UUID of a chat conversation - groupId (optional): UUID of a group - userIds (optional): Array of user UUIDs for a DM - threadTimestamp (optional): Thread root RFC3339 datetime (from a prior message's `timestamp`) to read thread replies - before (optional): Only messages before this time (RFC3339) - after (optional): Only messages after this time (RFC3339) - ascending (optional): Sort ascending by time (true/false) - limit (optional): Max messages per page (max 200) - cursor (optional): Pagination cursor from a previous response Each returned message carries: - `timestamp` — RFC3339 send time (with microsecond precision). Pass back into chat_post, chat_update, chat_delete, reaction_* as-is. - `threadTimestamp` — RFC3339 thread root (only on replies / when replying to a thread). - `userId` — UUID of the sender (resolve via the response envelope's `addresses` map; see below). - `text` — canonical message text with Slack-syntax mention tokens: `<@uuid>` for principals (users and bots), `<!subteam^uuid>` for groups and channels, and `<!channel>` for the broadcast. Tokens are never rewritten by the server. - `mentions` — flat list of payloads referenced by mention tokens in `text`: bare address UUIDs (from both `<@uuid>` and `<!subteam^uuid>` tokens) and the literal `"all"` for `<!channel>`. Order-preserving and deduplicated. Always present when `text` contains mentions; use this to know what was mentioned without re-parsing the regex. The response envelope additionally carries an `addresses` map keyed by UUID — every sender and mention-target address referenced on this page, with display name, type (`user`/`bot`/`userGroup`/`standardGroup`/`meetingGroup`/`teamRoam`), and type-specific fields (e.g. `botCode`, `email`, `isGuest`). Use it to render display names: replace `<@<uuid>>` and `<!subteam^<uuid>>` in `text` with `@` + `addresses.<uuid>.displayName`, and `<!channel>` with `@all`. The map omits IDs the caller is not authorized to view (cross-roam bots, private cross-account groups, etc.) — render those as `@unknown`. To look up a message from a Roam chat link URL, use resolve_chat_link instead of parsing the URL yourself. To get a shareable link to a message, use create_chat_link instead of constructing the URL yourself.

    Inputs

    afterstring
    Only return messages sent after this RFC3339 timestamp. When set, results are returned oldest-first instead of newest-first.
    ascendingstring
    Whether to sort results ascending by time (oldest first), passed as the string "true" or "false". If omitted, results are newest-first unless after is set.
    beforestring
    Only return messages sent before this RFC3339 timestamp.
    chatIdstring
    The UUID of an existing chat conversation to read, from chat_list results. Provide exactly one of chatId, groupId, or userIds to identify the conversation.
    cursorstring
    Pagination cursor from a previous response, used to fetch the next page of messages.
    groupIdstring
    The UUID of a group/channel to read, from group_list results — reads that group's channel. Provide exactly one of chatId, groupId, or userIds.
    limitinteger
    Maximum number of messages to return per page (max 200).
    threadTimestampstring
    The RFC3339 timestamp of a thread's root message (from a prior message's timestamp field), to read that thread's replies instead of the main channel.
    userIdsarray
    One or more user UUIDs identifying a direct message conversation to read, opening or creating it if needed. Provide exactly one of chatId, groupId, or userIds.
  • roammcp_chat_listList your recent conversations (DMs and groups), sorted by most recent activity.Read-only

    List chats

    List your recent conversations (DMs and groups), sorted by most recent activity.

    Inputs

    cursorstring
    Pagination cursor from a previous response, used to fetch the next page of conversations.
    limitinteger
    Maximum number of conversations to return per page. Defaults to 10.default 10
  • roammcp_chat_scheduled_listList pending messages scheduled via chat_post's sendAt that have not been sent yet.Read-only

    List scheduled chat messages

    List pending messages scheduled via chat_post's sendAt that have not been sent yet. Only messages scheduled by this credential's bot identity are returned, ascending by sendAt. Supports an optional chatId filter, sendAt range filtering, and pagination.

    Inputs

    afterstring
    Only return messages scheduled to send after this RFC3339 timestamp.
    beforestring
    Only return messages scheduled to send before this RFC3339 timestamp.
    chatIdstring
    Only return scheduled messages targeting this chat UUID.
    cursorstring
    Pagination cursor from a previous response, used to fetch the next page of scheduled messages.
    limitinteger
    Maximum number of scheduled messages to return per page.
  • roammcp_conversation_listList conversations from the workspace's attendance/reporting log, with per-participant time-in-conversation detail.Read-only

    List conversations

    List conversations from the workspace's attendance/reporting log, with per-participant time-in-conversation detail. Supports date range filtering and pagination. WHEN TO USE THIS TOOL: - Use for attendance and usage questions: "who was in meetings yesterday", "how long did we spend in huddles last week", "which rooms get used". - Unlike meeting_list (which is transcript-oriented), conversation_list covers every conversation — including short huddles and calls without a transcript or recording — and reports how long each participant was present. - For meeting content (summaries, transcripts, action items), use meeting_list / meeting_info / meeting_transcript instead. WHAT IT RETURNS: - One entry per conversation: id, place, room, roomType, start/end times, and meetingLinkIds when the room was booked through a meeting link. - participants: each participant's name and total seconds in the conversation. Requires the user:read scope; emails additionally require user:read.email. ACCESS: - Org tokens list every conversation in the workspace (requires broad meeting access). - Personal tokens list only conversations the token owner participated in. A page may then contain fewer than `limit` matches (even zero) while more history remains — keep following nextCursor until it is empty. Parameters: - after (optional): RFC3339 datetime; only conversations after this time (switches results to ascending order) - before (optional): RFC3339 datetime; only conversations before this time - limit (optional): Max conversations per page (default 10, max 100) - cursor (optional): Pagination cursor from a previous response's nextCursor - expand (optional): Comma-separated extra fields. "ip" adds each participant's client IP address (org tokens only).

    Inputs

    afterstring
    RFC3339 datetime, conversations after this time. When ascending is omitted, this also sorts oldest-first.
    ascendingstring
    Sort oldest-first (true) or newest-first (false). Repeat on later pages. When omitted, after still sorts oldest-first.
    beforestring
    RFC3339 datetime, conversations before this time
    cursorstring
    Pagination cursor from a previous response
    expandstring
    Comma-separated extra fields: ip (participant IP addresses; org tokens only)
    limitinteger
    Results per page (default 10, max 100)
  • roammcp_get_meGet the authenticated user's identity: `id`, `name`, and (when the token has the `user:read.email` scope) `email`.Read-only

    Get my user info

    Get the authenticated user's identity: `id`, `name`, and (when the token has the `user:read.email` scope) `email`. This is a projection over `token.info` that returns only the user object — useful for quickly answering "who am I" without parsing the full token payload. For org tokens, returns the bot identity.

    Inputs

    This tool takes no inputs.

All 73 in Communication