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.

Where to find it. Open the account menu, choose My profile & settings, and pick API keys — the fourth item in the Personal group, after Profile, Preferences and Notifications. It is available to every signed-in user: there is no admin step, no plan gate, and no read-only mode. The page lists your own keys only, so someone else’s key never appears on it.

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 — MCP 2025-06-18 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.

1. Open Settings → API keys (under Personal).
2. Click New key in the panel head. On a workspace with no keys yet, the empty state offers Create a key instead — same dialog.
3. In the Create API key dialog, give the key a Label (up to 120 characters; the placeholder suggests “e.g. Claude Desktop — Alex”) and choose when it Expires.
4. Click Create key. The key is issued and shown to you once, in a dialog you cannot dismiss by accident — see the one-time reveal below.

Expiry is a choice, and it defaults to 90 days

The Expires row offers four options. There is no free-form date field, and no way to leave the question unanswered.

The label is required. Leaving it empty and clicking Create key replaces the field’s hint with “Enter a label so you can recognise this key later”; the error appears only on that save attempt, never when you tab out of the field, and it clears as soon as you start typing.

The one-time reveal

The API key created dialog is the only place the full key ever exists in the UI, so it is built so you cannot lose it by mis-clicking: clicking outside it does nothing, Escape does nothing, and there is no × to close it. Two explicit actions end it.

• Copy and close — copies the key to your clipboard and closes the dialog. If your browser blocks the clipboard, the dialog stays open and says so: “Your browser blocked the clipboard. Select the key above and copy it by hand before you close this — it cannot be shown again.” The key stays on screen, and one click selects the whole of it.
• I’ve saved it elsewhere — closes the dialog once you have stored the key yourself. The confirmation reads “Key saved. It cannot be shown again.”

The dialog states the rule plainly — “This is the only time the key is shown. Copy it now.” — and carries a link to this page (How to configure an MCP client) for the moment you are holding the key and need to know where to paste it.

Treat an API key like a password. It grants access to everything you can reach in the app. The dialog says the same thing: “Anyone with this key can read and modify this workspace’s test data.” 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.

Only a prefix is kept. Once the dialog closes, the list shows the first characters of the key (to_live_…) and nothing more — hovering the cell says “prefix only — the full key is never shown again”. There is no way to re-read a key you did not save.

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"

Codex (~/.codex/config.toml)

[mcp_servers.testorchestrator]
type = "http"
url = "https://api.testorchestrator.com/mcp"

[mcp_servers.testorchestrator.http_headers]
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.

3. Manage your keys

The same page lists every key you own, newest first. There is no sort control and no search box — a personal key list is a handful of rows — but there is a status filter, because revoked and expired keys stay in the list rather than disappearing from it.

What each row tells you

The expiring-soon banner

When any active key falls inside the 14-day window, a warning banner sits above the panel and names the deadline — for a single key, “Nightly CI pipeline expires in 9 days. Whatever uses it stops working then — create a replacement before it lapses.”; for more than one, “2 keys expire within two weeks. Whatever uses them stops working then.” Its Show active button switches the list to the Active filter.

The status filter

The Status control in the panel head filters to All, Active, Expired or Revoked, with a live count beside each of the three states. The count next to the panel title follows the filter. Filtering to a state you have none of gives you, for example, No expired keys / Try a different status. and a Clear filter button.

Revoking a key

Each row’s … menu offers Copy key prefix and Revoke key…. On an already-revoked key the revoke item is simply absent — there is nothing left to switch off.

The confirmation changes with what the key is actually doing:

• A key still in use — one that authenticated a request within the last week — asks you to type REVOKE before the button enables, and names the evidence: “This key authenticated a request 2 days ago, so something is using it right now. That client loses access the moment you revoke.”
• A dormant key gets a plain confirm: “Any client still holding this key loses access immediately.”

Both dialogs carry the same note, because it is the part that decides the answer: “A revoked key cannot be reactivated. You will need to create a new key and update the client’s configuration.”

Revoking cannot be undone. The row flips to Revoked at once and the confirmation toast carries no Undo. There is no reactivate action anywhere in the product, and no rotate button either — rotation is create a new key, update the client, then revoke the old one, in that order.

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, and whatever each project’s access default and exceptions give you. 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, attachments, 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, workflow 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.
• Attach files — upload a screenshot or document to a test case field or step, a test run result, or an exploratory session result.
• Link a case to a Linear or Jira issue and read coverage gaps and reverse traceability.

Protocol notes & limits

• Transport. MCP 2025-06-18 Streamable HTTP: JSON-RPC request/response over POST /mcp (application/json). The server is stateless (no Mcp-Session-Id, no server-initiated messages).
• GET /mcp. Returns HTTP 405 Method Not Allowed — the spec-legal signal that no server-push SSE stream is offered. Clients such as Cursor stop retrying instead of hanging on a missing stream.
• 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. A missing, invalid, revoked, or expired key returns HTTP 401; the key value is never echoed or logged.

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.

Related