MCP Server

The Gaffer MCP server (@gaffer-sh/mcp) connects AI coding assistants to your test history. Ask about test health, investigate flaky tests, and get context about failures without leaving your editor.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants access external tools and data sources. By installing the Gaffer MCP server, your AI assistant gains direct access to your test analytics.

Features

Test health insights - Ask about pass rates, trends, and overall test suite health
Flaky test detection - Identify tests with inconsistent behavior
Test history lookup - Check the history of specific tests to understand stability
Cross-project access - Query all your projects from a single API key
Report file access - Get links to HTML reports, coverage files, and other artifacts
Slowest test analysis - Find tests that are slowing down your CI pipeline

Prerequisites

A Gaffer account with test results uploaded
An API Key from Account Settings > API Keys

Setup

Claude Code

Add to your Claude Code settings (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

What tools does the Gaffer MCP server expose?

Three. The server runs in code mode: rather than one MCP tool per API call, it exposes three tools plus a codemode namespace of 16 analytics functions that you call from JavaScript. That keeps 16 tool definitions out of the context window, and it lets one execution chain several calls instead of paying a round-trip each.

MCP tool	What it does
`execute_code`	Runs JavaScript against `codemode.<function>()`. Max 20 API calls, 30s timeout.
`search_tools`	Finds available functions by keyword. An empty query lists all of them.
`list_projects`	Lists projects. Registered only when your token is a user API Key (`gaf_`).

You rarely write this code yourself. You ask a question, and the assistant writes the call:

const health = await codemode.get_project_health({ projectId: "proj_abc" });
if (health.flakyTestCount > 0) {
  const flaky = await codemode.get_flaky_tests({ projectId: "proj_abc" });
  return { health, flaky };
}
return { health };

Which functions can the assistant call?

All 16 are reachable through execute_code. Ask search_tools with an empty query to list them at runtime.

Function	Category	Returns
`get_project_health`	health	Health score (0-100), pass rate, run count, flaky count, trend
`get_test_history`	testing	Pass/fail history for one test, with branch, commit, and errors
`get_flaky_tests`	testing	Flip rates, transition counts, and last-seen timestamps
`list_test_runs`	testing	Recent runs, filterable by commit, branch, or status
`get_test_run_details`	testing	Individual results for one run, with stack traces
`get_failure_clusters`	testing	Failed tests grouped by error similarity
`get_slowest_tests`	testing	Slowest tests by average and P95 duration
`compare_test_metrics`	testing	Before/after metrics across two commits or runs
`search_failures`	testing	Past failures matching an error or test-name pattern
`get_coverage_summary`	coverage	Line, branch, and function coverage, plus trend
`get_coverage_for_file`	coverage	Coverage for an exact or partial file path
`get_untested_files`	coverage	Files below a coverage threshold
`find_uncovered_failure_areas`	coverage	Files with low coverage and test failures
`get_report`	reports	Report file URLs for a test run
`get_report_browser_url`	reports	Signed browser URL, valid 30 minutes
`get_upload_status`	uploads	Whether CI results are uploaded and processed

With a project token (gfr_), omit projectId on every function. It resolves automatically.

Example Prompts

Once the MCP server is connected, try asking your AI assistant:

“What projects do I have in Gaffer?”
“What’s the health of my test suite?”
“Which tests are flaky in my project?”
“Is the login test flaky? Check its history”
“What tests failed in the last commit?”
“Show me test runs on the main branch”
“Which tests are slowing down my CI pipeline?”
“Get the Playwright report for the latest test run”

Environment Variables

Variable	Required	Description
`GAFFER_API_KEY`	Yes	Your Gaffer API Key (starts with `gaf_`)
`GAFFER_API_URL`	No	API base URL (default: `https://app.gaffer.sh`)

Authentication

The MCP server uses User API Keys (gaf_ prefix) which provide read-only access to all projects across your organizations. Get your API Key from Account Settings > API Keys in the Gaffer dashboard.

Note: Project Tokens (gfr_ prefix) are designed for uploading test results from CI and only provide access to a single project. For the MCP server, use a User API Key instead.