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.
For reviewing results, start with reporting-only mode. Your agent can retrieve evidence without being offered target-management tools. Prefer to ask inside Tesults? Open Ask about these results in Results or Supplemental; no MCP setup is needed for that feature.
The conversations above are illustrative. AI explanations suggest possible causes, not verified diagnoses. Check the returned results and history scope before making a release decision.
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.
Reporting-only mode
Set TESULTS_READ_ONLY=true in the server environment alongside TESULTS_API_TOKEN. This exposes only the seven reporting and insight tools listed below and blocks non-GET requests locally.
When this option is omitted or set to false, the server also exposes tesults_create_target, tesults_update_target, tesults_delete_target and tesults_regenerate_token. Existing configurations keep this behavior. Deleting a target removes its results; regenerating a token invalidates the old token.
This setting restricts this MCP server, not the underlying API token's permissions. Keep the token private and do not commit it to shared configuration files. Insight tools can generate and cache AI analysis on the server even in reporting-only mode, but do not change test results or targets.
Requests time out after 60 seconds and responses are limited to 10 MiB. For large result sets, request fewer runs or set cases=false for summaries. API failures are returned as tool errors, not successful answers. Update an older MCP installation and restart the client to use these options.
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 | Explain a specific run using up to 100 non-passing tests. Causes are hypotheses. Check truncation metadata and the underlying evidence. |
| tesults_get_flaky_tests | Find inconsistent interpreted results across up to 10 recent runs in the requested range, including pass/unknown changes. An empty list is not proof of long-term stability. |
| tesults_get_regressions | Compare the latest run with its immediately preceding run to identify new and continuing failures, not a longer historical baseline. |
| tesults_what_changed | Compare a specified run against its preceding run and return resolved, new and continuing failures. |
| tesults_explain_case | Get stability, trend, patterns and recommendations for a case hash from its recent history. This is not scoped to a selected historical run; check runs_analyzed. |
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",
"TESULTS_READ_ONLY": "true"
}
}
}
}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.
These examples enable reporting-only mode. Use --scope user for your projects, or --scope local for private configuration in the current project. See the Claude Code MCP documentation for shared project configuration and secret handling.
claude mcp add --scope user --env TESULTS_API_TOKEN=your-api-token TESULTS_READ_ONLY=true --transport stdio tesults -- npx -y tesults-mcp
claude mcp add --scope local --env TESULTS_API_TOKEN=your-api-token TESULTS_READ_ONLY=true --transport stdio tesults -- npx -y tesults-mcp
Once connected, Claude Code can use the seven reporting and insight tools within the configured scope. Ask it to list targets first, then ask about failures or changes for a specific target. Replace the placeholder token locally and keep it out of shared files and screenshots.
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",
"TESULTS_READ_ONLY": "true"
}
}
}
}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 |