Overview
The Roark MCP Server lets AI agents and coding assistants interact with the Roark API through the Model Context Protocol (MCP). Once connected, your agent can create calls, run evaluations, search documentation, and execute code against the Roark TypeScript SDK — all within your existing workflow.How It Works
The MCP server exposes two tools to your agent:- Documentation Search — a tool for querying Roark API and SDK documentation directly from your agent.
- Code Execution — a tool where the agent writes and executes code against the Roark API in a sandboxed environment. Anything the code returns or prints is sent back to the agent as the tool result.
Prerequisites
Before you begin, ensure you have:- Node.js v18 or higher — Download Node.js
- A Roark API Key — Generate one here
- An MCP-compatible client (Claude Code, Cursor, VS Code, etc.)
Installation
Choose the setup method for your client:- Claude Code
- Cursor
- VS Code
- Other Clients
Run the following command in your terminal:Replace
your-api-key with your actual Roark API key.Example Recipes
Once connected, you can interact with the Roark API conversationally. Here are some examples to get you started:Investigate a specific call
Investigate a specific call
“Can you find out why call
d4e5f6a7-1234-5678-9abc-def012345678 failed?”The agent will fetch the call details, check its status, and surface any errors or issues from the analysis.Aggregate call metrics
Aggregate call metrics
“What was the average duration of the last 10 calls we received on Roark?”The agent will list recent calls, extract their durations, and compute the average for you.
Run metrics on a call
Run metrics on a call
“Run a metric collection job on call
a1b2c3d4-5678-9abc-def0-123456789abc and summarize the results.”The agent will create a metric collection job, wait for it to complete, and present the metric values.Create and measure a call in one go
Create and measure a call in one go
“Create a call from this recording URL and collect the greeting-quality and task-completion metrics on it: https://example.com/recording.mp3”The agent will create the call record, trigger metric collection, and return the results once they’re ready.
Review metric results across calls
Review metric results across calls
“Show me the metric results for my last 5 calls — which ones scored lowest on task-completion?”The agent will fetch recent calls, pull their metric values, and rank them by score.
List available metrics
List available metrics
“What metrics do I have configured in Roark?”The agent will retrieve your metric definitions and list them with their descriptions and slugs.
Kick off a simulation
Kick off a simulation
“Start a simulation run using my ‘angry-customer’ persona against the ‘appointment-booking’ customer flow.”The agent will look up your personas and customer flows, then create a simulation job.
Additional Resources
NPM Package
View package details on npm
Node.js SDK
Learn about the underlying TypeScript SDK
API Reference
Explore the full API documentation
MCP Specification
Learn more about the Model Context Protocol