---
title: "MCP server"
url: "https://raconte.ai/en/docs/mcp"
---

### Documentation

[Introduction](/en/docs)[Getting started](/en/docs/getting-started)[MCP server](/en/docs/mcp)[Webhooks](/en/docs/webhooks)[REST API](/en/docs/api)[CLI](/en/docs/cli)[SDK](/en/docs/sdk)[Agent skill](/en/docs/skill)

### Guides

[Configure the MCP server](/en/guides/mcp-setup)[Using the MCP server](/en/guides/mcp-usage)

[Raconte](/) ⟩ [Documentation](/en/docs)

# MCP server

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

Raconte exposes a [Model Context Protocol](https://modelcontextprotocol.io) 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](/en/guides/mcp-setup). 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](/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](/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.

Table of contents

[1\. Endpoint and authentication](#endpoint-and-authentication)[2\. create-interview](#create-interview)[3\. update-interview](#update-interview)[4\. get-interview](#get-interview)[5\. create-invitation](#create-invitation)[6\. update-invitation](#update-invitation)[7\. get-invitation](#get-invitation)[8\. Invitation lifecycle, in summary](#invitation-lifecycle-in-summary)