Skip to main content
Testkube 2.14.0 is out! AI test creation, detailed error analysis, and much more! Read More

Testkube MCP Server

tip

Check out https://testkube.io/blog/building-ai-assisted-test-workflows-testkube-mcp-github-copilot for a complete example on AI-driven remediation using the Testkube MCP Server with Github and Vs-Code.

Overview​

The Testkube MCP Server brings Testkube's test orchestration capabilities directly into your development environment and AI-powered workflows, enabling AI assistants and runners to interact directly with your Testkube workflows, executions, and artifacts.

More specifically, it allows you and your AI agents to:

  • Execute and Monitor Test Workflows: Run workflows, check execution status, and retrieve results
  • Analyze Test Results: Access execution logs, artifacts, and failure details
  • Navigate Test History: Search through past executions and analyze trends
  • Create and Manage Test Resources: List workflows, view configurations, create workflows and access metadata
note

Model Context Protocol (MCP) is an open standard that enables AI assistants to connect with external systems and data sources.

tip

The MCP Server gives your runner access to Testkube. To also teach a runner how to use Testkube — discovering tests in a repository, authoring valid TestWorkflow YAML, diagnosing failed executions — install the Testkube Agent Skills. The two work well together.

tip

When used with agentic AI tools like GitHub Copilot with Claude Sonnet 4 in VS Code or Cursor, the Testkube MCP enables:

  • Multi-step Problem Solving: AI agents can run multiple tools in sequence to solve complex testing scenarios.
  • Automated Debugging: Runners can analyze failures, examine logs, and suggest fixes.
  • Intelligent Test Management: Automated workflow creation, execution, and result analysis.

Getting Started​

Choose the setup method that works best for you:

The easiest way to get started - Connect directly to the Testkube Control Plane without any local installation.

  • ✅ No installation required
  • ✅ OAuth authentication — just log in via browser, no API keys needed
  • ✅ Always available
  • ✅ Best for remote access and team collaboration
  • ✅ Works with Claude Code, VS Code, Cursor, and other MCP clients

Get Started with Hosted Endpoint →

2. Testkube CLI​

Run the MCP Server locally using the Testkube CLI for full control and local development.

  • 🔧 Full control over the MCP server process
  • 🔧 Best for local development
  • 🔧 Supports stdio and shttp transports
  • 🔧 Works with all MCP-compatible tools

Get Started with CLI →

3. Docker Container​

Run the MCP Server in a Docker container for containerized deployments.

  • 🐳 Container-friendly deployment
  • 🐳 Ideal for CI/CD pipelines
  • 🐳 Easy to integrate with existing Docker workflows
  • 🐳 Supports both stdio and shttp transports

Get Started with Docker →

Configuration Examples​

Once you've set up the Testkube MCP Server, configure your AI tools:

Available Tools​

The MCP server provides tools for comprehensive Testkube management:

Workflow Management​

  • list_workflows - List workflows with filtering
  • get_workflow - Get workflow details
  • get_workflow_definition - Get workflow YAML
  • get_workflow_metrics - Get workflow performance metrics
  • create_workflow - Create new workflow
  • update_workflow - Update existing workflow
  • run_workflow - Execute workflow

Workflow Template Management​

  • list_workflowtemplates - List all workflow templates with optional label filtering
  • get_workflowtemplate_definition - Get workflow template YAML definition
  • create_workflowtemplate - Create new workflow template
  • update_workflowtemplate - Update existing workflow template

Runner Management​

  • list_agents - List available runners for workflow execution targeting - Read More

Execution Management​

  • list_executions - List workflow executions
  • get_execution_info - Get execution details
  • get_workflow_execution_metrics - Get detailed resource consumption metrics for a specific execution
  • get_workflow_resource_history - Analyze resource consumption patterns across multiple executions (trends, outliers, statistics)
  • fetch_execution_logs - Get execution logs
  • lookup_execution_id - Resolve execution name to ID
  • wait_for_executions - Wait for executions to complete
  • abort_workflow_execution - Cancel running execution
  • update_execution_tags - Update tags on an execution (replace semantics)

Artifact Management​

  • list_artifacts - List execution artifacts
  • read_artifact - Read artifact content

Query Tools​

  • query_workflows - Query multiple workflow definitions using JSONPath expressions
  • query_executions - Query multiple execution records using JSONPath expressions

Schema Tools​

  • get_workflow_schema - Get the YAML schema for TestWorkflow definitions
  • get_execution_schema - Get the YAML schema for TestWorkflowExecution data

Insights Boards​

Create, view and update Insights boards. Boards belong to the organization rather than to one environment, and a report narrows itself to environments through its own filters.

  • list_boards - List the boards visible to you (shared and private)
  • get_board - Get a board with its reports and layout
  • create_board - Create an empty board, shared with the organization by default
  • update_board - Change a board's name, description, slug, visibility or layout
  • add_board_report - Add a Pass/Fail, Executions, Workflows or Time Series report
  • update_board_report - Change a report's name, description, kind or settings
  • remove_board_report - Remove a report from a board
  • delete_board - Delete a board and all of its reports
  • render_board - Return the numbers each report shows. By default every report uses its own environment filter, as in the Dashboard; set scope to environment to limit every report to the MCP session's environment. Relative ranges (a day, week, month or quarter) end at midnight in timeZone, an IANA name such as Europe/Berlin that defaults to UTC; the Dashboard ends them at midnight in your browser's time zone, so pass yours to get the same numbers
note

Board tools require a signed-in user. They work with the hosted MCP endpoint when you connect with your user account, and with the CLI after testkube login. They do not work with an API token, including an API token passed to the Docker container as TK_ACCESS_TOKEN.

Deleting a shared board requires the organization admin role, as it does in the Dashboard.

Changes to a board made through MCP never overwrite a change someone else made in the meantime. Each change is applied only to the version of the board the tool read. If the board changed first, for example because someone edited it in the Dashboard, the tool reads it again and reapplies your change on top, and it reports an error without changing anything if the board keeps changing. This needs a Control Plane that tracks board versions; with an older one, a change overwrites the board as it was read. Deleting a board is different: it removes the board and everything on it, including changes made since the tool read it, as deleting in the Dashboard does.

Utility Tools​

  • build_dashboard_url - Generate dashboard URLs
  • list_labels - List available labels
  • list_resource_groups - List resource groups

Example Prompts​

Once configured, you can interact with Testkube using natural language:

List my test workflows and their recent execution status
Help me debug my last failed workflow execution
Create a new test workflow for my Python API and run it
Show me test execution trends for the past week and identify failing patterns
Analyze the logs of execution "api-tests-123" and suggest fixes
Create an Insights board with the pass/fail ratio and average duration of my API workflows over the last month

Need Help?​

info

Don't hesitate to reach out to us on Slack if you run into any issues!