MCP server

The Raconte MCP server: tools, parameters, and example payloads.

Raconte exposes a Model Context Protocol server over Streamable HTTP. Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Opencode, VS Code Copilot Chat, Windsurf) can drive the product through six tools: three on interviews, three on invitations.

Need the client configuration steps? Read the MCP setup guide. This page is the reference for the tools themselves.

Endpoint and authentication

The MCP endpoint is https://api.raconte.ai/api/mcp. Authentication uses an API key passed in the URL:

https://api.raconte.ai/api/mcp?api_key=YOUR_API_KEY

API keys are created from Settings → API in the app and scoped to one organization. The endpoint and a ready-to-paste client config are also available from Settings → MCP. Every tool call runs against that organization; resources from other orgs are never returned.

create-interview

Create an AI voice interview. Without invitees, a single shareable READY invitation is created (its url is the link to share manually). With invitees, one invitation is created per invitee instead (no empty placeholder), and each one with an email or phone is sent immediately. A delivery failure does not stop the others and is reported per invitation (sent/error). The response always returns the created invitations in invitations.

Parameter	Type	Required	Description
`prompt`	string	yes	The interview prompt describing what questions to ask
`locale`	enum	no	Interview language. Defaults to the organization default language when omitted
`title`	string	no	Optional custom title for the interview
`intro`	string	no	Optional intro message shown to the recipient
`firstMessage`	string	no	Optional first message the AI will say when starting the call
`invitees`	array	no	Invitees to create and send right away. Each item supports `name`, `email`, `phone` (email or phone required)

Response example without invitees: a single shareable invitation, recipient fields null and sent: false (nothing was sent):

{
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "invitations": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "slug": "K9pQ2mWxYz",
      "status": "ready",
      "name": null,
      "recipientEmail": null,
      "recipientPhone": null,
      "url": "https://raconte.ai/invitation/K9pQ2mWxYz",
      "sent": false,
      "error": null
    }
  ]
}

With invitees, invitations holds one entry per invitee instead, each with its name/recipientEmail/recipientPhone and its sent/error delivery outcome.

update-interview

Patch an interview definition. Only the provided fields are updated. Set archived: true to archive (or false to restore).

Parameter	Type	Required	Description
`interviewId`	uuid	yes	Interview UUID to update
`title`	string	no	New title
`prompt`	string	no	New prompt (min. 10 characters)
`intro`	string	no	New intro message shown to the invitee
`firstMessage`	string	no	New first message the AI says when starting the call
`locale`	enum	no	New interview language
`maxMinutes`	number	no	Maximum minutes per call. Silence is not counted.
`maxResponses`	number	no	Maximum number of guest messages before the interview stops
`disableOrgSystemPrompt`	boolean	no	When true, do not prepend the organization system prompt
`archived`	boolean	no	Archive (true) or restore (false) the interview

Response example:

{
  "id": "12345678-1234-1234-1234-1234567890ab",
  "title": "Beta feedback",
  "prompt": "Ask people what they liked...",
  "intro": "Thanks for taking two minutes!",
  "firstMessage": "Hi, thanks for taking this interview.",
  "locale": "en",
  "maxMinutes": 15,
  "maxResponses": 100,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T11:02:05.880Z"
}

get-interview

Retrieve one interview by id with all its invitations and their full transcripts.

Parameter	Type	Required	Description
`interviewId`	uuid	yes	Interview UUID to fetch

Response example:

{
  "id": "12345678-1234-1234-1234-1234567890ab",
  "title": "Beta feedback",
  "prompt": "Ask people what they liked...",
  "intro": "Thanks for taking two minutes!",
  "firstMessage": "Hi, thanks for taking this interview.",
  "locale": "en",
  "maxMinutes": 15,
  "maxResponses": 100,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T11:02:05.880Z",
  "invitations": [
    {
      "id": "abcdef12-3456-7890-abcd-ef1234567890",
      "interviewId": "12345678-1234-1234-1234-1234567890ab",
      "slug": "K9pQ2mWxYz",
      "status": "completed",
      "name": "Jane Doe",
      "recipientEmail": "jane@example.com",
      "recipientPhone": null,
      "summary": "The invitee loved the onboarding and struggles with export.",
      "archivedAt": null,
      "createdAt": "2026-05-29T10:14:22.123Z",
      "updatedAt": "2026-05-29T10:31:40.500Z",
      "url": "https://raconte.ai/invitation/K9pQ2mWxYz",
      "messages": [
        { "role": "assistant", "content": "Hi! What did you like best?", "sentiment": null, "createdAt": "2026-05-29T10:20:00.000Z" },
        { "role": "user", "content": "The onboarding was smooth.", "sentiment": "positive", "createdAt": "2026-05-29T10:20:30.000Z" }
      ]
    }
  ]
}

