MCP server for test management: connect AI agents to your test cases

01What it does

The Model Context Protocol (MCP) is how AI clients call outside tools. An MCP server for test management turns the test repository into tools an agent can use: list the projects, read a case, create cases in a folder, start a run, record what passed and failed, link a case to the issue it covers.

TestOrchestrator's server is at https://api.testorchestrator.com/mcp (MCP 2025-06-18, Streamable HTTP, JSON-RPC 2.0). There is no chat window inside the product: you bring the agent, and TestOrchestrator is the record it reads from and writes to.

02What an agent can do

The tools fall into eight groups. The tool reference lists every tool with its arguments.

Group	What the agent can do
Discovery	List projects, folders, fields (steps, priority), trackers, cycles, environments, workflow states, statuses, tags and users
Test cases	List, search, read, create and update cases, including steps and priority
Folders	Create, rename and move folders
Comments	Read, add, edit and delete comments on a case
Test runs	Start runs, change their case selection, record a result per case, read a run's summary, close runs
Cycles	Create, update and reopen the cycles that group runs
Attachments	Upload a screenshot or file to a case, a step, a run result or an exploratory session result
Traceability	Link a case to a Jira, Linear or other tracker issue, find the cases for an issue, read coverage gaps

Search is by keyword and filter, not semantic. Linking writes the link in TestOrchestrator only; it never changes the issue in the tracker.

03Connect Claude Code, Cursor or another client

In TestOrchestrator, open Settings → API keys → Personal keys and create a key. It is shown once; store it in your client's config or a secrets manager.
Add the server to your client. For Claude Code:

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

For Cursor, in .cursor/mcp.json:

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

Ask the agent to start with get_projects, for example "list the test cases in my Checkout project". Codex, Claude Desktop and the mcp-remote bridge are in the MCP docs.

04Let an agent write cases from a ticket

An agent can turn a Jira or Linear issue into test cases in one conversation: it reads the issue through its own access to the tracker, calls get_fields to learn your template, creates the cases with create_test_case and links each one to the issue with link_to_issue. You review them in TestOrchestrator like any other case.

If you would rather not run an agent, TestOrchestrator's own AI drafts cases from a connected Jira, Linear, Notion, Azure DevOps or GitHub issue in the app, and in Linear you can mention TestOrchestrator on an issue to get cases drafted and linked.

05Let an agent record test results

start_test_run opens a run with the project's cases (or a cycle and environment you name), record_test_result sets one case's status with an optional comment and time spent, get_run_results reads the tally, and close_test_run finishes it. Every result carries the name of the person whose key the agent used.

Uploading results from CI is coming. Workspace service keys and the upload endpoint, POST /api/v1/ingest/results for JUnit XML, Playwright JSON or TestOrchestrator JSON, already exist; upload opens in a later release. See API keys.

06Keys, scopes and permissions

TestOrchestrator has two kinds of key, and each works on one surface only.

Key	For	Scopes	Project	Works on
Personal key	An MCP client acting as you	`mcp`	Follows your own project access	`/mcp`
Workspace service key	A CI pipeline uploading results	`ingest:results`, optionally `read`	One project, or explicitly all	`/api/v1`

A personal key acts as you. It has your access level, role and project access; if you cannot edit a project, neither can the agent.
A service key is bound to a project by its prj_ id and cannot run MCP tools: on /mcp it is refused like an unknown key.
Tenant isolation. Every call runs inside the key's workspace.
Expiry and revocation. Personal keys default to 90 days; revoking a key stops it on the next request, and the key list shows when each key last authenticated.

08Frequently asked questions

What is an MCP server for test management?

It is a Model Context Protocol endpoint that exposes a test management tool's data and actions as tools an AI client can call. The AI client does the reasoning; the test management tool stays the system of record for cases, runs and results.

Which AI clients can connect to TestOrchestrator?

Any client that speaks MCP over HTTP and lets you set an Authorization header: the MCP docs carry ready configuration for Claude Code, Codex, Cursor and Claude Desktop. Copilot, Windsurf and other clients use the same URL and header if they accept a remote HTTP server; a client that only runs local servers can bridge with mcp-remote.

Can an AI agent record test results?

Yes. With start_test_run, record_test_result and close_test_run an agent opens a run, records a status per case with an optional comment and time spent, and closes it. The results are attributed to the key's owner.

Can an agent write test cases from a Jira or Linear ticket?

Yes. The agent reads the ticket with its own access to the tracker (for example the tracker's own MCP server, or text you paste), creates the cases with create_test_case, and links each one to the issue with link_to_issue, so the issue's coverage shows in TestOrchestrator. TestOrchestrator's built-in AI can also draft cases from a Jira, Linear, Notion, Azure DevOps or GitHub issue in the app.

Which plans include the MCP server?

Every plan, including Free. Any signed-in user can create a personal key; there is no admin step and no plan gate.

Can an agent see other workspaces or projects I cannot open?

No. A key works only inside the workspace it was created in and can do only what its owner can do there. A project you cannot open is answered "not found or access denied", the same as one that does not exist.