MCP Server

TestOrchestrator exposes its QA data and actions to any MCP-compatible AI client — Claude, Claude Code, Cursor, or any agent that speaks the Model Context Protocol — over an MCP server. Your AI client supplies the intelligence; TestOrchestrator supplies the projects, test cases, runs, comments, and traceability it can act on. There is no chat UI inside the product: you connect your own client with a personal API key.

Availability. The MCP server is rolling out. If you don’t yet see API Keys under your profile, it has not reached your workspace — check back shortly. This page documents how it works so you’re ready to connect on day one.

How it works

The protocol splits the work cleanly: the AI client is the “coworker” that reasons and decides what to do, and TestOrchestrator is the system of record it reads from and writes to. Connect a client once with an API key and your agent can discover a project’s structure, author detailed test cases, comment, start runs, link cases to Linear or Jira issues, and read coverage and traceability — all from inside your own AI tool.

Endpoint: https://api.testorchestrator.com/mcp — Streamable HTTP, JSON-RPC 2.0.
Authentication: a personal API key sent as an Authorization: Bearer <key> header.
Isolation: every call runs inside the key’s workspace (tenant). A key for one workspace can never read or write another workspace’s data.

1. Create your API key

API keys are personal and self-service — any user can create their own, no admin needed.

In TestOrchestrator, open Profile → API Keys.
Click Create API key, give it a label (for example “Claude Desktop”), optionally set an expiry, and confirm.
Copy the key now. It is shown exactly once and stored only as a hash. If you lose it, revoke it and create a new one.

You can create multiple keys and revoke any of your own at any time — revocation takes effect immediately.

Treat an API key like a password. It grants access to everything you can reach in the app. Don’t commit it to source control or paste it into shared documents; store it in your MCP client’s config or a secrets manager.

2. Connect your AI client

Point your client at the endpoint and pass your key in the Authorization header. Restart the client afterwards; you should see the TestOrchestrator tools become available. Replace to_live_… with the key you created.

Claude Code (CLI)

claude mcp add --transport http testorchestrator \
  https://api.testorchestrator.com/mcp \
  --header "Authorization: Bearer to_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Cursor (`.cursor/mcp.json`)

{
  "mcpServers": {
    "testorchestrator": {
      "url": "https://api.testorchestrator.com/mcp",
      "headers": {
        "Authorization": "Bearer to_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop & other MCP clients

Clients that support remote (HTTP) MCP servers can use the same configuration shape:

{
  "mcpServers": {
    "testorchestrator": {
      "type": "http",
      "url": "https://api.testorchestrator.com/mcp",
      "headers": {
        "Authorization": "Bearer to_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For a client that can only launch local (stdio) servers, bridge to the HTTP endpoint with mcp-remote:

{
  "mcpServers": {
    "testorchestrator": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.testorchestrator.com/mcp",
        "--header",
        "Authorization: Bearer to_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Once connected, confirm it works by asking the agent something like “list the test cases in project 6.” See the Tool Reference for everything an agent can do.

The security model

The MCP server is designed so a key can never do more than the person who created it. Three guarantees back that up:

A key acts as you. It inherits your permissions — your access level, global role, project membership, and any per-project overrides. It can do only what you can do in the app, in the projects you can access — nothing more. (This mirrors how Linear API keys inherit the issuer’s permissions.)
Least privilege by default. Because the key is scoped to you, granting an agent access never widens your reach. If you can’t edit a project, neither can your key.
Strict tenant isolation. Every call runs inside your workspace. A key issued in one workspace can never read or write another workspace’s data.

Errors for missing or forbidden resources are reported as “not found or access denied” without revealing whether the resource exists in another workspace. A missing, invalid, revoked, or expired key returns HTTP 401, and the key value is never echoed back or written to logs.

What an agent can do

The server exposes a growing set of tools, grouped by area — discovery, test cases, folders, comments, test runs, cycles, and traceability. The Tool Reference documents every tool with its arguments. In short, an agent can:

Discover a workspace’s projects, folders, fields (including steps and priority), integration sources, cycles, environments, lifecycle states, statuses, tags, and users.
List, search, create, and update test cases — including steps and priority via custom field values — and organise the folder tree.
Read, add, edit, and delete comments on a test case.
Start and edit test runs, record per-case results, read a run’s summary, and close it out.
Create, update, and reopen cycles that group those runs.
Link a case to a Linear or Jira issue and read coverage gaps and reverse traceability.

Protocol notes & limits

Transport. Streamable HTTP over POST /mcp (request/response). The server-push GET SSE channel is not implemented — the connection is POST-only.
JSON-RPC methods: initialize, tools/list, tools/call, ping, and notifications/initialized.
Search is keyword/filter, not semantic. search_test_cases matches on title and number; there is no embedding or semantic search.
Permissions apply per tool. Write tools (create, update, comment, link, start run) require the same permissions they need in the app, so some calls may be denied for read-only keys.
Errors. Tool execution failures return a tools/call result with isError: true and an opaque message; malformed arguments return JSON-RPC -32602.

Out of scope. CI-intelligence tools (flaky-test detection, failure history), test-pack tools, and semantic search are not offered — the server only advertises tools backed by a real capability. tools/list is a contract that everything in it works.

🔧