Getting started
- Claude Code
- Cursor
- Windsurf
- Codex
- VS Code
- Claude Desktop
Install the plugin from the official Claude plugins marketplace:Alternatively, you can add the MCP server directly:
Alternative: auto-detect with add-mcp
If your tool supports it, you can use
add-mcp to automatically detect
installed agents and configure them:
Example prompts
Once connected, you can ask your AI assistant questions like:- “Explain the regression on the
feat/my-great-featurebranch.” - “Make my
foo_barfunction faster.” - “What are the hottest functions in the
bench_foobenchmark?” - “Analyze the flamegraph for
bench_parseand refactor the hot path.” - “Compare the flamegraphs of
bench_serializebetweenmainandfeat/new-encoderand explain what changed.” - “Find the bottleneck in
bench_api_handlerand open a PR to fix it.”
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
Sample query & response
Query
Response
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
Sample query & response
Query
Response
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
Sample query & response
Query
Response
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
Sample query & response
Query
Response
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
Sample query & response
Query
Response
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
Sample query & response
Query
Response
Sample differential query & response
Sample differential query & response
Query
Response
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
Sample input & output
Input
Output
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, so there are no API keys to manage.The MCP server has access to the same repositories and data as your CodSpeed
account.