MCP Tool Reference

This is the full set of tools the TestOrchestrator MCP server exposes, grouped by area — discovery, test cases, folders, comments, test runs, cycles, and traceability. Every tool operates inside the API key’s workspace and respects the key owner’s permissions. See the MCP Server overview to connect a client first.

Most tools take a numeric project id. Start by calling get_projects to resolve a project name to its id, then use that id with the other tools. Folder, field, tag, and source ids come from the discovery tools below.

Discovery

Resolve names to ids and learn a project’s structure before reading or writing.

Tool	What it does	Arguments
`get_projects`	List the projects you can access (id + name) — use it to resolve a project name to an id.	(none)
`get_folders`	List a project’s folders (id, name, parentId) so you can file cases in the right place.	`project`
`get_fields`	List a project’s templates and their fields (id, label, type incl. STEPS, options) — exactly what you see authoring a case. Use the field ids with `create_test_case`/`update_test_case` to set priority, steps, etc.	`project`, `templateId?`
`get_external_sources`	List a project’s integration sources (id, name, system type) and the available relation options. Use a source id + relation with `link_to_issue`.	`project`
`get_cycles`	List a project’s cycles (sprints/releases that group runs) and the available cycle types. Use a cycle id with run tools, and a cycle-type id with `create_cycle`.	`project`
`get_environments`	List the environments available in a project. Use an environment id as `environmentId` on run tools.	`project`, `context?` (`REPOSITORY` / `RUNS`)
`get_lifecycles`	List the lifecycle states available in a project. Use a state id as `lifecycleStateId` on case and run tools.	`project`, `context?` (`REPOSITORY` / `RUNS`)
`get_statuses`	List the result statuses for a project’s runs (id, name, whether each counts as pass/fail/complete). Use a status id with `record_test_result`.	`project`
`get_tags`	List the tags available in a project. Use tag ids with the `tagIds` argument on case and run tools.	`project`, `context?` (`REPOSITORY` / `RUNS`)
`get_users`	List the active users in the workspace (id, name, email, access level, global role) for assignee/identity resolution. Requires user-management permission.	(none)

Test cases

List, search, create, and update test cases — including steps and priority through custom field values.

Tool	What it does	Arguments
`get_test_cases`	List test cases in a project, optionally limited to a folder.	`project`, `folder?`
`search_test_cases`	Keyword/filter search matching case title and number, cursor-paginated. Not semantic search.	`project`, `query?`, `folder?`, `limit?`, `cursor?`
`create_test_case`	Create a test case. Set steps and priority via `fieldValues` (discover field ids with `get_fields`); optionally link to an external issue on creation with `sourceReference`.	`project`, `title`, `folder` (+ `templateId?`, `lifecycleStateId?`, `estimate?`, `tagIds?`, `fieldValues?`, `sourceReference?`)
`update_test_case`	Update an existing case’s fields — including steps and priority via `fieldValues`.	`project`, `caseId` (+ any of `title`, `folder`, `templateId`, `lifecycleStateId`, `estimate`, `tagIds`, `fieldValues`)

Steps and priority via fieldValues. Each entry is { fieldId, value }, where value is the field’s JSON value — a string for selects like priority, or a structured value for a STEPS field. Call get_fields first to discover the right field ids, types, and options.

Folders

Build and reorganise the repository folder tree that test cases live in.

Tool	What it does	Arguments
`create_folder`	Create a repository folder. Returns the new folder id for use with `create_test_case`. Omit `parentId` for a top-level folder.	`project`, `name` (+ `parentId?`, `description?`)
`update_folder`	Rename, re-describe, or re-parent a folder. Only the provided fields change.	`project`, `folderId` (+ `name?`, `description?`, `parentId?`)

Comments

Read, add, edit, and remove comments on a test case — useful for an agent to leave or revise analysis.

