Overview
The Roark MCP Server lets AI agents and coding assistants work with Roark through the Model Context Protocol (MCP). Once connected, your agent can look up agents, calls, transcripts and metric scores, set up personas and customer flows, and run simulations, all within your existing workflow. The MCP server pairs with Roark’s Agent Skills, which teach an agent how to choose the right Roark resources and compose them into a complete testing workflow. The MCP provides the API access; the skills provide the workflow. For Claude Code, the Roark plugin installs both together.Connect
Add this URL to your MCP client:- Claude Code
- Claude
- Cursor
- VS Code
- Other Clients
The recommended setup installs the Roark MCP server and its workflow skills together. Run Claude Code and enter:If you only want the MCP server without the workflow skills, add it from your terminal:
Tools
The server gives your agent one tool per task:- Read: list projects, agents, agent endpoints, calls, personas, customer flows, environments and metric definitions; get a call, its transcript and its metric scores; get the results of a simulation run.
- Set up and run: create agents, phone endpoints, personas and customer flows, and start simulations.
- Docs: search the Roark documentation.
Choosing a project
An unpinned connector URL carries no project, so the agent picks one per request. This is the one to use when the work spans projects:Run the server locally
You can also run the server on your own machine with an API key. Run this way, it exposes two tools instead of the ones above: documentation search, and code execution, where the agent writes and runs code against the Roark TypeScript SDK. Code execution reaches every operation in the Roark API, including ones the hosted tools do not cover, such as creating calls from recordings and running metric collection jobs. You need Node.js v20 or higher and a Roark API key. Add the server to any client that uses a JSON configuration:Without a project, calls made by a user credential fail with
400 and a message naming the header
to send. That is the signal to call client.project.list() and pick one, not a transient error to
retry.Pairing with Agent Skills
The MCP server gives your agent the tools to reach the Roark API. It does not tell the agent which testing template fits a goal, which metrics to attach, or how to avoid accidentally placing hundreds of calls. That is what Roark’s Agent Skills are for, and the two are designed to be used together. There are 15 skills covering the full workflow: registering an agent, authoring personas and flows, assembling run plans, configuring metrics, reading results, monitoring production traffic, and gating CI. Installing theroark plugin in Claude Code brings the MCP server and all of them at once. Other agents install the skills with a single command:
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. This needs the locally run server.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. This needs the locally run server.
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
GitHub Repository
Browse the source code and open an issue
Agent Skills
Teach your agent the Roark testing workflow
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