Using the MCP server

Once the MCP server is wired into your client (see the setup guide), your AI agent gets six tools to drive Raconte: three for interviews and three for invitations. This guide shows how to use them day to day, with example requests phrased in plain language.

For the full parameter list of each tool, keep the MCP server reference handy.

The six tools at a glance

Interview side:

• create-interview: create an AI voice interview (and its first invitation).
• update-interview: edit an existing interview, or archive it.
• get-interview: fetch an interview with all its invitations and their transcripts.

Invitation side:

• create-invitation: add one or more invitations to an existing interview.
• update-invitation: edit an invitation, cancel it or archive it.
• get-invitation: fetch a single invitation with its full transcript.

How to phrase your requests

You talk to your agent in plain language; it picks the tool and fills in the parameters. The examples below give a typical phrasing and show what happens behind the scenes.

Example 1, create an interview and send it

“Create a product feedback interview in English that asks people what they liked, what held them back, and what they’d like to see next. Send it to jane@example.com.”

The agent calls create-interview with a prompt, a locale and an invitees entry for jane@example.com. An invitation is created for that invitee and sent right away:

{
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "invitations": [
    { "slug": "M3nB7vCxQa", "status": "ready", "name": "Jane", "url": "https://raconte.ai/invitation/M3nB7vCxQa", "sent": true, "error": null }
  ]
}

With no invitees, the agent creates a single shareable invitation (recipient null) and you get back its url in invitations to send yourself.

Example 2, invite several participants

“Invite these people to interview 12345678-1234-1234-1234-1234567890ab: Jane (jane@example.com), Marc (marc@example.com) and +1 555 010 0042.”

The agent calls create-invitation with the invitees array. Each invitee needs an email or a phone and is sent right away. The result reports per invitation whether delivery succeeded (sent) or why it failed (error), without blocking the others:

{
  "invitations": [
    { "slug": "K9pQ2mWxYz", "status": "ready", "name": "Jane", "url": "https://raconte.ai/invitation/K9pQ2mWxYz", "sent": true, "error": null },
    { "slug": "M3nB7vCxQa", "status": "ready", "name": "Marc", "url": "https://raconte.ai/invitation/M3nB7vCxQa", "sent": false, "error": "email: invalid address" }
  ]
}

Example 3, share a link without sending it

“Give me an invitation link for this interview, I’ll send it myself.”

Every interview already carries a shareable READY invitation: its url, returned by create-interview, drops into your own email, a QR code or a Slack channel. create-invitation, on the other hand, always sends as soon as an email or phone is provided.

Example 4, read the transcripts

“Show me the responses to interview 12345678-1234-1234-1234-1234567890ab.”

The agent calls get-interview, which returns the interview with its invitations and, for the completed ones, the full transcript (messages, role, sentiment) plus a summary. To read a single participant, get-invitation with the invitation id is enough.

Example 5, update, cancel, archive

“Bump this interview’s max duration to 15 minutes and rename it to ‘Beta feedback’.”

The agent calls update-interview; only the fields you mention change. The same tool archives an interview with archived: true (and restores it with false).

On the invitation side, update-invitation handles the lifecycle:

• status: "cancelled" disables a link that is still ready (and "ready" re-enables it).
• archived: true soft-deletes the invitation, false restores it.
• setting recipientEmail or recipientPhone to a new value re-sends the invitation to it (the result then carries sent/error).

Invitation lifecycle

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 --> [*]

Good practices

• One key, one organization. Every call runs against the API key’s organization. Interviews and invitations from other organizations are never returned.
• Work with ids. create-interview returns the interviewId and the created invitations (invitations[].id), create-invitation returns the created invitations: keep these ids to chain get-* and update-* calls later.
• Let the agent chain calls. A request like “create the interview, invite these ten people, then summarise the answers as they come in” maps naturally to create-interview → create-invitation → get-interview.

Need the detail of a parameter? It’s all in the MCP server reference.