Using the MCP server

Once the MCP server is wired into your client (see the setup guide), your AI agent gets eight tools to drive Raconte: four for interviews and four 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 eight tools at a glance

Interview side:

• list-interviews: browse the interviews of the organization, most recent first.
• 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:

• list-invitations: browse invitations and their summaries, across the organization or within one interview.
• 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/i/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 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/i/K9pQ2mWxYz", "sent": true, "error": null },
    { "slug": "M3nB7vCxQa", "status": "ready", "name": "Marc", "url": "https://raconte.ai/i/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 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 email to a new value re-sends the invitation to it (the result then carries sent/error).

Example 6, find an existing interview

“List my last three interviews.”

The agent calls list-interviews with limit: 3. The results come back most recent first, each with an excerpt of the prompt and its invitation counts, so the agent can pick the one you mean and follow up with get-interview:

{
  "total": 26,
  "limit": 3,
  "offset": 0,
  "hasMore": true,
  "interviews": [
    { "id": "12345678-...", "title": "Beta feedback", "promptExcerpt": "Ask people what they liked...", "invitationsCount": 12, "completedCount": 7 }
  ]
}

Both list tools take a search string (title and prompt for interviews; recipient, summary and interview title for invitations) and page with limit and offset, total and hasMore telling the agent whether to fetch the next page. To sweep the answers of a whole organization without knowing the interview ids, list-invitations alone does it: every row carries its interviewTitle and its AI summary.

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. If you lost them, list-interviews and list-invitations find them back.
• 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.