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

# MCP Server

> Connect AI assistants to your CodSpeed performance data using the Model Context Protocol.

The CodSpeed MCP server gives AI-powered tools direct access to your performance
data — benchmark runs, comparisons, and flamegraphs — so you can investigate
regressions, explore profiling results, and review performance changes without
leaving your editor or chat interface.

The server follows the
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) specification
and is hosted by CodSpeed at

```
https://mcp.codspeed.io/mcp
```

## Getting started

<Tabs>
  <Tab title="Claude Code" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/claude.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=f60787f3ce3f0d36f7edc3b7edd49782" width="24" height="24" data-path="assets/icons/claude.svg">
    Install the plugin from the official Claude plugins marketplace:

    ```sh theme={null}
    /plugin install codspeed@claude-plugins-official
    ```

    <Tip>
      The plugin installs both the MCP server and [agent skills](/ai/skills)
      automatically.
    </Tip>

    Alternatively, you can add the MCP server directly:

    ```sh theme={null}
    claude mcp add --transport http CodSpeed https://mcp.codspeed.io/mcp
    ```
  </Tab>

  <Tab title="Cursor" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/cursor.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=fceb486527afd060782308259fbdec5a" width="24" height="24" data-path="assets/icons/cursor.svg">
    Add the following to your `.cursor/mcp.json` file:

    ```json title=".cursor/mcp.json" theme={null}
    {
      "mcpServers": {
        "CodSpeed": {
          "url": "https://mcp.codspeed.io/mcp"
        }
      }
    }
    ```

    Cursor will prompt you to authenticate with CodSpeed via OAuth on first use.
  </Tab>

  <Tab title="Windsurf" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/windsurf.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=6e03464bfadeb42abb3124858e9eb2e1" width="24" height="24" data-path="assets/icons/windsurf.svg">
    Add the following to your `~/.codeium/windsurf/mcp_config.json` file:

    ```json title="mcp_config.json" theme={null}
    {
      "mcpServers": {
        "CodSpeed": {
          "serverUrl": "https://mcp.codspeed.io/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/openai.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=c1b83fed6d8f4a3964a567ee764acfce" width="24" height="24" data-path="assets/icons/openai.svg">
    Add the CodSpeed MCP server and authenticate:

    ```sh theme={null}
    codex mcp add CodSpeed --url https://mcp.codspeed.io/mcp
    codex mcp login CodSpeed
    ```
  </Tab>

  <Tab title="VS Code" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/github-copilot.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=787581f1762690481f7cad06f78d4c75" width="24" height="24" data-path="assets/icons/github-copilot.svg">
    Add the following to your `.vscode/mcp.json` file:

    ```json title=".vscode/mcp.json" theme={null}
    {
      "servers": {
        "CodSpeed": {
          "type": "http",
          "url": "https://mcp.codspeed.io/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop" icon="https://mintcdn.com/codspeed/4PzkxvwqEer7fV5z/assets/icons/claude.svg?fit=max&auto=format&n=4PzkxvwqEer7fV5z&q=85&s=f60787f3ce3f0d36f7edc3b7edd49782" width="24" height="24" data-path="assets/icons/claude.svg">
    1. Open **Settings** → **MCP**.
    2. Click **Add MCP Server**.
    3. Enter the following:
       * **Name**: `CodSpeed`
       * **URL**: `https://mcp.codspeed.io/mcp`
    4. Save and authenticate with CodSpeed when prompted.
  </Tab>
</Tabs>

### Alternative: auto-detect with `add-mcp`

If your tool supports it, you can use
[`add-mcp`](https://github.com/neondatabase/add-mcp) to automatically detect
installed agents and configure them:

```sh theme={null}
npx add-mcp https://mcp.codspeed.io/mcp --name CodSpeed
```

## Example prompts

Once connected, you can ask your AI assistant questions like:

* "Explain the regression on the `feat/my-great-feature` branch."
* "Make my `foo_bar` function faster."
* "What are the hottest functions in the `bench_foo` benchmark?"
* "Analyze the flamegraph for `bench_parse` and refactor the hot path."
* "Compare the flamegraphs of `bench_serialize` between `main` and
  `feat/new-encoder` and explain what changed."
* "Find the bottleneck in `bench_api_handler` and open a PR to fix it."

<Tip>
  Because the MCP server runs inside coding agents, your assistant can
  cross-reference flamegraph hot spots with your actual source code — then
  suggest or apply optimizations directly.
</Tip>

## Available tools

The CodSpeed MCP server exposes five tools:

| Tool                | Description                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_repositories` | List all CodSpeed-enabled repositories that you have access to. Returns repository names, visibility, and descriptions.                                                      |
| `list_runs`         | List recent performance runs for a repository. Returns run IDs, commit hashes, status, event type, branch, and PR information.                                               |
| `get_run`           | Inspect a single performance run and its benchmark results. Shows benchmark names, identifiers, and values. Accepts a run ID, branch, or defaults to the latest run.         |
| `compare_runs`      | Compare two performance runs and return a markdown performance report. Shows benchmark-level comparisons including improvements, regressions, and new or missing benchmarks. |
| `query_flamegraph`  | Query and summarize a flame graph from a performance run. Returns hot spots (functions with highest self time), the call tree, and timing information for each function.     |

## Authentication

The CodSpeed MCP server uses **OAuth** for authentication. When you first
connect, your MCP client will open a browser window where you log in to CodSpeed
and authorize access. The client stores the resulting token and refreshes it
automatically — no API keys to manage.

<Note>
  The MCP server has access to the same repositories and data as your CodSpeed
  account.
</Note>