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

### 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 v18 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">
    Run the following command in your terminal:

    ```bash theme={null}
    claude mcp add roark --env ROARK_API_BEARER_TOKEN="your-api-key" -- npx -y @roarkanalytics/sdk-mcp
    ```

    Replace `your-api-key` with your actual Roark API key.
  </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={null}
    {
      "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={null}
    {
      "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={null}
    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={null}
    {
      "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>

### 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 evaluations on a call">
    *"Run all evaluators on call `a1b2c3d4-5678-9abc-def0-123456789abc` and summarize the results."*

    The agent will create an evaluation job, wait for it to complete, and present the evaluation results.
  </Accordion>

  <Accordion title="Create and evaluate a call in one go">
    *"Create a call from this recording URL and run the greeting-quality and task-completion evaluators on it: [https://example.com/recording.mp3](https://example.com/recording.mp3)"*

    The agent will create the call record, trigger evaluations, and return the results once they're ready.
  </Accordion>

  <Accordion title="Review evaluation scores across calls">
    *"Show me the evaluation results for my last 5 calls — which ones scored lowest on task-completion?"*

    The agent will fetch recent calls, pull their evaluation runs, and rank them by score.
  </Accordion>

  <Accordion title="List available evaluators">
    *"What evaluators do I have configured in Roark?"*

    The agent will retrieve your evaluator 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' scenario."*

    The agent will look up your personas and scenarios, 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="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>