Tool	What it does	Arguments
`add_comment`	Add a comment to a test case (for example, analysis or notes from an AI agent).	`project`, `caseId`, `comment`
`get_comments`	List the comments on a test case.	`project`, `caseId`
`update_comment`	Edit a comment’s text. You can edit your own; editing someone else’s needs elevated permission.	`project`, `caseId`, `commentId`, `comment`
`delete_comment`	Delete a comment. You can delete your own; deleting someone else’s needs elevated permission.	`project`, `caseId`, `commentId`

Test runs

Start runs, edit their case selection, record per-case results, read summaries, and close them out.

Tool	What it does	Arguments
`start_test_run`	Start a test run — by default it includes all of the project’s test cases. Optionally attach a cycle and environment.	`project` (+ `title?`, `includeAllCases?`, `cycleId?`, `environmentId?`)
`get_test_runs`	List the runs in a project (id, title, status, counts). Use `get_run_results` for one run’s per-case detail.	`project`
`get_run_results`	Results summary for a run — folder tree with pass/fail/complete counts and per-status tallies.	`project`, `runId`
`record_test_result`	Record a result for one case in a run (e.g. Passed/Failed/Blocked). Get a `statusId` from `get_statuses`.	`project`, `runId`, `caseId`, `statusId` (+ `comment?`, `elapsedSeconds?`)
`update_test_run`	Edit a run’s title, notes, cycle, environment, lifecycle state, tags, and case selection. Closed runs can’t be edited.	`project`, `runId` (+ `title?`, `notes?`, `cycleId?`, `environmentId?`, `lifecycleStateId?`, `tagIds?`, and case selection: `includeAllCases?` / `caseIds?` / `addCaseIds?` + `removeCaseIds?`)
`close_test_run`	Close a run, marking it finished.	`project`, `runId`

Cycles

Create and manage the cycles (sprints/releases) that group test runs. Discover existing cycles and cycle types with get_cycles.

Tool	What it does	Arguments
`create_cycle`	Create a cycle. Set `status` `ACTIVE` (with a start date) to start it, or `COMPLETED` (with an end date) to complete it; nest it with `parentCycleId`.	`project`, `name`, `cycleTypeId` (+ `description?`, `startDate?`, `endDate?`, `status?`, `parentCycleId?`)
`update_cycle`	Update a cycle’s name, dates, type, status, or parent. Only the provided fields change; `clearParent` detaches its parent.	`project`, `cycleId` (+ `name?`, `description?`, `cycleTypeId?`, `startDate?`, `endDate?`, `status?`, `parentCycleId?`, `clearParent?`)
`reopen_cycle`	Reopen a completed cycle (back to `ACTIVE`, clearing its end date). Only a completed cycle can be reopened.	`project`, `cycleId`

Traceability

Link cases to external issues and read coverage and reverse traceability.

Tool	What it does	Arguments
`link_to_issue`	Link a test case to an external issue (e.g. a Linear or Jira issue) for traceability. This writes the link in TestOrchestrator only; it does not modify the external tracker.	`project`, `caseId`, `sourceId`, `issueKey` (+ `relationType?`, `issueUrl?`, `title?`)
`get_cases_for_issue`	Reverse traceability: the test cases referencing a given external issue.	`sourceId`, `issueKey`
`get_coverage_gaps`	Per object type, how many objects are not yet linked to any external issue — the traceability gap.	`project`, `sourceId?`

Errors & permissions

Resources you can’t see are reported as “not found or access denied” — the same message whether the resource is missing or simply outside your access, so it never reveals what exists in another workspace. Read-only keys can browse, but the write tools (creating or updating cases, folders, comments, runs, results, cycles, and links) require the same permissions they need in the app, so some calls may be denied. A few tools have extra gates: get_users needs user-management permission, and editing or deleting someone else’s comment needs elevated permission. Tool failures come back as a result with isError: true; malformed arguments return JSON-RPC -32602.

🤖