MCP Server

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 (MCP) specification and is hosted by CodSpeed at

https://mcp.codspeed.io/mcp

Getting started

Install the plugin from the official Claude plugins marketplace:

/plugin install codspeed@claude-plugins-official

The plugin installs both the MCP server and agent skills automatically.

Alternatively, you can add the MCP server directly:

claude mcp add --transport http CodSpeed https://mcp.codspeed.io/mcp

Add the following to your .cursor/mcp.json file:

.cursor/mcp.json

{
  "mcpServers": {
    "CodSpeed": {
      "url": "https://mcp.codspeed.io/mcp"
    }
  }
}

Cursor will prompt you to authenticate with CodSpeed via OAuth on first use.

Add the following to your ~/.codeium/windsurf/mcp_config.json file:

mcp_config.json

{
  "mcpServers": {
    "CodSpeed": {
      "serverUrl": "https://mcp.codspeed.io/mcp"
    }
  }
}

Add the CodSpeed MCP server and authenticate:

codex mcp add CodSpeed --url https://mcp.codspeed.io/mcp
codex mcp login CodSpeed

Add the following to your .vscode/mcp.json file:

.vscode/mcp.json

{
  "servers": {
    "CodSpeed": {
      "type": "http",
      "url": "https://mcp.codspeed.io/mcp"
    }
  }
}

Open Settings → MCP.
Click Add MCP Server.
Enter the following:
- Name: CodSpeed
- URL: https://mcp.codspeed.io/mcp
Save and authenticate with CodSpeed when prompted.

Alternative: auto-detect with `add-mcp`

If your tool supports it, you can use add-mcp to automatically detect installed agents and configure them:

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

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.

Available tools

The CodSpeed MCP server exposes seven tools:

List all CodSpeed-enabled repositories that you have access to. Returns repository names, visibility, and descriptions.

Sample query & response

Query

list_repositories({});

Response

{
  "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"
    }
  ]
}

List recent performance runs for a repository. Returns run IDs, commit hashes, status, event type, branch, PR information, and a url to each run page in the CodSpeed app.

Sample query & response

Query

list_runs({ repository: "CodSpeedHQ/codspeed", limit: 5 });

Response

{
  "runs": [
    {
      "id": "6a315367cef14236ed18cd7b",
      "url": "https://app.codspeed.io/CodSpeedHQ/codspeed/runs/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",
      "url": "https://app.codspeed.io/CodSpeedHQ/codspeed/runs/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"
      }
    }
  ]
}

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. When the run has issues, an “Issues” section lists those recorded on the run and its parts, and a “Benchmark Issues” section those recorded on its benchmark results, each with the benchmarks it affects, before the benchmarks. The run_url field links to the run page in the CodSpeed app.

Sample query & response

Query

get_run({
  repository: "CodSpeedHQ/codspeed",
  run_id: "6a315367cef14236ed18cd7b",
});

Response

---
repository: CodSpeedHQ/codspeed
run_id: 6a315367cef14236ed18cd7b
branch: main
commit: 7c50010
date: 2026-06-16T13:45:11.844Z
run_url: https://app.codspeed.io/CodSpeedHQ/codspeed/runs/6a315367cef14236ed18cd7b
---

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

Compare two performance runs and return a markdown performance report. Shows benchmark-level comparisons including improvements, regressions, and new or missing benchmarks. When benchmarks with a significant change had their base and head measured on different hardware, in a different software environment (OS, runtime version, linked libraries), or with a different major version of their CodSpeed integration, a “Comparison Issues” section lists each kind of difference with these benchmarks. An “Environment Differences” section then details what changed, under “Hardware”, “Software / Toolchain” and “CodSpeed Integration”, with the benchmarks compared across it and how it affects each mode. The comparison_url field links to the comparison page in the CodSpeed app.

Sample query & response

Query

compare_runs({
  repository: "CodSpeedHQ/pytest-codspeed",
  head_run_id: "6a19d91790da9981fdd07f33",
  base_run_id: "6a19cc7a6edb082bd37ca2d1",
});

