Skip to main content

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:
The first time your agent uses it, your client opens a browser window to sign in with your Roark account and choose what the agent may do. Roark then creates an API key for that connection, listed on your API keys page, where you can revoke it at any time.
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.
Starting a simulation places real, billable calls, so review what the agent is about to run before you approve that tool call.

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:
A pinned connector URL carries the project in the path, and every request acts on that project. The dashboard’s API keys page generates it for you:
On an unpinned connector, the agent finds the projects it can use with the list projects tool and names one on each request.

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:
In Claude Code, the same server is:
With a user credential rather than a project key, code the agent writes names the project through the client:
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 the roark plugin in Claude Code brings the MCP server and all of them at once. Other agents install the skills with a single command:
Once installed, ask your agent for what you want and it selects the right skill:
See Agent Skills for the full list, the supported agents, and installation details.
Every simulated call is billable. Review the estimated call count before starting a run, especially when selecting multiple flow variants, personas, endpoints, or iterations.

Example Recipes

Once connected, you can interact with the Roark API conversationally. Here are some examples to get you started:
“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.
“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 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 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.
“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.
“What metrics do I have configured in Roark?”The agent will retrieve your metric definitions and list them with their descriptions and slugs.
“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