Skip to main content

​
MCP Server

Replay exposes an MCP (Model Context Protocol) server that lets AI agents interact with your Replay workspace. Use it from Claude Desktop, Cursor, or any MCP-compatible client to list, view, and create roleplays through natural language.

​
Available Tools

ToolDescription
list_roleplaysList all roleplays in your workspace. Optionally filter by live/draft status.
get_roleplayGet detailed information about a specific roleplay including persona, scorecard, and configuration.
create_roleplayCreate a new roleplay with a title, customer persona, and scorecard. Supports referencing existing resources by ID or creating them inline.

​
Authentication

The MCP server uses OAuth 2.1 for authentication. When you connect an MCP client, it automatically:
  1. Discovers the OAuth server via /.well-known/oauth-protected-resource
  2. Redirects you to log in to your Replay account
  3. Shows a consent screen asking you to approve access
  4. Exchanges the authorization for an access token
All tool calls are scoped to your user and company — you can only access roleplays in your own workspace.

​
Connecting from Claude Desktop

  1. Open Claude Desktop
  2. Go to Settings → Connectors
  3. Click Add Custom Connector
  4. Enter:
    • Name: Replay
    • URL: https://app.replay.sale/mcp/mcp
  5. Click Save
The first time you use a Replay tool, Claude will open a browser window for you to log in and authorize access. Once connected, you can ask Claude things like:
  • “List my roleplays in Replay”
  • “Show me the details of my Cold Call roleplay”
  • “Create a new roleplay for objection handling practice”

​
Connecting from Cursor

  1. Open Cursor Settings (Cmd+, on macOS)
  2. Navigate to MCP in the sidebar
  3. Click Add new MCP server
  4. Enter:
    • Name: Replay
    • Type: URL (Server-Sent Events)
    • URL: https://app.replay.sale/mcp/mcp
  5. Click Save
Cursor will prompt you to authenticate when you first use a Replay tool.

​
Connecting from Claude Code

Run this command in your terminal: 
claude mcp add --transport http replay https://app.replay.sale/mcp/mcp
Or add it manually to your project’s .mcp.json: 
{
  "mcpServers": {
    "replay": {
      "type": "url",
      "url": "https://app.replay.sale/mcp/mcp"
    }
  }
}

​
Testing with MCP Inspector

MCP Inspector is a developer tool for testing MCP servers interactively. 
npx @modelcontextprotocol/inspector
When the Inspector opens in your browser:
  1. Set the URL to https://app.replay.sale/mcp/mcp
  2. Set Transport to Streamable HTTP
  3. Click Connect
  4. Complete the OAuth login flow when prompted
  5. Use the Tools tab to call list_roleplays, get_roleplay, or create_roleplay

​
Tool Reference

​
list_roleplays

Returns all roleplays in your workspace. Parameters:
ParameterTypeRequiredDescription
is_livebooleanNoFilter by live/draft status. Omit to return all.
Example response: 
[
  {
    "id": "82cf1b3c-e92b-404f-99f9-8ec9e26d06a0",
    "title": "Cold Call Practice",
    "isLive": true,
    "passingScore": 70,
    "customerPersona": {
      "id": "...",
      "name": "Sarah Chen"
    }
  }
]

​
get_roleplay

Get full details for a specific roleplay. Parameters:
ParameterTypeRequiredDescription
roleplay_idstring (UUID)YesID of the roleplay to retrieve.

​
create_roleplay

Create a new roleplay. You can reference existing personas and scorecards by ID, or create them inline. Parameters:
ParameterTypeRequiredDescription
titlestringYesTitle of the roleplay.
customer_personaobjectYes{ id: "..." } to reference existing, or { name, tts_provider, default_voice_id } to create inline.
scorecardobjectYes{ id: "..." } to reference existing, or { title, sections: [...] } to create inline.
passing_scorenumberNoMinimum passing score (0-100). Defaults to 70.
languagestringNoLanguage code: en, es, fr-CA, pt-BR, cs. Defaults to en.
instructionsstringNoInstructions for the AI persona during conversation.
objectivestringNoObjective description shown to the user.
Example — reference existing resources: 
{
  "title": "Objection Handling Practice",
  "customer_persona": { "id": "existing-persona-uuid" },
  "scorecard": { "id": "existing-scorecard-uuid" },
  "passing_score": 80
}
Example — create inline: 
{
  "title": "Discovery Call Practice",
  "customer_persona": {
    "name": "Alex Rivera",
    "tts_provider": "Cartesia",
    "default_voice_id": "voice-id-here"
  },
  "scorecard": {
    "title": "Discovery Scorecard",
    "sections": [
      {
        "title": "Opening",
        "criteria": [
          {
            "title": "Professional Introduction",
            "prompt": "Did the rep introduce themselves and their company clearly?",
            "criterion_type": "YesNoQuestion"
          }
        ]
      }
    ]
  }
}
Example response: 
{
  "roleplayId": "new-roleplay-uuid",
  "customerPersonaId": "new-or-existing-persona-uuid",
  "scorecardId": "new-or-existing-scorecard-uuid",
  "variables": []
}

​
Troubleshooting

Make sure your Replay account is active and you can log in at app.replay.sale. If you’re redirected back to the consent page repeatedly, try clearing your browser cookies for app.replay.sale and reconnecting.
Your access token may have expired. Disconnect and reconnect the MCP server in your client to trigger a fresh OAuth flow.
Verify the URL is exactly https://app.replay.sale/mcp/mcp (note the double /mcp). The first segment is the route path, the second is the MCP transport identifier.
Ensure customer_persona and scorecard are provided. When creating inline, tts_provider must be one of: Cartesia, Azure, OpenAI, ElevenLabs, Rime, Google, AzureCustomNeuralVoice. Scorecard sections need at least 1 criterion each (max 8), and at least 1 section (max 4).