Response

---
repository: CodSpeedHQ/pytest-codspeed
head_run_id: 6a19d91790da9981fdd07f33
head_commit: 7c66604
base_run_id: 6a19cc7a6edb082bd37ca2d1
base_commit: 5db906e
impact: -0.011035181366613855
comparison_url: https://app.codspeed.io/CodSpeedHQ/pytest-codspeed/runs/compare/6a19cc7a6edb082bd37ca2d1..6a19d91790da9981fdd07f33
---

## Comparison Issues

- ⚠️ **37 benchmarks with a significant change ran on different hardware** (37): `tests/benchmarks/test_bench_fibo.py::test_recursive_fibo_20`, `tests/benchmarks/test_bench_misc.py::test_multiprocessing_map[10000]`, … Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.
  [Learn more about Macro Runners](https://codspeed.io/docs/features/macro-runners.md)

## Environment Differences

> ⚠️ The base and head runs did not run in identical environments. Each difference below lists **only** the benchmarks whose base and head ran across it, with an inline note on how that kind of difference affects each mode. A benchmark not listed under any difference was compared on matching runners and is unaffected.

### Hardware

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

**Affected benchmarks:**

- `tests/benchmarks/test_bench_fibo.py::test_recursive_fibo_20` (WallTime)
- `tests/benchmarks/test_bench_misc.py::test_multiprocessing_map[10000]` (WallTime)

_…additional affected benchmarks omitted_

**Why this affects WallTime benchmarks:** WallTime mode measures elapsed wall-clock time, which is directly sensitive to CPU speed, memory, and system load. A hardware or environment change can move it independently of any code change. Details: https://codspeed.io/docs/features/macro-runners.md

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

Retrieve the full structured result of a single benchmark in a performance run: the instrument metrics (walltime distribution, simulated time breakdown, or memory allocation breakdown), known issues, and whether a flamegraph is available. The url field opens the run page on this benchmark.

Sample query & response

Query

get_benchmark_result({
  repository: "CodSpeedHQ/codspeed",
  run_id: "6a315367cef14236ed18cd7b",
  benchmark_uri: "exec_harness::sleep 1",
  runner_mode: "WallTime",
});

Response

{
  "url": "https://app.codspeed.io/CodSpeedHQ/codspeed/runs/6a315367cef14236ed18cd7b?uri=exec_harness%3A%3Asleep%25201&runnerMode=WallTime",
  "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
  }
}

Query and summarize a flamegraph from a performance run. Returns hot spots (functions with highest self time), the call tree, the most expensive threads, and timing information for each hot spot. The flamegraph_url field opens the benchmark’s flamegraph in the CodSpeed app, without the filters.Root Function Details, at the top, gives the full stats of the root function (root_function_name, or the flamegraph root): the time breakdown (Simulation), hardware performance counters (walltime) or the average allocation size (memory). Re-root the flamegraph to get them for another function.Use the optional filters object to narrow the flamegraph: pid / tid restrict it to specific processes/threads (their intersection — use list_threads to discover the available PIDs/TIDs), and root_function_name re-roots it at a specific function for deeper exploration.Set base_run_id to compare run_id, the head run, with a base run, e.g. after compare_runs to find the functions behind a regression or an improvement. The response keeps the head flamegraph’s layout and adds the local change (of a function’s or call’s own total) and the global change (its impact on the benchmark total); positive values are improvements. Detail blocks show base → head values, and new / dropped mark what exists in one run only. Filters apply to both runs, with pid / tid taken from run_id, and flamegraph_url then opens the comparison. The base run needs a result in the same runner mode, measured by a compatible runner version.

Sample query & response

Query

query_flamegraph({
  repository: "astral-sh/uv",
  run_id: "6adf63bf21dc63cc0188471a",
  benchmark_uri:
    "crates/uv-bench/benches/uv_settings.rs::uv_settings::parse_build_dependency_settings::parse_build_dependency_settings",
  runner_mode: "WallTime",
});

