How to connect Claude Code to a test management tool

01What you need

• Claude Code installed and signed in. We used Claude Code 2.1.260.
• A TestOrchestrator account. Any plan works, Free included. The MCP server is at https://api.testorchestrator.com/mcp.
• A project with at least one case, so the first request has something to read.

021. Create a personal key

In TestOrchestrator open Settings → API keys (the Personal keys tab) and choose New key. Give it a label that names the client and the person, for example Claude Code, Sam; the expiry defaults to 90 days. The dialog says plainly that anyone holding the key can read and modify the workspace's test data.

After Create key, the key is shown once: "This is the only time the key is shown. Copy it now." Copy it into a password manager or straight into the next command. Afterwards the list shows only its prefix, to_live_…, and a Last used column that reads Never until a client authenticates with it.

032. Add the MCP server to Claude Code

Run this in the project folder you work in, with your key in place of the placeholder:

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

Claude Code answers:

Added HTTP MCP server testorchestrator with URL: https://api.testorchestrator.com/mcp to local config
Headers: {
  "Authorization": "[REDACTED]"
}

Without -s, the server goes into your local config: private to you, in this project only.

043. Check the connection and the tools

claude mcp get testorchestrator

testorchestrator:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: http
  URL: https://api.testorchestrator.com/mcp

claude mcp list shows the same server as Connected. When Claude Code starts in this project it loads 39 tools from the server, each named after the server and the tool, for example get_projects, create_test_case and record_test_result. In the app, the key's Last used cell changes from Never to the time of the first request.

If the status is not Connected, check the URL, that the header reads Bearer followed by the whole key, and that the key is still Active in the list. A missing, revoked or expired key is answered with HTTP 401.

054. Ask Claude Code to work in your test cases

Start with a request that has a clear end, for example:

Use the testorchestrator tools. List my projects. In the Checkout project, read test case 1. Then create a test case in the Payments folder titled "Pay with an expired card is declined", in the Draft state, and read it back.

The server tells the agent how to begin: get_projects is described as the tool to call first, because every project tool takes the numeric project id it returns, not the project name. A request like the one above uses six tools: get_projects, get_test_cases, get_test_case, get_folders, get_lifecycles (to find the id of the Draft state) and create_test_case. We ran exactly this sequence against a TestOrchestrator server with Codex; the full transcript is in How to manage test cases with Codex and MCP.

Ask for the Draft state on purpose. In a new workspace the default state for a case is Ready, so a case created without a state is not marked for review. See how to review test cases created by AI agents.

06Permissions: what Claude Code can do with the key

• It acts as you. The key has your access in your workspace: projects you cannot open answer "not found or access denied", and edits you cannot make are refused.
• Everything it writes is yours. A case or result the agent creates is recorded under your account; there is no separate agent identity.
• Allow tools deliberately. Claude Code asks before it runs a tool unless you allow it. Allowing the read tools (get_*, search_test_cases) and keeping write tools on ask is a sensible start.
• Revoke when done. Revoking a key in Settings → API keys stops it on the next request; there is no way to reactivate it.

More in security and permissions for MCP test management.

07Related

• MCP server docs and tool reference
• How to manage test cases with Codex and MCP
• MCP server for test management
• Best MCP-compatible test management tools