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

1. A Gaffer account with test results uploaded
2. 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"
      }
    }
  }
}

Available Tools

list_projects

List all projects you have access to.

• Input: organizationId (optional), limit (optional)
• Returns: List of projects with IDs, names, and organization info

get_project_health

Get health metrics for a project.

• Input: projectId (required), days (optional, default: 30)
• Returns: Health score (0-100), pass rate, test run count, flaky test count, trend direction

get_test_history

Get the pass/fail history for a specific test.

• Input: projectId (required), testName or filePath (one required), limit (optional)
• Returns: History of test runs with pass/fail status, duration, branch/commit info, error messages

get_flaky_tests

Get the list of flaky tests in a project.

• Input: projectId (required), threshold (optional), limit (optional), days (optional)
• Returns: List of flaky tests with flip rates, transition counts, and last seen timestamps

list_test_runs

List recent test runs with optional filtering.

• Input: projectId (required), commitSha (optional), branch (optional), status (optional), limit (optional)
• Returns: List of test runs with pass/fail/skip counts, commit info, pagination

get_report

Get the report files for a specific test run.

• Input: testRunId (required)
• Returns: List of files with filenames, sizes, content types, and download URLs

get_slowest_tests

Get the slowest tests in a project, sorted by P95 duration.

• Input: projectId (required), days (optional), limit (optional), framework (optional)
• Returns: List of slowest tests with average and P95 durations, run counts

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