Response

---
benchmark_name: parse_build_dependency_settings
runner_mode: WallTime
benchmark_total_time: 48.6 ms
run_id: 6adf63bf21dc63cc0188471a
flamegraph_url: https://app.codspeed.io/astral-sh/uv/runs/6adf63bf21dc63cc0188471a?uri=crates%2Fuv-bench%2Fbenches%2Fuv_settings.rs%3A%3Auv_settings%3A%3Aparse_build_dependency_settings%3A%3Aparse_build_dependency_settings&runnerMode=WallTime
truncated: yes
---

## Root Function Details

### `uv_settings::parse_build_dependency_settings::{closure#0}::{closure#0}`

```
origin: Unknown
file: /home/runner/work/uv/uv/crates/uv-bench/benches/uv_settings.rs
object: uv_settings
calls: 1
self time: < 1 ns (0.00%)
total time: 48.6 ms (100.00%)
total perf counters:
- cpu cycles: 207,199,559
- instructions: 624,618,544
```

**Callers:**
- (none)

**Callees:**
- `toml::de::from_str::<uv_settings::settings::Options>` (1 calls)

## Top 10 expensive functions (by self time)

| Function                                                                                            | Origin        |                  Calls |       Self Time |      Total Time |
| --------------------------------------------------------------------------------------------------- | ------------- | ---------------------: | --------------: | --------------: |
| `_memcpy_avx512_unaligned_erms` (./string/../sysdeps/x86_64/multiarch/memmove-vec-unaligned-erms.S) | Unknown       |                     40 | 6.5 ms (13.38%) | 6.5 ms (13.40%) |
| `core::ptr::write::<toml_parser::lexer::token::Token>` (library/core/src/ptr/mod.rs)                | Rust built-in |                      1 |   6 ms (12.26%) |   6 ms (12.26%) |
| `<core::option::Option<toml_parser::source::Raw>>::unwrap` (library/core/src/option.rs)             | Rust built-in | 6 [indirect recursive] |  3.8 ms (7.89%) |  3.4 ms (7.06%) |

## Most expensive calls (by total time)

| Function                                                                                                                                  | Origin                | Parent                                                                   |      Self Time |        Total Time |
| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------ | -------------: | ----------------: |
| `uv_settings::parse_build_dependency_settings::{closure#0}::{closure#0}` (/home/runner/work/uv/uv/crates/uv-bench/benches/uv_settings.rs) | Unknown               | —                                                                        | < 1 ns (0.00%) | 48.6 ms (100.00%) |
| `toml::de::from_str::<uv_settings::settings::Options>` (src/de/mod.rs) *(1 truncated child)*                                              | toml-1.1.6+spec@1.1.0 | `uv_settings::parse_build_dependency_settings::{closure#0}::{closure#0}` | < 1 ns (0.00%) | 48.6 ms (100.00%) |

_…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 `filters.root_function_name` set to a function of
> interest for deeper exploration.

Sample differential query & response

Query

query_flamegraph({
  repository: "reflex-dev/reflex",
  run_id: "68801be45dfe494497351d0c",
  base_run_id: "68801ba85dfe494497351d08",
  benchmark_uri:
    "tests/benchmarks/test_compilation.py::test_compile_stateful[_stateful_page]",
  runner_mode: "Simulation",
});

Response

# Differential Flamegraph Summary

---
benchmark_name: test_compile_stateful[_stateful_page]
runner_mode: Simulation
base_run_id: 68801ba85dfe494497351d08
head_run_id: 68801be45dfe494497351d0c
flamegraph_url: https://app.codspeed.io/reflex-dev/reflex/runs/compare/68801ba85dfe494497351d08..68801be45dfe494497351d0c?uri=tests%2Fbenchmarks%2Ftest_compilation.py%3A%3Atest_compile_stateful%255B_stateful_page%255D&runnerMode=Simulation
base_benchmark_total_time: 299.7 µs
head_benchmark_total_time: 297.7 µs
benchmark_change: +0.69%
truncated: yes
---

