How to integrate an AI agent in testing, step by step

01What you need

A TestOrchestrator workspace, on any plan, Free included.
An AI client that speaks MCP: Claude Code, Cursor, Codex, Claude Desktop or another client that accepts a remote HTTP server.
The ticket the work is for, in Jira, Linear or another tracker, and a way for the agent to read it: the tracker's own MCP server or connector, or the text pasted into the conversation.

02Step 1: create a personal key

In TestOrchestrator open Settings → API keys → Personal keys and click New key. Give it a label that names the client ("Claude Code — Alex"), choose when it expires (90 days by default) and create it. The key starts with to_live_ and is shown once.

Use a personal key, not a workspace service key. A personal key carries the mcp scope and acts as you. A service key is for CI result upload and is refused on the MCP server.

03Step 2: connect the MCP server

Add https://api.testorchestrator.com/mcp to your client with the key as a bearer token. In Claude Code:

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

Cursor, Codex and Claude Desktop configuration is in the MCP docs. Restart the client; the TestOrchestrator tools appear. Ask the agent to call get_projects first: every other tool takes the numeric project id it returns.

04Step 3: let the agent draft cases from the ticket

Ask, for example: "Read CHK-42 and draft test cases for it in the Checkout project, in a new folder, linked to the issue." The agent:

reads the issue through its own access to the tracker;
calls get_fields to learn your template (steps, priority and custom fields);
creates a folder with create_folder and the cases with create_test_case;
links each case to the issue with link_to_issue, so get_cases_for_issue and the issue's coverage show them.

The tracker must be connected in Admin → Integrations for the link to name it. If you would rather not run an agent for this step, TestOrchestrator's own AI drafts reviewable cases from a Jira ticket or a Linear issue in the app.

05Step 4: review the drafts

The agent's cases are ordinary test cases, recorded under your name. Open the folder, read each case, fix the steps and expected results, delete what is not worth keeping. The agent can leave notes for the reviewer with add_comment. Do not skip this step: an agent drafts from the ticket it read, and only a person knows what the ticket left out.

06Step 5: start a run and record results

Ask the agent to start a run (start_test_run, optionally in a cycle and environment), look up the result statuses (get_statuses) and record a result per case (record_test_result, with a comment and the time spent). get_run_results shows the tally as it goes, and every result carries your name.

07Step 6: close the run and follow up

When the run is done, the agent closes it with close_test_run. Closing is what wakes the QA agent of the Linear integration (Pro and Business, off by default): for each linked Linear issue it drafts a summary of how its cases did and, when auto-actions are on, posts it as a comment, moves a regressed issue back to In Progress and labels an issue with fewer than half of its cases passing. Moving an issue to Done or filing a bug sub-issue always waits for an admin to approve it. The QA agent works with Linear only.

Coming next: uploading automated results from CI with a workspace service key, so agent-recorded and automated results sit in the same project. The keys exist today; upload opens in a later release.

08Keep it safe

One key per client, labelled, with an expiry. Revoke it when the client is retired; there is no reactivation.
The key can do what you can do. If an agent only needs to read, give it a key from a user with read-only access to the project.
Every call stays inside one workspace; a project the key cannot open answers "not found or access denied".
Check Last used on the key list for a key you thought was idle.

10Frequently asked questions

Can an AI agent run my test cases?

An agent can drive the run: open it, read each case's steps, record a status and a comment per case, and close it. Whether the checks themselves are performed depends on what the agent can reach, for example a browser or your test suite through its own tools. TestOrchestrator records what the agent reports; it does not execute tests itself.

Is it safe to give an AI agent access to test management?

It is when the key is narrow. A TestOrchestrator personal key has one scope, mcp: it works on the MCP server and is refused on the public API. It acts as you, so it can only do what you can do, in the projects you can open, in one workspace. It expires (90 days by default), you can revoke it at once, and everything the agent writes is recorded under your name.

Do I need a separate key for CI?

Yes, when result upload opens. CI uses a workspace service key, created by a Tenant Admin, bound to one project (or explicitly to all) and scoped to ingest:results. A service key cannot run MCP tools, and a personal key cannot upload results.

Which AI agents work with this?

Any MCP client that connects to a remote HTTP server with an Authorization header. The docs have ready configuration for Claude Code, Codex, Cursor and Claude Desktop.

Can the agent change my Jira or Linear issues?

Not through TestOrchestrator. Linking a case to an issue writes the link in TestOrchestrator only. If you also give the agent access to your tracker, what it can do there is decided by that access.