MCP — Model Context Protocol

msg.ZenTestAI ships with a built-in MCP server that lets external AI clients — Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot and others — connect directly to your tenant and drive the platform from your own editor. Once connected, the AI client can browse tests, run them, inspect results and even author new tests on your behalf, using the same permissions as the user (or API key) it authenticates with.

MCP is an open standard for connecting AI assistants to external tools and data. msg.ZenTestAI exposes its capabilities as MCP tools; any MCP-capable client can call them.

There is no per-tenant setup screen for MCP — the server is always available (an administrator can switch it off per tenant via a feature flag). The configuration happens entirely on the client side: point your AI tool at the endpoint and give it a credential.

Connection details

Field	Value
Endpoint	https://<your-msg-zentestai-backend>/mcp
Transport	Streamable HTTP (no SSE fallback).
Auth — option 1	HTTP header x-zen-test-api-key: <tenant API key> (legacy zen-test-api-key still accepted) — see API-Key Connectivity.
Auth — option 2	HTTP header Authorization: Bearer <OIDC access token> — the same token the frontend uses.

The API-key flow is simplest and works for headless / CI scenarios; the key is bound to exactly one tenant. The Bearer-token flow makes the session act on behalf of a specific human user, so it inherits that user's tenant assignments and roles.

Integrating it in your editor

The examples below all do the same thing: register a server named zentestai pointing at /mcp with an auth header. Replace <backend-host> and the credential with your own.

Claude Code

Add the server from the terminal:

claude mcp add --transport http zentestai https://<backend-host>/mcp \
  --header "x-zen-test-api-key: <your tenant API key>"

…or add it to your .mcp.json / settings:

{
  "mcpServers": {
    "zentestai": {
      "type": "http",
      "url": "https://<backend-host>/mcp",
      "headers": { "x-zen-test-api-key": "<your tenant API key>" }
    }
  }
}

Then run /mcp inside Claude Code to confirm the zentestai server is connected.

Cursor / Windsurf

Add the following to the client's MCP config file (Cursor: ~/.cursor/mcp.json, or the per-project .cursor/mcp.json; Windsurf uses the equivalent mcp_config.json):

{
  "mcpServers": {
    "zentestai": {
      "url": "https://<backend-host>/mcp",
      "headers": { "x-zen-test-api-key": "<your tenant API key>" }
    }
  }
}

To act as a specific user instead of an API key, swap the header for "Authorization": "Bearer <oidc-access-token>".

VS Code (GitHub Copilot)

In VS Code, add an MCP server to .vscode/mcp.json (or via MCP: Add Server in the command palette):

{
  "servers": {
    "zentestai": {
      "type": "http",
      "url": "https://<backend-host>/mcp",
      "headers": { "x-zen-test-api-key": "<your tenant API key>" }
    }
  }
}

Then enable the server in the Copilot Chat tool picker.

Claude Desktop

Claude Desktop currently speaks only stdio MCP, so bridge to the HTTP server with mcp-remote in claude_desktop_config.json:

{
  "mcpServers": {
    "zentestai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<backend-host>/mcp",
        "--header",
        "x-zen-test-api-key:<your tenant API key>"
      ]
    }
  }
}

How a tenant is selected

Tools always operate on one tenant ("product"). The active tenant is resolved on every call, in this order:

1. An explicit product argument passed to the tool — validated against your assigned tenants.
2. Your single assigned tenant — applies automatically with API-key auth (a key is bound to one tenant).
3. A previously persisted choice made with the select_product tool — used only when you have access to two or more tenants.
4. Otherwise the call fails with a clear message listing the tenants you can choose from.

The persisted choice survives reconnects and backend restarts.

What the AI client can do

The server exposes a curated set of tools, grouped by purpose:

Group	What it lets the AI do
Session / tenant	Find out who is logged in, list available tenants, and remember a default tenant.
Read tests	Browse the test catalogue and read tests, parameters, variants, execution plans, groups and macros.
Maintain tests	Create tests and edit them — steps, parameters, execution variants, activities and folders.
Run tests	Trigger executions (optionally interactive), wait for them to finish, and cancel them.
Inspect results	Find past executions, read headers / results / logs, and fetch captured screenshots.
Interactive recording	While a test runs interactively, pause, inspect the live page, try actions, and record new steps.
Application config	Read and update application profiles (non-secret settings) and read a linked Jira issue.
Knowledge Base	Read the application's Knowledge Base and write articles to it.

The exact list ships with the backend and may grow over time — your client always sees the current set when it connects.

Security model

• MCP reuses the existing authentication. Whatever the API key or Bearer token can do on the REST API, the MCP session can do — no more, no less.
• The opening initialize call is not authenticated, so a client can list the available tool schemas, but every tool invocation runs through the authentication guard. Anonymous clients cannot run anything.
• All tenant restrictions (max executions per day, max AI cost per day, host restriction, edit-lock) apply to MCP calls exactly as they do to the REST API and frontend.
• Tests bound to an external system (e.g. Jira/Xray) reject step edits via MCP, so the connector's view of the test can't be silently overwritten.
• An administrator can disable MCP for a tenant via a feature flag; tool calls for a disabled tenant are rejected.

tip

For shared CI/CD pipelines, prefer the API-key flow — it needs no human re-authentication and the key can be regenerated any time on the tenant settings. For per-developer setups, prefer the Bearer-token flow so the session inherits that developer's roles.

caution

A client holding the API key can run, edit and create tests in your tenant. Treat the key like any production credential — store it in a secret manager, never commit it to source control.