Documentation
If you are just getting started with Tesults and have not submitted test results data to Tesults yet and cannot see any results data in the results view, read the integration documentation instead. Once that has been completed, you can use the Tesults API to retrieve results data to make decisions within your continuous integration and deployment pipelines.
MCP Server
The Tesults MCP server lets AI agents query your test results, detect flaky tests, identify regressions, and explain failures in plain English — without you having to copy logs, paste data, or write a single line of code to connect them.
Once configured, you can have conversations like these directly in Claude Desktop, Claude Code, or Cursor:
The MCP server uses the same API token as the Tesults REST API. No additional credentials are required.
InstallationConfiguration
Available tools
Claude Desktop
Claude Code
Cursor
Other MCP clients
Installation
The Tesults MCP server is distributed as an npm package. Install it globally or run it on demand using npx. Running via npx is the simplest approach and is used in all configuration examples on this page.
npm install -g tesults-mcp
When using npx in your MCP client configuration, the package is fetched and run automatically — no global install required.
Requirements
| Requirement | Details |
|---|---|
| Node.js | Version 18 or later |
| npm | Included with Node.js |
| API token | A Tesults API token. See the authentication documentation for details. |
| MCP client | Claude Desktop, Cursor, or any other MCP-compatible client |
Configuration
The Tesults MCP server requires one environment variable: TESULTS_API_TOKEN. This is the same API token used for the Tesults REST API. See the authentication documentation for how to obtain a token.
The token scopes access to a single project. All tools exposed by the MCP server operate within that project.
Environment variable
| Name | Value |
|---|---|
| TESULTS_API_TOKEN | Your Tesults API token. Retrieve this from the API token page in your Tesults project configuration. |
Available tools
The MCP server exposes the following tools to connected AI agents. Each tool maps directly to a Tesults API endpoint. The agent selects which tool to call based on the task at hand — no manual wiring required.
| Tool name | Description |
|---|---|
| tesults_get_targets | List all targets (test jobs) in the project. Returns target ids and names needed by other tools. |
| tesults_get_results | Get test results for a target. Supports filtering by build name or run id, pagination, and optional inclusion of persistent and analysis data. |
| tesults_explain_run | Get a plain-language explanation of a specific test run: summary, root cause, failure count, and key failure patterns. |
| tesults_get_flaky_tests | Get a list of tests that have shown inconsistent results (flaky behaviour) across recent runs, including failure rate and classification. |
| tesults_get_regressions | Identify tests that are new failures compared to a historical baseline. Distinguishes new regressions from continuing failures. |
| tesults_what_changed | Compare the latest run against the previous run and return resolved failures, new failures, and continuing failures. |
| tesults_explain_case | Get stability classification, trend, patterns, and recommendations for a specific test case identified by its hash. |
Claude Desktop
Add the Tesults MCP server to your Claude Desktop configuration file. The configuration file location depends on your operating system:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
After saving the configuration, restart Claude Desktop. Tesults tools will be available automatically in any conversation. You can ask questions like "Which tests are flaky in my API target?" or "What changed in the latest run for target ID 123456?" and Claude will call the appropriate tool.
claude_desktop_config.json
{
"mcpServers": {
"tesults": {
"command": "npx",
"args": ["-y", "tesults-mcp"],
"env": {
"TESULTS_API_TOKEN": "your-api-token"
}
}
}
}Replace your-api-token with your Tesults API token. If you already have other MCP servers configured, add the tesults entry alongside them.
Claude Code
Claude Code (the CLI) supports MCP servers and can be configured to use Tesults either globally across all projects or scoped to a specific project.
Use the claude mcp add command to register the Tesults MCP server. The --scope project flag adds it to the current project only; omit it to add globally.
claude mcp add tesults-mcp npx tesults-mcp -e TESULTS_API_TOKEN=your-api-token
claude mcp add tesults-mcp npx tesults-mcp --scope project -e TESULTS_API_TOKEN=your-api-token
Once added, Claude Code will have access to all Tesults tools in any session. You can ask questions like "Are there any flaky tests in target 123456?" directly in the terminal.
Useful commands
| Command | Description |
|---|---|
| claude mcp add tesults ... | Register the Tesults MCP server |
| claude mcp list | List all registered MCP servers |
| claude mcp remove tesults | Remove the Tesults MCP server |
| claude mcp get tesults | Show configuration details for the Tesults server |
Cursor
Add the Tesults MCP server to your Cursor MCP configuration. You can configure it globally (applies to all projects) or per-project.
- Global:
~/.cursor/mcp.json - Per-project:
.cursor/mcp.jsonin your project root
After saving the configuration, Cursor will detect the server automatically. In Agent mode, Cursor can call Tesults tools as part of any agentic task — for example, checking whether the latest test run is clean before suggesting a deployment.
mcp.json
{
"mcpServers": {
"tesults": {
"command": "npx",
"args": ["-y", "tesults-mcp"],
"env": {
"TESULTS_API_TOKEN": "your-api-token"
}
}
}
}Replace your-api-token with your Tesults API token.
Other MCP clients
Any MCP-compatible agent or tool can connect to the Tesults MCP server. The server uses the stdio transport, which is the standard transport supported by all major MCP clients.
Regardless of the client, the underlying configuration is always the same: run npx -y tesults-mcp as the server command and pass TESULTS_API_TOKEN as an environment variable. Refer to your client's documentation for where to place the configuration.
Generic stdio configuration
| Field | Value |
|---|---|
| transport | stdio |
| command | npx |
| args | -y tesults-mcp |
| env: TESULTS_API_TOKEN | Your Tesults API token |