cpp-latency-mcp

Hybrid MCP server for C++ latency benchmarking.

• C++ benchmark targets built with Google Benchmark
• Python MCP SDK stdio server with tools:
  • list_targets
  • run_benchmark
  • compare_runs
• Optional controls:
  • enable_rdtsc via env toggle passed to benchmark process
  • Linux-only perf stat capture

MCP client setup (Claude Code and Codex)

Claude Code

Recommended (CLI-managed) setup:

claude mcp add --scope user cpp-latency -- /ABS/PATH/cpp-latency-mcp/.venv/bin/python -m cpp_latency_mcp.server --log-level info

• Remove --scope user to install for the current project only.
• Restart Claude Code after adding the server.
• Verify with claude mcp list.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.cpp_latency]
command = "/ABS/PATH/cpp-latency-mcp/.venv/bin/python"
args = ["-m", "cpp_latency_mcp.server", "--log-level", "info"]
startup_timeout_ms = 20_000

Restart Codex, then run /mcp and confirm cpp_latency is listed with tools.

Included benchmark suites

• sample_latency_bench: basic vector/memcpy latency checks with optional rdtsc.
• latency_patterns_bench: pattern-focused suite ported from imperial_hft style examples: cache warm/cold, prefetching, branch reduction, slowpath split, compile-time dispatch, constexpr lookup, inlining, loop unrolling, signed/unsigned comparison, mixed types, SIMD, atomic vs mutex.
• disruptor_queue_bench: lock-free SPSC ring buffer style benchmark compared with mutex+condition-variable queue baseline.

MCP usage

The server uses MCP SDK stdio transport (newline-delimited JSON-RPC messages).

list_targets

Arguments:

• binary_path (optional)
• project_path (optional)
• filter (optional benchmark regex filter)

Provide either binary_path or project_path.

run_benchmark

Arguments:

• binary_path (required)
• filter (optional)
• repetitions (optional)
• min_time_sec (optional)
• affinity (optional Linux CPU set, e.g. "0,1")
• enable_rdtsc (optional)
• perf_events (optional list of Linux perf events)

Results are stored in .latency-mcp/runs/<run_id>.json.

compare_runs

Arguments:

• baseline_run_id (required)
• candidate_run_id (required)
• metric (optional: p50_ns, p95_ns, mean_ns, min_ns, max_ns; default p95_ns)
• threshold_pct (optional regression threshold percentage; default 0.0)

Local Quickstart

cd cpp-latency-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[test]

# Build sample benchmark
cmake -S benchmarks -B benchmarks/build
cmake --build benchmarks/build -j

# Binaries produced:
# - sample_latency_bench
# - latency_patterns_bench
# - disruptor_queue_bench

# Run server
python -m cpp_latency_mcp.server

Repository layout

• benchmarks/: Sample Google Benchmark target + CMake build files
• python/cpp_latency_mcp/: MCP server and benchmark orchestration logic
• tools/mcp_cli.py: Local MCP CLI for smoke testing
• tests/: Unit, integration, and stdio e2e tests

Testing

pytest tests/unit
pytest tests/integration
pytest tests/e2e