> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/mcp-server/overview.md).

# MCP Server Overview

Connect an MCP-compatible AI agent to ContextQA tools for test creation, execution, failure analysis, and self-healing through natural language.

{% hint style="info" %}
**Who is this for?** SDETs, developers, and DevOps engineers integrating ContextQA with AI coding assistants (Claude, Cursor) or CI/CD pipelines.
{% endhint %}

The ContextQA MCP Server exposes supported test-automation capabilities as MCP (Model Context Protocol) tools. An MCP-compatible AI agent — Claude, Cursor, VS Code Copilot, or a custom-built agent — can discover the tools available to its connection and use them to create tests, run executions, analyze failures, and manage supported workspace resources.

## Quick answer

The ContextQA MCP Server lets an authenticated, MCP-compatible AI client discover and call ContextQA testing tools. Depending on the connected server version and account, an agent can create or query tests, trigger executions, poll status, retrieve evidence, investigate failures, and manage supported workspace resources. The connected tool manifest is authoritative for exact names, parameters, and availability.

## What this page covers

{% hint style="success" %}
**Hosted MCP reference:** Use [mcp.contextqa.com/docs](https://mcp.contextqa.com/docs) for the current server URL, OAuth setup, supported clients, ready-to-use prompts, and troubleshooting. Your connected client's tool manifest is authoritative for the exact tools available to your account and server version.
{% endhint %}

This means you can describe what you want to test in plain English, and an AI agent orchestrates the entire workflow: generating the test case, executing it, monitoring results, diagnosing failures, pushing defect tickets, and even applying self-healing patches — without writing a single line of Playwright or Selenium code.

![MCP Server architecture diagram with AI clients connecting through MCP to manifest-discovered ContextQA tools and backend services](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-000483c8556f1dede790ee7c83c22ff215420a51%2Fmcp-architecture.svg?alt=media)

***

## What You Can Do

For complete generic-first tutorials, start with [testing with AI coding agents](/testing-with-ai-coding-agents/ai-agent-testing.md). The collection separates repository unit and integration tests from managed application checks, with client setup, Playwright examples, and an [export portability checklist](/testing-with-ai-coding-agents/export-and-portability.md).

**Create Tests from Any Source**

* Natural language task descriptions
* Jira and Azure DevOps tickets (reads acceptance criteria automatically)
* Figma design files (analyzes screens and UX flows)
* Excel and CSV files (migrates manual test libraries)
* Swagger / OpenAPI specifications (generates API contract tests)
* Video screen recordings (extracts user journeys from `.mp4` files)
* Requirements documents (plain text or structured specs)
* Code diffs from pull requests (generates targeted regression tests)
* n8n workflow definitions (maps automation nodes to test steps)
* Edge case generation (AI-inferred boundary and negative scenarios)

**Execute Tests on Any Platform**

* Browser-based UI tests (Chrome, Firefox, Safari, Edge)
* Mobile device tests (iOS and Android via device farm)
* Performance load tests
* Security DAST scans

**Analyze and Debug Failures**

* Poll execution status programmatically until completion
* Pull step-by-step results with per-step screenshots
* Retrieve full browser console logs and network HAR logs
* Access Playwright trace files for DOM-level debugging
* Run AI root cause analysis that explains failures in plain English

**Manage Defects and Self-Healing**

* Automatically push defect tickets to Jira or Azure DevOps
* Retrieve self-healing suggestions when element locators break
* Approve and apply healing patches programmatically

**Migrate and Export**

* Analyze existing Cypress, Playwright, or Selenium repositories
* Migrate test suites from those frameworks into ContextQA
* Export ContextQA tests back to Playwright TypeScript

***

## Tool capabilities by category

The table below is an orientation map, not a fixed inventory. Server versions and account permissions can change exact names and availability. Inspect the connected manifest before designing an automated workflow.

| Category                        | Example capabilities                                                    |
| ------------------------------- | ----------------------------------------------------------------------- |
| Test Case Management            | Create, read, update, delete, and query                                 |
| Execution & Results             | Execute, poll, retrieve results, and inspect step details               |
| Test Suites & Plans             | List, execute, monitor, and rerun                                       |
| Infrastructure & Config         | Environments, devices, concurrency, and UI elements                     |
| Test Data Profiles              | Parameterized data-profile management                                   |
| Test Generation                 | Requirements, tickets, designs, API specs, recordings, and code changes |
| Bug & Defect                    | Create tickets and review healing suggestions                           |
| Advanced Testing                | Supported performance, security, and code-export workflows              |
| AI-Powered Analysis             | Root cause, repository queries, and impact analysis                     |
| Analytics & Coverage            | Coverage-gap analysis and proposed tests                                |
| Custom Agents & Knowledge Bases | Agent and knowledge-base management                                     |
| Telemetry                       | Step results, network and console logs, trace links, and reasoning data |
| Support-to-Fix                  | Reproduce and investigate supported failure workflows                   |
| Migration Platform              | Analyze supported repositories, migrate, and export                     |

***

## Tool Categories in Detail

### Test Case Management

The core CRUD layer for test cases. You can create a test case from a URL and a plain English description, read back its steps, update individual steps, delete cases, and query the full test library using natural language search.

| Tool                       | Purpose                                            |
| -------------------------- | -------------------------------------------------- |
| `create_test_case`         | Create a new test case from URL + task description |
| `get_test_cases`           | List all test cases in a workspace                 |
| `get_test_case_steps`      | Get all steps for a specific test case             |
| `update_test_case_step`    | Modify an individual step                          |
| `delete_test_case`         | Permanently delete a test case                     |
| `delete_test_case_step`    | Remove one step from a test case                   |
| `query_contextqa`          | Natural language search across all test cases      |
| `create_complex_test_step` | Add an advanced step (conditional, loop, API call) |

### Execution & Results

Tools that trigger test runs and retrieve results. The typical pattern is: call `execute_test_case`, store the returned execution handle, poll `get_execution_status` until a terminal state, then fetch results.

| Tool                    | Purpose                                         |
| ----------------------- | ----------------------------------------------- |
| `execute_test_case`     | Run a single test case                          |
| `get_execution_status`  | Poll for PASSED / FAILED / RUNNING              |
| `get_test_case_results` | Get the complete result object for an execution |
| `get_test_step_results` | Retrieve per-step details including screenshots |
| `fix_and_apply`         | Apply a code-level fix to a failing test        |

### Test Suites & Plans

Suites group related test cases. Plans add execution configuration: which browser, which environment, which schedule. These tools let an agent orchestrate full regression runs, not just individual cases.

| Tool                             | Purpose                            |
| -------------------------------- | ---------------------------------- |
| `get_test_suites`                | List all suites in a workspace     |
| `execute_test_suite`             | Run an entire suite                |
| `get_test_plans`                 | List all test plans                |
| `execute_test_plan`              | Trigger a full plan execution      |
| `get_test_plan_execution_status` | Poll plan-level execution status   |
| `rerun_test_plan`                | Re-run a plan (useful after fixes) |

### Infrastructure & Config

Manage the environments (base URLs, variables), device configurations for mobile tests, and discover the UI element map of a live application.

| Tool                     | Purpose                                              |
| ------------------------ | ---------------------------------------------------- |
| `get_environments`       | List all configured environments                     |
| `get_test_devices`       | List available mobile device configurations          |
| `get_mobile_concurrency` | Check how many concurrent mobile slots are available |
| `get_ui_elements`        | Discover all UI elements on a live page              |
| `list_custom_agents`     | List all custom AI agent personas                    |
| `create_custom_agent`    | Define a new agent persona with custom behavior      |
| `list_knowledge_bases`   | List all knowledge bases                             |
| `create_knowledge_base`  | Create a new knowledge base with AI instructions     |

### Test Generation

The generation tools are the most powerful entry point for an AI agent. Each one accepts a different source artifact and returns a fully formed test case ready to execute.

| Tool                                | Purpose                                   |
| ----------------------------------- | ----------------------------------------- |
| `generate_contextqa_tests_from_n8n` | Generate from an n8n workflow file or URL |
| `generate_tests_from_code_change`   | Generate from a git diff                  |
| `generate_tests_from_jira_ticket`   | Generate from a Jira/ADO ticket           |
| `generate_tests_from_figma`         | Generate from a Figma design URL          |
| `generate_tests_from_excel`         | Generate from an Excel/CSV file           |
| `generate_tests_from_swagger`       | Generate from an OpenAPI spec             |
| `generate_tests_from_video`         | Generate from a screen recording          |
| `generate_tests_from_requirements`  | Generate from a requirements document     |
| `generate_tests_from_analytics_gap` | Generate tests to fill coverage gaps      |
| `generate_edge_cases`               | Generate boundary and negative scenarios  |

### Bug & Defect

Once a failure is confirmed, these tools handle the full defect lifecycle: push to the issue tracker, inspect what changed in the UI, and apply the automated fix.

| Tool                           | Purpose                                       |
| ------------------------------ | --------------------------------------------- |
| `create_defect_ticket`         | Create a Jira/ADO issue with failure evidence |
| `get_auto_healing_suggestions` | Get AI-proposed locator fixes                 |
| `approve_auto_healing`         | Accept and apply a healing suggestion         |

### Advanced Testing

Beyond browser UI tests, ContextQA supports performance and security test types triggered from the same tool interface.

| Tool                         | Purpose                                     |
| ---------------------------- | ------------------------------------------- |
| `execute_performance_test`   | Run a load/performance test                 |
| `execute_security_dast_scan` | Run a DAST security scan against a live URL |
| `export_test_case_as_code`   | Export a test case as runnable code         |

### AI-Powered Analysis

These tools let the AI agent interrogate a test repository for intelligence — finding what changed, what is at risk, and what tests already exist.

| Tool                  | Purpose                                         |
| --------------------- | ----------------------------------------------- |
| `get_root_cause`      | AI analysis of a specific test failure          |
| `query_repository`    | Query the test repo for context about a feature |
| `analyze_test_impact` | Given a code change, identify impacted tests    |

### Analytics & Coverage

| Tool                                | Purpose                                          |
| ----------------------------------- | ------------------------------------------------ |
| `analyze_coverage_gaps`             | Identify application flows with no test coverage |
| `generate_tests_from_analytics_gap` | Create tests that close identified gaps          |

### Custom Agents & Knowledge Bases

Custom agents and knowledge bases allow teams to encode institutional testing knowledge into the AI execution engine — for example, always skip the cookie consent banner, or always use the test credit card number on the payment page.

| Tool                    | Purpose                                      |
| ----------------------- | -------------------------------------------- |
| `list_custom_agents`    | List all agent personas                      |
| `create_custom_agent`   | Create a new agent with custom system prompt |
| `list_knowledge_bases`  | List all knowledge bases                     |
| `create_knowledge_base` | Create a knowledge base with AI instructions |

### Telemetry

Every execution produces a rich evidence package. These tools expose each artifact individually so an AI agent can inspect exactly what happened at the network, DOM, and console level.

| Tool                         | Purpose                                     |
| ---------------------------- | ------------------------------------------- |
| `get_execution_step_details` | Per-step data with screenshots              |
| `get_network_logs`           | Full HAR-format network log                 |
| `get_console_logs`           | Browser console output                      |
| `get_trace_url`              | URL to Playwright trace viewer              |
| `get_ai_reasoning`           | Per-step AI confidence scores and decisions |

### Support-to-Fix

When a user reports a bug — in a support ticket, Slack message, or Jira issue — these tools allow an agent to directly reproduce the reported behavior and produce a structured failure report.

| Tool                    | Purpose                                       |
| ----------------------- | --------------------------------------------- |
| `reproduce_from_ticket` | Reproduce a bug described in a support ticket |
| `investigate_failure`   | Deep investigation of a specific failure      |

### Migration Platform

Teams migrating from Cypress, Playwright, or Selenium can use these tools to analyze their existing test code and port it to ContextQA's natural language format.

| Tool                        | Purpose                                            |
| --------------------------- | -------------------------------------------------- |
| `analyze_test_repo`         | Analyze a test repository and report its structure |
| `migrate_repo_to_contextqa` | Convert existing tests to ContextQA format         |
| `export_to_playwright`      | Export ContextQA tests to Playwright TypeScript    |

***

## How MCP Works with ContextQA

The Model Context Protocol is an open standard that lets an AI model call external tools in a structured way. When you configure the ContextQA MCP server in your AI client (Claude Desktop, Cursor, a custom agent), the client receives a manifest of the tool definitions available to that connection — including names, descriptions, and parameter schemas. The AI model can then decide which available tool to call during a conversation.

The ContextQA MCP server translates each tool call into the corresponding ContextQA REST API call, handles authentication, and returns structured JSON results that the AI can reason about and present to you.

This architecture means you never need to learn the ContextQA REST API directly. You interact with your AI assistant in natural language, and the AI handles all the API orchestration.

***

## Related Documentation

The MCP tools map directly to ContextQA platform features documented elsewhere in these docs. Use these links to understand the features behind the tools:

| MCP capability                                         | Learn more                                                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Test case creation and the step editor                 | [Creating Test Cases](/web-testing/creating-test-cases.md), [Test Steps Editor](/web-testing/test-steps-editor.md)              |
| AI test generation from Jira, Figma, Swagger, and more | [AI Test Generation](/ai-features/ai-test-generation.md)                                                                        |
| Running tests and polling results                      | [Running Tests](/execution/running-tests.md), [Parallel Execution](/execution/parallel-execution.md)                            |
| Environments and execution configuration               | [Environments](/execution/environments.md)                                                                                      |
| Failure analysis and root cause debugging              | [Failure Analysis](/reporting/failure-analysis.md), [Debugging Tests](/execution/debugging-tests.md)                            |
| Self-healing and auto-healing suggestions              | [AI Self-Healing](/web-testing/self-healing.md)                                                                                 |
| Test data profiles and parameterization                | [Test Data Management](/web-testing/test-data-management.md)                                                                    |
| Custom agents and knowledge bases                      | [Custom Agents](/ai-features/custom-agents.md), [Knowledge Base](/ai-features/knowledge-base.md)                                |
| Defect ticket creation (Jira, Azure DevOps)            | [Jira Integration](/integrations/jira.md), [Azure DevOps Integration](/integrations/azure-devops.md)                            |
| CI/CD pipeline integration                             | [GitHub Actions](/integrations/github-actions.md), [Jenkins](/integrations/jenkins.md), [GitLab CI](/integrations/gitlab-ci.md) |
| Reports and analytics                                  | [Test Results](/reporting/test-results.md), [Analytics Dashboard](/reporting/analytics-dashboard.md)                            |

> **New to ContextQA?** Start with the [Quickstart Guide](/getting-started/quickstart.md) to understand the platform before setting up the MCP server. For role-specific guidance, see [ContextQA for SDETs](/documentation-by-role/by-role/for-sdets.md) or [ContextQA for Developers](/documentation-by-role/by-role/for-developers.md).

***

## Next Steps

* [Installation & Setup](/mcp-server/installation-and-setup.md) — connect a supported MCP client
* [Authentication](/mcp-server/authentication.md) — configure credentials for your deployment
* [MCP Connection Troubleshooting](/mcp-server/troubleshooting.md) — diagnose endpoint, OAuth, scope, and manifest problems
* [Agent Integration Guide](/mcp-server/agent-integration-guide.md) — learn how AI agents should use these tools effectively
* [Tool Reference](/mcp-server/tool-reference.md) — review documented tools, then confirm the connected manifest
* [Official Prompt Library](https://mcp.contextqa.com/docs/prompts) — copy task-oriented prompts for creation, execution, debugging, export, and migration
* [Official Bug Fix Workflow](https://mcp.contextqa.com/docs/bug-fix) — follow the reproduce, investigate, fix, verify, and report sequence
* [Official MCP Troubleshooting](https://mcp.contextqa.com/docs/faq) — diagnose connection, OAuth, execution, and prompt issues

## Evaluate MCP in your toolchain

Bring the AI client and QA workflow your team already uses. The ContextQA team can demonstrate how the hosted MCP server fits your authentication, test creation, execution, and failure-analysis process.

[**Book a Demo →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=mcp_server_overview)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learning.contextqa.com/mcp-server/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.