Gaffer — Claude Code MCP server: what it does, how to install
MCP server connecting AI assistants to Gaffer test history. It checks flaky tests, coverage gaps, and failure clusters directly during debugging.
claude mcp add --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> --transport stdio gaffer -- npx -y @gaffer-sh/mcpWhat Gaffer does
The server links your coding assistant to test analytics stored in Gaffer. It groups failures by root causes, isolates flaky checks with high flip rates, and flags files that combine low coverage with recent test breaks. Out of 17 available functions, 16 are strictly read-only; only upload_test_results writes data.
To save context space, the server runs in code mode. Rather than exposing dozens of standalone MCP tools, it provides just three: execute_code, search_tools, and list_projects. The assistant chains analytics calls inside a small JavaScript snippet under the codemode namespace. Each execution has a 30-second timeout and a cap of 20 API calls.
Without an active Gaffer account holding test results and a valid GAFFER_API_KEY, the server cannot retrieve anything. You also need a user key starting with gaf_ to inspect project lists.
What it helps with
- Identify flaky tests with frequent pass-fail flips
- Group test failures by root cause
- Find files combining poor test coverage with failures
- Compare test metrics between git commits
Example prompts for the agent
- Check our project test health and list the flakiest tests
- Compare test durations and pass rates between the last two commits
- Find untested files that also experienced recent test failures
How to install Gaffer
Platform CLI
claude mcp add --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> --transport stdio gaffer -- npx -y @gaffer-sh/mcpReplace <…> with your own values
Platform CLI
codex mcp add gaffer --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> -- npx -y @gaffer-sh/mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"gaffer": {
"command": "npx",
"args": [
"-y",
"@gaffer-sh/mcp"
],
"env": {
"GAFFER_API_KEY": "<GAFFER_API_KEY>",
"GAFFER_API_URL": "<GAFFER_API_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"gaffer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@gaffer-sh/mcp"
],
"env": {
"GAFFER_API_KEY": "<GAFFER_API_KEY>",
"GAFFER_API_URL": "<GAFFER_API_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GAFFER_API_KEY=<GAFFER_API_KEY> -e GAFFER_API_URL=<GAFFER_API_URL> gaffer npx -y @gaffer-sh/mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Gaffer
How to install Gaffer in Claude Code?
Run claude mcp add --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> --transport stdio gaffer -- npx -y @gaffer-sh/mcp in your terminal. Replace the placeholders with your Gaffer credentials.
What does Gaffer do?
It grants AI assistants visibility into your test history and test health. The model can inspect flaky checks, error trends, and test coverage before writing code.
How does code mode work in this server?
The server exports three tools instead of seventeen. The agent writes JavaScript that calls codemode functions in batches, adhering to a 30-second timeout and a limit of 20 calls per script.
