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

https://mcp.codspeed.io/mcp

Getting started

Claude Code

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

Cursor

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.

Windsurf

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

mcp_config.json

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

Codex

Add the CodSpeed MCP server and authenticate:

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

VS Code

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

.vscode/mcp.json

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

Claude Desktop

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.

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_repositories

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_runs

List recent performance runs for a repository. Returns run IDs, commit hashes, status, event type, branch, and PR information.

Sample query & response

Query

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

Response

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

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.

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

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

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

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

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.

Sample query & response

Query

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

Response

{
  "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_flamegraph

Query and summarize a flame graph from a performance run. Returns hot spots (functions with highest self time), the call tree, the most expensive threads, and timing information for each function.

Use the optional filters object to narrow the flame graph: 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.

Sample query & response

Query

query_flamegraph({
  repository: "CodSpeedHQ/codspeed",
  run_id: "6a315367cef14236ed18cd7b",
  benchmark_uri:
    "crates/runner-shared/benches/memtrack_writer.rs::write_events[1000000]",
  runner_mode: "Simulation",
  filters: { tid: [12] },
});

Response

# Flame Graph Summary

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

## Selected Threads

| PID | TID | Process         | Thread |     Total Time |
| --: | --: | --------------- | ------ | -------------: |
|   1 |  12 | codspeed-runner | main   | 2.1 s (99.98%) |

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

list_threads

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 flame graph 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.