create-invitation

Create one or several invitations for an existing interview. Each invitee with an email or phone is sent right away by email or SMS. A delivery failure does not stop the others and is reported per invitation (sent/error).

Parameter	Type	Required	Description
`interviewId`	uuid	yes	Interview UUID to invite people to
`invitees`	array	yes	List of invitees. Each item supports `name`, `email`, `phone`. Each invitee needs an email or a phone

Response example:

{
  "invitations": [
    {
      "id": "abcdef12-...",
      "slug": "K9pQ2mWxYz",
      "status": "ready",
      "name": "Jane Doe",
      "recipientEmail": "jane@example.com",
      "recipientPhone": null,
      "url": "https://raconte.ai/invitation/K9pQ2mWxYz",
      "sent": true,
      "error": null
    }
  ]
}

update-invitation

Patch an invitation. Set status: "cancelled" to deactivate (or "ready" to reactivate) and archived: true to delete (soft delete; false restores it). Setting recipientEmail or recipientPhone to a new value re-sends the invitation to it; a delivery failure is reported (sent/error) without failing the update.

Parameter	Type	Required	Description
`invitationId`	uuid	yes	Invitation UUID to update
`name`	string	no	New invitee display name (`null` clears it)
`recipientEmail`	string	no	New invitee email (`null` clears it; a new value re-sends the invitation)
`recipientPhone`	string	no	New invitee phone (`null` clears it; a new value re-sends the invitation)
`status`	enum	no	`"cancelled"` deactivates a READY invitation; `"ready"` reactivates
`archived`	boolean	no	Archive (true) or restore (false) the invitation. Archive is soft.

Response example (the sent/error fields are present only when a recipient changed):

{
  "id": "abcdef12-3456-7890-abcd-ef1234567890",
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "slug": "K9pQ2mWxYz",
  "status": "ready",
  "name": "Jane Doe",
  "recipientEmail": "jane.new@example.com",
  "recipientPhone": null,
  "summary": null,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T12:00:00.000Z",
  "url": "https://raconte.ai/invitation/K9pQ2mWxYz",
  "sent": true,
  "error": null
}

get-invitation

Retrieve one invitation by id with its status and its full transcript (messages with role and sentiment).

Parameter	Type	Required	Description
`invitationId`	uuid	yes	Invitation UUID to fetch

Response example:

{
  "id": "abcdef12-3456-7890-abcd-ef1234567890",
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "slug": "K9pQ2mWxYz",
  "status": "completed",
  "name": "Jane Doe",
  "recipientEmail": "jane@example.com",
  "recipientPhone": null,
  "summary": "The invitee loved the onboarding and struggles with export.",
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T10:31:40.500Z",
  "url": "https://raconte.ai/invitation/K9pQ2mWxYz",
  "messages": [
    { "role": "assistant", "content": "Hi! What did you like best?", "sentiment": null, "createdAt": "2026-05-29T10:20:00.000Z" },
    { "role": "user", "content": "The onboarding was smooth.", "sentiment": "positive", "createdAt": "2026-05-29T10:20:30.000Z" }
  ]
}

Invitation lifecycle, in summary

stateDiagram-v2
    state "Archived (soft delete)" as ARCHIVED
    [*] --> READY: create-invitation
    READY --> IN_PROGRESS: send or open link
    IN_PROGRESS --> COMPLETED: last message then hang-up
    READY --> CANCELLED: status cancelled
    CANCELLED --> READY: status ready
    READY --> ARCHIVED: archived true
    ARCHIVED --> READY: archived false
    COMPLETED --> [*]

get-interview and get-invitation both include the transcript for COMPLETED invitations. The summary lands shortly after the call ends; if you read the transcript right at completion, expect summary: null for a few seconds.