---
title: "Using the MCP server"
url: "https://raconte.ai/en/guides/mcp-usage"
---

### 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](/) ⟩ [Guides](/en/docs)

# 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](/guides/mcp-setup)), 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](/docs/mcp) 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](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:

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

**ℹ️ 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 `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](/docs/mcp).

Table of contents

[1\. The six tools at a glance](#the-six-tools-at-a-glance)[2\. How to phrase your requests](#how-to-phrase-your-requests)[3\. Example 1, create an interview and send it](#example-1-create-an-interview-and-send-it)[4\. Example 2, invite several participants](#example-2-invite-several-participants)[5\. Example 3, share a link without sending it](#example-3-share-a-link-without-sending-it)[6\. Example 4, read the transcripts](#example-4-read-the-transcripts)[7\. Example 5, update, cancel, archive](#example-5-update-cancel-archive)[8\. Invitation lifecycle](#invitation-lifecycle)[9\. Good practices](#good-practices)