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

<ResponseField name="list_repositories">
  List all CodSpeed-enabled repositories that you have access to. Returns
  repository names, visibility, and descriptions.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    list_repositories({});
    ```

    ```json title="Response" theme={null}
    {
      "repositories": [
        {
          "repository": "CodSpeedHQ/codspeed",
          "visibility": "public",
          "description": "CodSpeed is the all-in-one performance testing toolkit. Optimize code performance and catch regressions early."
        },
        {
          "repository": "CodSpeedHQ/pytest-codspeed",
          "visibility": "public",
          "description": "A pytest plugin to create benchmarks"
        },
        {
          "repository": "CodSpeedHQ/codspeed-rust",
          "visibility": "public",
          "description": "Crates to benchmark your Rust code"
        }
      ]
    }
    ```
  </Accordion>
</ResponseField>

<ResponseField name="list_runs">
  List recent performance runs for a repository. Returns run IDs, commit hashes,
  status, event type, branch, and PR information.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    list_runs({ repository: "CodSpeedHQ/codspeed", limit: 5 });
    ```

    ```json title="Response" theme={null}
    {
      "runs": [
        {
          "id": "6a315367cef14236ed18cd7b",
          "commit": {
            "hash": "7c50010379a4cb2ff1f550e7e8c9790b4391bc8e",
            "message": "fix(valgrind): skip rustup-wrapped proxy in trace-children"
          },
          "date": "2026-06-16T13:45:11.844Z",
          "status": "completed",
          "event": "push",
          "branch": "main"
        },
        {
          "id": "6a315096823c2ab665d8a12b",
          "commit": {
            "hash": "707a61cf1ea55936a2405eabbeddf6b494c44757",
            "message": "fix(valgrind): skip rustup-wrapped proxy in trace-children"
          },
          "date": "2026-06-16T13:33:10.082Z",
          "status": "completed",
          "event": "pull_request",
          "branch": "cod-2850-codspeed-cli-fails-with-rustup-proxy-error",
          "pullRequest": {
            "number": 405,
            "title": "fix(valgrind): skip rustup-wrapped proxy in trace-children"
          }
        }
      ]
    }
    ```
  </Accordion>
</ResponseField>

<ResponseField name="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.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    get_run({
      repository: "CodSpeedHQ/codspeed",
      run_id: "6a315367cef14236ed18cd7b",
    });
    ```

    ```text title="Response" theme={null}
    ---
    repository: CodSpeedHQ/codspeed
    run_id: 6a315367cef14236ed18cd7b
    branch: main
    commit: 7c50010
    date: 2026-06-16T13:45:11.844Z
    ---

    ## Benchmarks (7 total)

    | Mode       | Benchmark Name          | Benchmark URI                                                            | Value    |
    | ---------- | ----------------------- | ------------------------------------------------------------------------ | -------- |
    | Memory     | `sleep 1`               | `exec_harness::sleep 1`                                                  | 15.6 KB  |
    | WallTime   | `sleep 1`               | `exec_harness::sleep 1`                                                  | 1 s      |
    | Simulation | `sleep 1`               | `exec_harness::sleep 1`                                                  | 126.4 µs |
    | Simulation | `write_events[10000]`   | `crates/runner-shared/benches/memtrack_writer.rs::write_events[10000]`   | 20 ms    |
    | Simulation | `write_events[100000]`  | `crates/runner-shared/benches/memtrack_writer.rs::write_events[100000]`  | 207.3 ms |
    | Simulation | `write_events[500000]`  | `crates/runner-shared/benches/memtrack_writer.rs::write_events[500000]`  | 1 s      |
    | Simulation | `write_events[1000000]` | `crates/runner-shared/benches/memtrack_writer.rs::write_events[1000000]` | 2.1 s    |
    ```
  </Accordion>
</ResponseField>

<ResponseField name="compare_runs">
  Compare two performance runs and return a markdown performance report. Shows
  benchmark-level comparisons including improvements, regressions, and new or
  missing benchmarks. When the two runs ran in different environments (CPU, OS,
  runtime version, linked libraries), an "Environment Differences" section is
  added first.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    compare_runs({
      repository: "CodSpeedHQ/pytest-codspeed",
      head_run_id: "6a19d91790da9981fdd07f33",
      base_run_id: "6a19cc7a6edb082bd37ca2d1",
    });
    ```

    ```text title="Response" theme={null}
    ---
    repository: CodSpeedHQ/pytest-codspeed
    head_run_id: 6a19d91790da9981fdd07f33
    head_commit: 7c66604
    base_run_id: 6a19cc7a6edb082bd37ca2d1
    base_commit: 5db906e
    impact: -0.011035181366613855
    ---

    ## Environment Differences

    > ⚠️ The head and base runs were executed in different environments. Performance
    > differences may be caused by environment changes rather than code changes.

    ### Hardware

    - **CPU**: `AMD EPYC 9V74 80-Core Processor` → `AMD EPYC 7763 64-Core Processor`

    _…additional environment differences omitted_

    ## Summary

    | Status          | Count |
    | --------------- | ----: |
    | ⚡ Improvements |    17 |
    | ❌ Regressions  |    20 |
    | ✅ Unchanged    |   252 |

    ## Benchmark Results

    | Status | Mode     | Benchmark Name                    | `BASE`  | `HEAD`   | Change  |
    | ------ | -------- | --------------------------------- | ------- | -------- | ------- |
    | ❌     | WallTime | `test_recursive_fibo_20`          | 5.3 ms  | 5.9 ms   | -10.48% |
    | ❌     | WallTime | `test_multiprocessing_map[10000]` | 98.1 ms | 108.2 ms | -9.38%  |
    | ❌     | WallTime | `test_color[graph0-3]`            | 31 µs   | 32.7 µs  | -5.16%  |
    | ⚡     | WallTime | `test_multiprocessing_map[1000]`  | 66.4 ms | 60.9 ms  | +9.08%  |
    | ⚡     | WallTime | `test_threadpool_map[10]`         | 2.5 ms  | 2.3 ms   | +5.54%  |
    | ⚡     | WallTime | `test_sudoku[initial_grid0]`      | 8.3 µs  | 7.9 µs   | +4.81%  |

    _…31 more changed benchmarks omitted_
    ```
  </Accordion>
