MCP Server

TestQala exposes a Model Context Protocol (MCP) server that lets AI-powered tools run tests on your behalf. Connect your IDE or agent (Claude Code, VS Code Copilot, Cursor, Windsurf, etc.) and trigger test runs without leaving your editor.

Endpoint

Transport	URL
Streamable HTTP	https://mcp.testqala.com/mcp
SSE	https://mcp.testqala.com/sse

Authentication

All requests require a Bearer token using your TestQala API key:

Authorization: Bearer tqa_xxxxx

See Getting Started for how to create an API key.

info

MCP access requires a plan with API access enabled. If your plan doesn't include API access, tool calls will return an API_ACCESS_DENIED error.

Available Tools

list_targets

Lists the active verification targets associated with your account.

Parameters: None

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My App",
    "value": "app.example.com",
    "type": "domain"
  }
]

run_test_cases

Creates and dispatches a test run with one or more test cases against a target.

Parameters:

Name	Type	Required	Description
target	string	Yes	The target domain to test against
platform	"web" | "mobile" | "desktop"	No	Platform to execute on (default: web)
platformOptions	object	No	Platform-specific options (e.g. browser, viewport)
testCases	array	Yes	One or more test cases (min 1)
testCases[].name	string	Yes	Test case name
testCases[].type	"functional" | "bug-replication"	Yes	Type of test case
testCases[].steps	string	Yes	Steps to execute
testCases[].expectations	string	Yes	Expected outcomes

Response:

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "testCaseCount": 1,
  "dashboardUrl": "https://app.testqala.com/external-runs/550e8400-e29b-41d4-a716-446655440000"
}

get_test_run

Gets the status and progress of a test run, including individual test case results.

Parameters:

Name	Type	Required	Description
runId	string (UUID)	Yes	The test run ID returned by run_test_cases

Response:

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "durationMs": 12345,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "testCases": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Login with valid credentials",
      "type": "functional",
      "status": "passed",
      "startedAt": "2025-01-15T10:30:01.000Z",
      "finishedAt": "2025-01-15T10:30:05.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Login with invalid password",
      "type": "functional",
      "status": "running",
      "startedAt": "2025-01-15T10:30:06.000Z",
      "finishedAt": null
    }
  ],
  "dashboardUrl": "https://app.testqala.com/external-runs/550e8400-e29b-41d4-a716-446655440000"
}

Possible status values: queued, running, passed, failed, errored, not_run

Client Configuration

tip

All examples below use an environment variable TESTQALA_API_KEY to avoid hardcoding your key. Set it in your shell profile or CI environment:

export TESTQALA_API_KEY="tqa_xxxxx"

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "testqala": {
      "type": "streamable-http",
      "url": "https://mcp.testqala.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TESTQALA_API_KEY}"
      }
    }
  }
}

GitHub Copilot Coding Agent

Add .copilot/mcp.json to your repository:

{
  "mcpServers": {
    "testqala": {
      "type": "http",
      "url": "https://mcp.testqala.com/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_TESTQALA_API_KEY"
      },
      "tools": ["*"]
    }
  }
}

Then add your API key as a secret in your repository's copilot environment:

1. Go to Settings > Environments > copilot (create it if it doesn't exist)
2. Add a secret named COPILOT_MCP_TESTQALA_API_KEY with your tqa_ key as the value

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "testqala": {
      "url": "https://mcp.testqala.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TESTQALA_API_KEY}"
      }
    }
  }
}

Example Usage

Once connected, you can ask your AI assistant to run tests naturally:

"Run a functional test against app.example.com that verifies the login flow works with valid credentials"

The assistant will call list_targets to find your target, then run_test_cases to dispatch the test. You'll get back a link to the dashboard where you can watch the run in real time.

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Missing or invalid API key	Check your Authorization header has a valid tqa_ key
403 API_ACCESS_DENIED	Plan doesn't include API access	Upgrade your plan at app.testqala.com
ENTITLEMENT_CHECK_FAILED	Entitlement service unreachable	Retry after a few moments
Connection refused	Wrong endpoint URL	Use /mcp for Streamable HTTP or /sse for SSE