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

### 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)

# Configure the MCP server

Connect Claude, Claude Code, Cursor, Opencode, and other MCP-compatible clients to create interviews, manage invitations, and pull transcripts.

Raconte exposes a [Model Context Protocol](https://modelcontextprotocol.io) server over Streamable HTTP. Any MCP-compatible client can drive the product with six tools: three for interviews (`create-interview`, `update-interview`, `get-interview`) and three for invitations (`create-invitation`, `update-invitation`, `get-invitation`).

This guide shows how to wire it up in the most common clients. For what each tool does and example workflows, see the [usage guide](/guides/mcp-usage) and the [MCP server reference](/docs/mcp).

## Before you start

You need:

1.  A Raconte account on an organization where you can create API keys.
2.  An API key. Go to **Settings → API keys**, create one, and copy it once (the full value is shown only at creation).
3.  The MCP endpoint URL. Production: `https://api.raconte.ai/api/mcp`. Replace with your own host if you self-host.

The client connects to the endpoint with your API key as a query string:

```
https://api.raconte.ai/api/mcp?api_key=YOUR_API_KEY
```

**⚠️ Treat the URL as a secret**

The API key sits in the URL. Anyone who can read your MCP config can send interviews and read transcripts on your behalf. Keep the key in a `.env` file and reference it from the config (the examples below do this), and keep config files out of any folder you publish or sync.

### Put the key in a .env

Most clients can expand a variable from your shell into the MCP config at startup, so the key can live in a `.env` file and never appear in the config itself.

1.  Put `RACONTE_API_KEY=...` in a `.env` file (or in your shell profile, or in a project `.envrc` loaded by direnv).
2.  Make sure the shell that launches the client exports it. With direnv that happens automatically; with a plain `.env`, source it (`set -a; source .env; set +a`) or wrap the command with a `dotenv` launcher.
3.  Reference the variable from the config using the syntax your client expects (each section below uses it).

Add `.env` to `.gitignore`. Only the variable name ends up in the config.

## Claude Desktop

Claude Desktop reads its config from `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.

Add an entry under `mcpServers`:

```
{
  "mcpServers": {
    "raconte": {
      "type": "streamable-http",
      "url": "https://api.raconte.ai/api/mcp?api_key=YOUR_API_KEY"
    }
  }
}
```

Restart Claude Desktop. The `raconte` tools appear in the tools picker.

**ℹ️ Claude Desktop has no env substitution for HTTP servers**

Claude Desktop does not expand env vars inside `mcpServers[*].url`. Either bridge through stdio with [`mcp-remote`](https://github.com/geelen/mcp-remote) (which supports `env`), or keep the URL with the key inline and rely on the macOS Keychain / Windows DPAPI by keeping the file out of any synced folder.

## Claude Code (CLI)

The fastest path is the `claude mcp add` command. From any directory:

```
claude mcp add --transport http raconte "https://api.raconte.ai/api/mcp?api_key=\${RACONTE_API_KEY}"
```

Use `--scope user` to make the server available across every project, or `--scope project` to commit a `.mcp.json` file at the repo root for the team.

You can also edit `~/.claude.json` (user scope) or `.mcp.json` (project scope) directly. Claude Code expands `${VAR}` from the parent shell:

```
{
  "mcpServers": {
    "raconte": {
      "type": "http",
      "url": "https://api.raconte.ai/api/mcp?api_key=${RACONTE_API_KEY}"
    }
  }
}
```

Then `claude mcp list` confirms the server is connected.

## Cursor

Cursor reads MCP from `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` at the project root. It expands `${env:VAR}`:

```
{
  "mcpServers": {
    "raconte": {
      "type": "streamable-http",
      "url": "https://api.raconte.ai/api/mcp?api_key=${env:RACONTE_API_KEY}"
    }
  }
}
```

Open **Settings → MCP & Integrations** to verify Cursor sees the server, then enable the tools you want the agent to call.

## Opencode

Opencode reads `~/.config/opencode/config.json` (or `opencode.json` at the project root). It uses `{env:VAR}` for interpolation:

```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "raconte": {
      "type": "remote",
      "url": "https://api.raconte.ai/api/mcp?api_key={env:RACONTE_API_KEY}",
      "enabled": true
    }
  }
}
```

Restart Opencode. The `raconte` tools become available to every model that supports tool use.

## VS Code (GitHub Copilot Chat)

VS Code 1.99+ supports MCP through `.vscode/mcp.json` per workspace, or `mcp.json` in your user profile. The cleanest pattern is a prompted, password-typed input that VS Code caches in its secret storage:

```
{
  "inputs": [
    {
      "id": "raconteApiKey",
      "type": "promptString",
      "description": "Raconte API key",
      "password": true
    }
  ],
  "servers": {
    "raconte": {
      "type": "http",
      "url": "https://api.raconte.ai/api/mcp?api_key=${input:raconteApiKey}"
    }
  }
}
```

`${env:RACONTE_API_KEY}` works too if you prefer the env-var form. Open the Copilot Chat panel, switch to **Agent** mode, and the `raconte` tools show up in the tool picker.

## Windsurf

In Windsurf, open **Settings → Cascade → MCP servers** or edit `~/.codeium/windsurf/mcp_config.json`. It supports `${env:VAR}` like Cursor:

```
{
  "mcpServers": {
    "raconte": {
      "serverUrl": "https://api.raconte.ai/api/mcp?api_key=${env:RACONTE_API_KEY}"
    }
  }
}
```

Save and reload. The tools appear in Cascade.

## Available tools

Once the server is connected, your client can call six tools, all scoped to the organization that owns the API key and all returning JSON:

*   `create-interview`, `update-interview`, `get-interview` to create, edit and read interviews.
*   `create-invitation`, `update-invitation`, `get-invitation` to invite participants and read their transcripts.

See the [usage guide](/guides/mcp-usage) for examples and end-to-end workflows, and the [MCP server reference](/docs/mcp) for the full parameter list of each tool.

## Troubleshooting

**ℹ️ The server connects but the tools don't show**

Most clients cache the tool list per session. Restart the client, or remove and re-add the server entry.

If a call returns an authentication error, the API key was likely revoked or never had access to the org. Generate a new one in **Settings → API keys** and update the variable.

If you self-host Raconte, replace `https://api.raconte.ai` with your own API host. The path stays `/api/mcp`.

Table of contents

[1\. Before you start](#before-you-start)[2\. Claude Desktop](#claude-desktop)[3\. Claude Code (CLI)](#claude-code-cli)[4\. Cursor](#cursor)[5\. Opencode](#opencode)[6\. VS Code (GitHub Copilot Chat)](#vs-code-github-copilot-chat)[7\. Windsurf](#windsurf)[8\. Available tools](#available-tools)[9\. Troubleshooting](#troubleshooting)