> ## 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 interact with the Roark API through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). 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](/documentation/sdks/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](https://nodejs.org))
* A Roark API Key ([Generate one here](/documentation/getting-started/api-keys))
* An MCP-compatible client (Claude Code, Cursor, VS Code, etc.)

### Installation

Choose the setup method for your client:

<Tabs>
  <Tab title="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:

    ```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    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:

    ```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
    ```
  </Tab>

  <Tab title="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": {
          "command": "npx",
          "args": ["-y", "@roarkanalytics/sdk-mcp"],
          "env": {
            "ROARK_API_BEARER_TOKEN": "your-api-key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="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"}}
    {
      "mcpServers": {
        "roark": {
          "command": "npx",
          "args": ["-y", "@roarkanalytics/sdk-mcp"],
          "env": {
            "ROARK_API_BEARER_TOKEN": "your-api-key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other Clients">
    You can run the MCP server directly via `npx`:

    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    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:

    ```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"
          }
        }
      }
    }
    ```

    Consult your client's documentation for where to place this configuration. A partial list of MCP clients is available at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients).
  </Tab>
</Tabs>

### 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](/documentation/sdks/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:

```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](/documentation/sdks/skills) 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.
</Warning>

### Example Recipes

Once connected, you can interact with the Roark API conversationally. Here are some examples to get you started:

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Additional Resources

<CardGroup cols={2}>
  <Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@roarkanalytics/sdk-mcp">
    View package details on npm
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/roarkhq/mcp-roark-analytics">
    Browse the source code and open an issue
  </Card>

  <Card title="Agent Skills" icon="graduation-cap" href="/documentation/sdks/skills">
    Teach your agent the Roark testing workflow
  </Card>

  <Card title="Node.js SDK" icon="square-js" href="/documentation/sdks/node-sdk">
    Learn about the underlying TypeScript SDK
  </Card>

  <Card title="API Reference" icon="book-open" href="/api-reference/introduction">
    Explore the full API documentation
  </Card>

  <Card title="MCP Specification" icon="link" href="https://modelcontextprotocol.io">
    Learn more about the Model Context Protocol
  </Card>
</CardGroup>