MCP — Model Context Protocol

msg.ZenTestAI ships with a built-in MCP server that lets external AI clients (Claude Desktop, Claude Code, Cursor, Windsurf, GitHub Copilot, …) connect directly to your tenant and drive the platform. 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.

There is no tenant configuration required to enable MCP — the server is always available. The configuration happens on the client side: each AI tool needs to be pointed at the MCP endpoint and given a credential to authenticate with.

---

Connection details

Field	Value
Endpoint	https://<your-msg-zentestai-backend>/mcp
Transport	Streamable HTTP (SSE-style fallback is not enabled).
Auth (option 1)	HTTP header zen-test-api-key: <your tenant API key> — 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 the simplest and works for headless CI scenarios. The Bearer-token flow is required when you want the MCP session to act on behalf of a specific human user (for example to inherit that user's product assignments).

---

How a tenant is selected

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

1. An explicit product argument passed to the tool — validated against the user's assigned tenants.
2. The user's single assigned tenant — applies automatically when API-key auth is used (an API key is bound to exactly one tenant).
3. A previously persisted choice made via the select_product MCP tool — used only when the user has access to two or more tenants.
4. Otherwise the call fails with a clear error message listing the available tenants.

The persisted choice survives reconnects and backend restarts.

---

Client configuration examples

Cursor / Windsurf / Claude Code (API-key)

Add the following to your client's MCP configuration file (e.g. ~/.cursor/mcp.json):

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

Cursor / Windsurf / Claude Code (OIDC user)

{
  "mcpServers": {
    "zentestai": {
      "url": "https://<backend-host>/mcp",
      "headers": { "Authorization": "Bearer <oidc-access-token>" }
    }
  }
}

Claude Desktop

Claude Desktop currently only speaks stdio MCP. Use the mcp-remote bridge to talk to a remote HTTP server:

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

---

What the AI client can do

The MCP server exposes a curated set of tools. They fall into the following groups:

Group	Examples	What it lets the AI do
Session / tenant	whoami, list_products, select_product	Find out who is logged in, list available tenants and remember a default tenant for future calls.
Read tests	list_test_definitions, get_test_definition, list_test_sets, get_test_set	Browse the test catalogue and read individual tests, parameters and execution variants.
Maintain tests	create_test_definition, update_test_header, add_test_step, update_test_step, delete_test_step, move_test_step, add_execution_variant, update_execution_variant	Create new tests and modify existing ones — including steps, parameters and variant combinations.
Run tests	execute_test, wait_for_execution, cancel_execution	Trigger executions (optionally in interactive mode), wait for them to finish and cancel them when needed.
Inspect results	list_executions, get_execution, get_execution_logs, list_execution_screenshots, get_execution_screenshot	Find past executions, read their headers/results, fetch the textual log and the captured screenshots.
Macros	list_macros, get_macro, create_macro, update_macro	Browse and author reusable test snippets (macros), including AI-generated business signatures.
Agents	list_agents	List the test users (agents) configured for the tenant.
Interactive recording	wait_for_interaction, interactive_continue, interactive_add_step, interactive_edit_step, interactive_delete_step, interactive_get_current_step, interactive_get_current_screenshot, interactive_get_frames, interactive_read_accessibility, interactive_run_js, interactive_act_on_node	While a test runs in interactive mode the AI can pause, inspect the live browser, try out actions and record new steps.

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

---

Security model

• MCP reuses the existing authentication. Whatever the API key or Bearer token is allowed to do on the REST API, the MCP session is allowed to do — no more, no less.
• The opening initialize HTTP call is not authenticated; an anonymous client can list the available tool schemas but cannot invoke any tool. Every tool invocation runs through the authentication guard.
• All tenant restrictions (max executions per day, max AI cost per day, host restriction, edit-lock) apply to MCP calls just like they do to REST and frontend calls.
• The MCP session does not introduce any new persisted state beyond the per-user default-tenant selection. It does not store conversation history, prompts or generated content.

---

Tips

tip

For shared CI/CD pipelines or generic automation, prefer the API-key flow — it does not need human re-authentication and the key can be regenerated at any time on the Head-Data tab.

tip

For per-developer setups (one AI client per engineer), prefer the Bearer-token flow so the AI session inherits the developer's roles and tenant assignments.

caution

An MCP client that has the API key can run, edit and create tests in your tenant. Treat the API key like any other production credential — store it in a password manager or secret vault, never commit it to source control.