</ResponseField>

<ResponseField name="get_benchmark_result">
  Retrieve the full structured result of a single benchmark in a performance
  run: the instrument metrics (wall-time distribution, simulated time breakdown,
  or memory allocation breakdown), known issues, and whether a flamegraph is
  available.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    get_benchmark_result({
      repository: "CodSpeedHQ/codspeed",
      run_id: "6a315367cef14236ed18cd7b",
      benchmark_name: "exec_harness::sleep 1",
      runner_mode: "WallTime",
    });
    ```

    ```json title="Response" theme={null}
    {
      "name": "sleep 1",
      "uri": "exec_harness::sleep 1",
      "runnerMode": "WallTime",
      "flamegraphAvailable": true,
      "issues": { "callgraphGenerationFailure": null },
      "walltime": {
        "minSeconds": 1.001428826,
        "lowerFenceSeconds": 1.001428826,
        "q1Seconds": 1.0014400695,
        "medianSeconds": 1.001462736,
        "q3Seconds": 1.001541066,
        "upperFenceSeconds": 1.001572194,
        "maxSeconds": 1.001572194,
        "meanSeconds": 1.0014850014,
        "stdevSeconds": 0.00005703226150872855,
        "totalTimeSeconds": 5.007425007,
        "rounds": 5,
        "iqrOutlierRounds": 0,
        "stdevOutlierRounds": 0,
        "iterPerRound": 1,
        "warmupIters": 0
      }
    }
    ```
  </Accordion>
</ResponseField>

<ResponseField name="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.

  <Accordion title="Sample query & response">
    ```js title="Query" theme={null}
    query_flamegraph({
      repository: "CodSpeedHQ/codspeed",
      run_id: "6a315367cef14236ed18cd7b",
      benchmark_name:
        "crates/runner-shared/benches/memtrack_writer.rs::write_events[1000000]",
      runner_mode: "Simulation",
    });
    ```

    ```text title="Response" theme={null}
    # Flame Graph Summary

    ---
    benchmark_name: write_events[1000000]
    runner_mode: Simulation
    benchmark_total_time: 2.1 s
    run_id: 6a315367cef14236ed18cd7b
    truncated: yes
    ---

    ## Top 10 expensive functions (by self time)

    | Function                                              | Origin     | Calls |         Self Time |        Total Time |
    | ----------------------------------------------------- | ---------- | ----: | ----------------: | ----------------: |
    | `ZSTD_compressBlock_fast_extDict_generic.constprop.0` | Unknown    |     2 | 468.5 ms (22.05%) | 572.8 ms (26.96%) |
    | `Unknown symbol (0x188a80)`                           | Unknown    |    12 | 244.8 ms (11.52%) | 244.8 ms (11.52%) |
    | `ZSTD_encodeSequences_bmi2`                           | Unknown    |     2 | 223.6 ms (10.52%) | 223.6 ms (10.52%) |
    | `ZSTD_compressBlock_fast`                             | Unknown    |     4 | 213.3 ms (10.04%) | 213.3 ms (10.04%) |
    | `ZSTD_compressStream`                                 | Unknown    |     2 |   97.9 ms (4.61%) |    1.3 s (60.07%) |
    | `rmp::encode::str::write_str` (src/encode/str.rs)     | rmp@0.8.15 |     1 |   93.3 ms (4.39%) |   213 ms (10.03%) |

    ## Most expensive calls (by total time)

    | Function                                                             | Origin          |       Self Time |     Total Time |
    | -------------------------------------------------------------------- | --------------- | --------------: | -------------: |
    | `runner_shared::artifacts::memtrack::MemtrackWriter<W>::write_event` | User code       | 32.5 ms (1.53%) | 2.1 s (99.80%) |
    | `rmp_serde::encode::MaybeUnknownLengthCompound<W,C>::end`            | rmp-serde@1.3.1 | 18.3 ms (0.86%) | 1.6 s (77.23%) |
    | `zstd::stream::zio::writer::Writer<W,D>::write`                      | zstd@0.13.3     | 30.8 ms (1.45%) | 1.4 s (64.57%) |

    _…call tree, per-function details, and remaining hot spots omitted_

    > Call tree filtered: showing up to 25 entries with ≥1.00% of root function
    > total time. Re-query with `root_function_name` set to a function of interest
    > for deeper exploration.
    ```
  </Accordion>
</ResponseField>

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