> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 work with Roark through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). 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](https://docs.roark.ai/documentation/sdks/skills.md), 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:

```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
https://mcp.roark.ai/mcp
```

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](https://docs.roark.ai/documentation/getting-started/api-keys.md) page, where you can revoke it at any time.

> [tab] Claude Code
>
> The recommended setup installs the Roark MCP server and its workflow skills together. Run Claude Code and enter:
>
> ```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
> /plugin marketplace add roarkhq/mcp-roark-analytics
> /plugin install roark@roark
> ```
>
> If you only want the MCP server without the workflow skills, add it from your terminal:
>
> ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
> claude mcp add --transport http roark https://mcp.roark.ai/mcp
> ```

> [tab] Claude
>
> In Claude, open **Settings > Connectors**, choose **Add custom connector**, and enter `https://mcp.roark.ai/mcp`.

> [tab] Cursor
>
> Add the following to your Cursor MCP configuration. You can find this file via **Cursor Settings > Tools & MCP > New MCP Server**.
>
> ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
> {
>   "mcpServers": {
>     "roark": {
>       "url": "https://mcp.roark.ai/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Add the following to your VS Code MCP configuration. Open it via **Command Palette > MCP: Open User Configuration**.
>
> ```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
> {
>   "servers": {
>     "roark": {
>       "type": "http",
>       "url": "https://mcp.roark.ai/mcp"
>     }
>   }
> }
> ```

> [tab] Other Clients
>
> Any client that supports remote MCP servers over HTTP can connect: add `https://mcp.roark.ai/mcp` as the server URL and sign in when prompted. A partial list of MCP clients is available at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients).

### 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:

```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
https://mcp.roark.ai/mcp
```

**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:

```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
https://mcp.roark.ai/mcp/<project-id>
```

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](https://docs.roark.ai/documentation/sdks/node-sdk.md). 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](https://docs.roark.ai/documentation/getting-started/api-keys.md). Add the server to any client that uses a JSON configuration:

```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
  "mcpServers": {
    "roark": {
      "command": "npx",
      "args": ["-y", "@roarkanalytics/sdk-mcp"],
      "env": {
        "ROARK_API_BEARER_TOKEN": "your-api-key"
      }
    }
  }
}
```

In Claude Code, the same server is:

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
claude mcp add roark --env ROARK_API_BEARER_TOKEN="your-api-key" -- npx -y @roarkanalytics/sdk-mcp
```

With a user credential rather than a project key, code the agent writes names the project through the client:

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
import Roark from '@roarkanalytics/sdk';

const client = new Roark();

// Which projects can this credential reach?
const { data } = await client.project.list();
console.log(data.projects.map((p) => `${p.name} ${p.id}`));

// Act on one of them.
const support = client.withOptions({ project: data.projects[0].id });
const calls = await support.call.list({ limit: 5 });
console.log(calls);
```

> [!NOTE]
>
> 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](https://docs.roark.ai/documentation/sdks/skills.md) 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:

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx skills add roarkhq/mcp-roark-analytics
```

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

```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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](https://docs.roark.ai/documentation/sdks/skills.md) for the full list, the supported agents, and installation details.

> [!WARNING]
>
> 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:

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](#run-the-server-locally).

> [accordion] 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](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](#run-the-server-locally).

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [NPM Package](https://www.npmjs.com/package/@roarkanalytics/sdk-mcp)
>
> View package details on npm

> [card] [GitHub Repository](https://github.com/roarkhq/mcp-roark-analytics)
>
> Browse the source code and open an issue

> [card] [Agent Skills](https://docs.roark.ai/documentation/sdks/skills.md)
>
> Teach your agent the Roark testing workflow

> [card] [Node.js SDK](https://docs.roark.ai/documentation/sdks/node-sdk.md)
>
> Learn about the underlying TypeScript SDK

> [card] [API Reference](https://docs.roark.ai/api-reference/introduction.md)
>
> Explore the full API documentation

> [card] [MCP Specification](https://modelcontextprotocol.io)
>
> Learn more about the Model Context Protocol


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.