---
title: "Using the MCP server | Raconte"
description: "Concrete examples to create interviews, invite participants and read transcripts from your AI agent."
url: "https://raconte.ai/en/guides/mcp-usage"
---

# Using the MCP server

Concrete examples to create interviews, invite participants and read transcripts from your AI agent.

Once the MCP server is wired into your client (see the [setup guide](/en/guides/mcp-setup)), 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](/en/docs/mcp) 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](mailto:jane@example.com).”

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

```json
{
  "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](mailto:jane@example.com)), Marc ([marc@example.com](mailto: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:

```json
{
  "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.

**ℹ️ The summary lands after a short delay**

The summary and sentiments are produced right after the call ends. If you read a transcript within seconds of the hang-up, expect `summary: null` until the insights pass finishes.

## 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`:

```json
{
  "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

```mermaid
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](/en/docs/mcp).
