MCP Server

Connect AI agents and coding assistants to the Roark API using the Model Context Protocol

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.

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.

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.

Using this approach, agents can perform complex API tasks deterministically and repeatably. All operations supported by the Roark REST API and SDKs are available through the MCP server.

Prerequisites

Before you begin, ensure you have:

• Node.js v20 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

The recommended setup installs the Roark MCP server and its workflow skills together. Set your API key in the environment that launches Claude Code, then run Claude Code and enter these commands:

export ROARK_API_BEARER_TOKEN="your-api-key"
/plugin marketplace add roarkhq/mcp-roark-analytics
/plugin install roark@roark

Set ROARK_API_BEARER_TOKEN before launching Claude Code. If Claude Code is already running, restart it after changing the variable.

If you only want the MCP server without the workflow skills, add it directly from your terminal:

claude mcp add roark --env ROARK_API_BEARER_TOKEN="your-api-key" -- npx -y @roarkanalytics/sdk-mcp

Cursor

Add the following to your Cursor MCP configuration. You can find this file via Cursor Settings > Tools & MCP > New MCP Server.

{
  "mcpServers": {
    "roark": {
      "command": "npx",
      "args": ["-y", "@roarkanalytics/sdk-mcp"],
      "env": {
        "ROARK_API_BEARER_TOKEN": "your-api-key"
      }
    }
  }
}

VS Code

Add the following to your VS Code MCP configuration. Open it via Command Palette > MCP: Open User Configuration.

{
  "mcpServers": {
    "roark": {
      "command": "npx",
      "args": ["-y", "@roarkanalytics/sdk-mcp"],
      "env": {
        "ROARK_API_BEARER_TOKEN": "your-api-key"
      }
    }
  }
}

Other Clients

You can run the MCP server directly via npx:

export ROARK_API_BEARER_TOKEN="your-api-key"
npx -y @roarkanalytics/sdk-mcp@latest

For any MCP-compatible client that uses a JSON configuration, use:

{
  "mcpServers": {
    "roark": {
      "command": "npx",
      "args": ["-y", "@roarkanalytics/sdk-mcp"],
      "env": {
        "ROARK_API_BEARER_TOKEN": "your-api-key"
      }
    }
  }
}

Consult your client’s documentation for where to place this configuration. A partial list of MCP clients is available at modelcontextprotocol.io.

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:

npx skills add roarkhq/mcp-roark-analytics

Once installed, ask your agent for what you want and it selects the right skill:

Set up a Roark simulation for my support agent. Register the agent, create a persona and customer flow, attach metrics, and show me the estimated call count before starting.

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:

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

“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 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 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

“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

“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

“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