## Root Function Details

### `test_compile_stateful[_stateful_page]`

```
change: no change, local +0.69%, global +0.69%
self time: < 1 ns → < 1 ns (0.00%)
total time: 299.7 µs → 297.7 µs (100.00%)
total time breakdown:
- instructions: 179.5 µs → 179.1 µs (60.17%)
- caches: 12.2 µs → 12.2 µs (4.11%)
- memory: 108 µs → 106.3 µs (35.71%)
```

**Callers:**
- (none)

**Callees:**
- `Unknown symbol (0x48ce4a0)` (1 calls)
- `_PyEval_EvalFrameDefault.cold` (1 calls)
- `CPython internals` (1 calls)

## Top 10 expensive functions (by self time)

| Function                                                                                              | Origin    |                 Calls |       Self Time |         Total Time | Local Change | Global Change |
| ----------------------------------------------------------------------------------------------------- | --------- | --------------------: | --------------: | -----------------: | -----------: | ------------: |
| `Unknown symbol (0x48cb640)`                                                                          | Unknown   | 12 [indirect recursive] | 9.4 µs (3.15%) | 282.8 µs (95.00%) |       +0.75% |        +0.71% |
| `_compile_stateful_components.<locals>.get_shared_components_recursive` (reflex/compiler/compiler.py) | User code | 12 [indirect recursive] | 8.9 µs (3.01%) |  90.2 µs (30.30%) |       +0.95% |        +0.29% |
| `CPython internals`                                                                                   | Unknown   |                     1 | 8.4 µs (2.84%) |    8.4 µs (2.84%) |       -0.05% |            0% |

## Most expensive calls (by total time)

| Function                                                        | Origin    | Parent                                    |        Self Time |          Total Time | Local Change | Global Change |
| --------------------------------------------------------------- | --------- | ----------------------------------------- | ---------------: | ------------------: | -----------: | ------------: |
| `test_compile_stateful.<locals>.<lambda>`                       | User code | `Unknown symbol (0x48ce4a0)`              | 904.7 ns (0.30%) |  285.8 µs (96.02%) |       +0.72% |        +0.69% |
| `_compile_stateful_components` (reflex/compiler/compiler.py)    | User code | `Unknown symbol (0x48cb640)`              |  1.2 µs (0.41%)  |   66.5 µs (22.35%) |       +0.85% |        +0.19% |

_…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 `filters.root_function_name` set to a function of
> interest for deeper exploration.

List the processes and threads recorded for a benchmark, with each thread’s total execution time and its start offset from the beginning of the benchmark. Use it to discover the PIDs/TIDs available before narrowing a flamegraph with query_flamegraph’s filters. Returns an empty list for benchmarks recorded without per-thread data (e.g. single-threaded profiles).

Sample input & output

Input

{
  "repository": "CodSpeedHQ/codspeed",
  "run_id": "6a315367cef14236ed18cd7b",
  "benchmark_uri": "crates/runner-shared/benches/memtrack_writer.rs::write_events[1000000]",
  "runner_mode": "Simulation"
}

Output

{
  "processes": [
    {
      "id": 1,
      "name": "codspeed-runner",
      "totalTimeSeconds": 2.1,
      "startOffsetSeconds": 0,
      "threads": [
        {
          "id": 12,
          "name": "main",
          "totalTimeSeconds": 2.0995,
          "startOffsetSeconds": 0
        },
        {
          "id": 42,
          "name": "writer",
          "totalTimeSeconds": 0.0005,
          "startOffsetSeconds": 0.13
        }
      ]
    }
  ]
}

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.

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

Get Started

For Agents

Instruments

Integrations

Explore Features

Getting started

Alternative: auto-detect with `add-mcp`

Example prompts

Available tools

Authentication

​Getting started

​Alternative: auto-detect with add-mcp

​Example prompts

​Available tools

​Authentication

Getting started

Alternative: auto-detect with `add-mcp`

Example prompts

Available tools

Authentication