Overview

Connect Recall.ai to an MCP-compatible AI client so your agent can investigate bots, inspect workspace data, search Recall.ai documentation, and help build or debug your integration.

What You Can Do

Use the Recall.ai MCP server to:

• Investigate why a bot failed to join, record, or produce a transcript.
• Inspect bot lifecycle events, participants, chat messages, and customer-visible logs.
• Trace calendar-created bots and diagnose calendar sync problems.
• Inspect webhook subscriptions, events, and delivery attempts.
• Find recordings, transcripts, and generated media artifacts.
• Check Recall.ai and third-party provider status incidents.
• Search Recall.ai guides and API reference pages
• Review billed usage, credit balances, and configured API rate limits.
• Optionally create or update webhook endpoints, send test webhooks, and submit rate-limit increase requests.

The MCP allows agents to view all the same data that a developer can, without being constrainted to what the API offers.

Quickstart

Find your coding agent below.

Claude Code

claude mcp add --scope user --transport http recall-ai https://us-east-1.recall.ai/mcp

You'll then want to login:

claude mcp login recall-ai

Codex

codex mcp add recall-ai --url https://us-east-1.recall.ai/mcp

Then complete the Recall.ai OAuth flow when prompted.

Cursor

Add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "recall-ai": {
      "url": "https://us-east-1.recall.ai/mcp"
    }
  }
}

Windsurf

Add the following to ~/.codeium/mcp_config.json:

{
  "mcpServers": {
    "recall-ai": {
      "serverUrl": "https://us-east-1.recall.ai/mcp"
    }
  }
}

Claude Desktop

1. Open Settings.
2. Open Connectors.
3. Add a custom connector.
4. Enter recall-ai as the connector name.
5. Enter https://us-east-1.recall.ai/mcp.
6. Connect and complete the Recall.ai OAuth flow.

3. Verify the Connection

Ask your agent:

Use Recall.ai's get_info tool and tell me the active workspace, organization, and API version. List all the tool calls that the recall-ai MCP supports.

Confirm that the response names the expected workspace before using workspace data or write tools.

Authentication and Workspace Access

Use OAuth when a person is connecting their own AI client. They sign in through the browser, and the connection can access the same Recall.ai billing accounts they can access.

Use a scoped MCP API key for an unattended or shared agent, or when another person should not receive all the access your OAuth connection has. Each key can be limited to one workspace and only the MCP capabilities that person or agent needs.

OAuth

OAuth grants the MCP server access to all billing accounts available to the signed-in user. The workspace selected during authorization becomes the default workspace, but the connection can access the user's other billing accounts and workspaces.

To work with a different workspace:

1. Use list_workspaces to find the desired workspace ID.
2. Pass that ID as workspace_id to workspace-scoped tools.

OAuth connections receive read access by default. Write tools require an explicit full or fine-grained write scope.

Scoped MCP API Keys

Create a separate key for each person or agent. This lets you restrict and revoke their access independently.

Create a Key

Create scoped keys from Dashboard → Developers → MCP API Keys in the workspace the agent should access:

1. Select New MCP API Key.
2. Give the key a descriptive name.
3. Choose full read access or specific read permissions.
4. Turn off full write access unless the agent needs a write tool.
5. If needed, grant only the relevant fine-grained write permission.
6. Create the key and copy it immediately to a secure secret store.

An MCP API key:

• Is restricted to the workspace in which it was created.
• Can call only tools allowed by its configured scopes.
• Cannot use the Recall.ai REST API.
• Does not expose tools for scopes it was not granted.
• Has immutable scopes. Revoke and replace the key to change its access.
• Remains active until revoked.

Do not paste an MCP API key into a prompt or commit it to source control.

Authenticate an Agent

Use the MCP endpoint for the region containing the key's workspace:

Configure the agent to send the key as a bearer token with every MCP request:

Authorization: Bearer <MCP_API_KEY>

Claude Code with an MCP API Key

claude mcp add --scope user --transport http recall-ai https://us-east-1.recall.ai/mcp \
  --header "Authorization: Bearer <MCP_API_KEY>"

Codex with an MCP API Key

Store the key in an environment variable:

export RECALL_MCP_API_KEY='<MCP_API_KEY>'

Add the following to ~/.codex/config.toml:

[mcp_servers.recall-ai]
url = "https://us-east-1.recall.ai/mcp"
bearer_token_env_var = "RECALL_MCP_API_KEY"

The MCP API Keys page provides ready-to-copy setup instructions for Cursor, VS Code, Windsurf, Claude Code, Claude Desktop, and Codex.

After connecting, run get_info and confirm that the agent can access only the intended workspace.

Permissions

Read Permissions

mcp.read grants access to every read tool available through MCP. For least-privilege agents, use fine-grained scopes instead:

Some tool results contain conditionally protected fields. For example, get_bot requires participant or chat scopes before it returns those fields.

Write Permissions

The server has no write access by default. mcp.write grants every write capability available through MCP. Prefer the fine-grained write scopes for autonomous or shared agents:

Write tools are not shown to credentials that lack the required scope. Your MCP client may also ask for confirmation before running a write tool.

Available Tools

The Recall.ai MCP server exposes read-only tools scoped to the workspace selected during authorization. If your account can access multiple workspaces, use list_workspaces to find the workspace ID and pass it as workspace_id to workspace-scoped tools.

Example Workflows

Investigate a Failed Bot

Prompt your agent:

Why did bot <BOT_ID> fail? Use its status changes and customer-visible logs, explain the causal chain, and link the relevant Recall.ai documentation.

The agent can use get_bot, get_bot_logs, search_docs, and get_doc. If the available evidence does not establish a cause, the response should say what is known and what evidence is still missing.

Trace a Missing Webhook

Prompt your agent:

Why did we not receive transcript.done for recording <RECORDING_ID>? Check our subscriptions and delivery attempts.

The agent can use list_webhook_endpoints and list_webhook_deliveries to distinguish a missing subscription from a failed delivery.

Trace a Calendar-Created Bot

Prompt your agent:

Which calendar event scheduled bot <BOT_ID>, and what was the calendar's connection state?

The agent can use get_bot_calendar_events and get_calendar.

Configure a Webhook

With mcp.webhooks.write, prompt your agent:

Create a webhook endpoint for recording.done at <WEBHOOK_URL>. Show me the proposed change and ask for confirmation before creating it.

The agent can use create_webhook_endpoint after you confirm the destination and event subscription.

Search Recall.ai Documentation

Prompt your agent:

Find the current Recall.ai documentation for creating a meeting bot and summarize the required request fields for this workspace's API version.

The agent can use search_docs followed by get_doc.