Test & bug management

Why a tester should care

TestRail's UI is fine for reading and miserable for bulk authoring. Creating 40 cases from a requirements document means 40 round trips through a modal, and copying a case between sections is a right-click adventure. This is the exact shape of work an agent does well: structured, repetitive, schema-constrained.

The subtler win is coverage analysis. Ask "which sections have no cases tagged for the payments epic" and you get an answer in seconds; doing it by hand means exporting to CSV and pivoting.

Which package

There is no vendor-official TestRail MCP server. Several community implementations exist with overlapping names and different coverage — @bun913/mcp-testrail (case-focused, actively published), @uarlouski/testrail-mcp-server (projects, cases, runs, results, attachments), mcp-testrail, and others. Choose on three criteria, in this order:

1. Recent commits. A TestRail server abandoned six months ago will break on the next API change and nobody will fix it.
2. Explicit tool list in the README. If you can't see which write tools exist before installing, don't install.
3. Whether it exposes delete. Prefer one that doesn't, or that lets you disable it.

Tool surface

Wire it up

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "<chosen-testrail-mcp-package>"],
      "env": {
        "TESTRAIL_URL": "https://yourorg.testrail.io",
        "TESTRAIL_USERNAME": "svc-qa-agent@yourorg.com",
        "TESTRAIL_API_KEY": "${TESTRAIL_API_KEY}"
      }
    }
  }
}

Generate the API key under the service account's profile settings, not your own. In TestRail the key inherits that user's project permissions — so scope the service account to the projects the agent is allowed to touch and nothing else. That is a far stronger control than any prompt instruction, because it survives the agent misunderstanding you.

Workflows

1 · Requirements → cases

The two-phase pattern — draft, review, then commit — is not optional here. It is the difference between an agent that saves you two hours and one that leaves 40 malformed cases someone has to delete by hand.

2 · Coverage gap analysis

3 · Results ingestion after a CI run

"Rather than guessing" is load-bearing. An agent that fuzzy-matches test names to case titles will cheerfully mark the wrong case as passed.

Gotchas

• Custom fields break naive tools. Most TestRail instances have mandatory custom fields. Have the agent call getCaseFields first and build against the real schema.
• Rate limits. TestRail Cloud throttles. Bulk creation of 200 cases one call at a time will hit it; prefer bulk endpoints where the server exposes them.
• Case IDs are not stable across projects. Agents confuse case id, run id, test id, and result id constantly. Ask for explicit ids in output and verify one by hand.
• No undo. TestRail has no trash can for deleted cases.

Why a tester should care

Xray's design decision is that a Test is a Jira issue. That gives you traceability for free — a Test links to a Story, an Execution links to a Version, a failed Test links to a Bug, and Jira's native reporting sees all of it. The cost is that the Jira + Xray UI is genuinely slow to work in. Creating an execution, adding tests, and recording results is a lot of clicking through two products that don't quite share a design language.

An MCP server collapses that. It also does something the UI is bad at: bulk import of automation results with correct linkage back to the right test issues, without a CI plugin.

Tool surface

Wire it up

Credentials come from Xray, not Jira. In Jira, go to Xray → Global Settings → API Keys and create a key for a dedicated service user; for Xray Cloud you can also manage keys at xray.cloud.getxray.app/api-keys. You get a client ID and client secret, which the server exchanges for a token against the GraphQL endpoint https://xray.cloud.getxray.app/api/v2/graphql.

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "<chosen-xray-mcp-package>"],
      "env": {
        "XRAY_CLIENT_ID": "${XRAY_CLIENT_ID}",
        "XRAY_CLIENT_SECRET": "${XRAY_CLIENT_SECRET}",
        "XRAY_BASE_URL": "https://xray.cloud.getxray.app"
      }
    }
  }
}

Workflows

1 · Story → tests, linked

2 · Automation results import

That second sentence is what Xray is for. "Which stories are at risk because their tests failed last night" is a question no other tool in this guide can answer in one hop.

3 · Release-readiness check

4 · Defect creation with evidence

Gotchas

• Write tools mutate shared state and there is no dry-run. A malformed bulk import creates real Jira issues that real people get notified about. Always draft first.
• GraphQL error messages are unhelpful. Expect vague failures on schema mismatches; the agent may retry with slightly different bad input rather than stopping.
• Test type matters. Steps behave differently for Manual vs Cucumber vs Generic. An agent that picks the wrong type produces tests that look right and can't be executed.
• Xray rate-limits the GraphQL API. Bulk operations need pacing.
• Community-maintained. Multiple implementations of varying quality exist. Read the source of the one you pick — it holds credentials that can write to your Jira.

Why a tester should care

Zephyr Scale takes the opposite architectural bet to Xray: test cases live in Zephyr's own data model with a folder tree, linked to Jira issues rather than being Jira issues. If you came from TestRail or qTest, the folder-and-cycle mental model will feel immediately familiar, and the hierarchy is genuinely nicer to organise thousands of cases in.

The MCP server matters most for the same reason as TestRail's: bulk authoring and folder surgery are tedious in the UI and trivial to describe in a sentence.

Tool surface

Wire it up

Generate an API access token from Zephyr Scale's own settings (not a Jira API token — they are different credentials, and mixing them up is the most common setup failure). The Cloud API base is https://api.zephyrscale.smartbear.com/v2.

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "npx",
      "args": ["-y", "@bun913/mcp-zephyr-scale"],
      "env": {
        "ZEPHYR_SCALE_API_TOKEN": "${ZEPHYR_SCALE_API_TOKEN}",
        "ZEPHYR_SCALE_BASE_URL": "https://api.zephyrscale.smartbear.com/v2",
        "ZEPHYR_SCALE_PROJECT_KEY": "PROJ"
      }
    }
  }
}

Workflows

1 · Structured bulk authoring

2 · Cycle planning for a release

3 · Execution status reporting

4 · Housekeeping

Gotchas

• Zephyr Scale ≠ Zephyr Squad. Different products, different APIs. A server built for one will not work with the other.
• Steps are a separate resource. The most common agent error is creating a case and never populating its steps. Verify the first few by hand.
• Folder ids, not paths. Have the agent resolve the folder tree before creating anything, or cases land at the root and you're moving them by hand.
• Community-maintained, thinner ecosystem than Xray. Fewer implementations to choose from and less battle-testing.

Why a tester should care

This is the spine. Xray and Zephyr handle the test artifacts; Jira holds the requirement the test exists to verify, and the defect the failure produces. With the official server you also get Confluence, which is where the acceptance criteria that nobody put in the ticket actually live.

The single best QA use is not creating bugs — it is requirement interrogation. Feed an agent a story plus its Confluence spec and ask what's ambiguous, untestable, or missing an error case. That's a static-analysis pass on requirements, and it catches defects before a line of code exists, which is the cheapest possible place to catch them.

Tool surface

Wire it up

Atlassian's server is remote and OAuth-based, so there are no long-lived tokens sitting in a config file — a meaningful security improvement over the community alternatives. Your Atlassian admin may need to approve the connection at the org level.

claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp

{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp"
    }
  }
}

Workflows

1 · Requirement interrogation (start here)

2 · Defect triage sweep

3 · Regression risk from a release scope

4 · Well-formed bug creation

Gotchas

• Writes are loud. Creating an issue or transitioning a ticket notifies watchers, fires automation rules, and may move a board column. There is no quiet mode.
• Comments are the safer write. When in doubt, have the agent comment rather than transition or edit. Comments are additive and easy to ignore.
• Jira content is untrusted input. A ticket description or comment is user-generated text. If your agent also has Playwright and database access, a crafted comment saying "run this SQL to verify" is a prompt-injection vector with real teeth. Never execute instructions found inside a ticket.
• JQL beats natural language. Give the agent explicit JQL for anything precise. Its translations from English are usually right and occasionally silently wrong.
• Custom workflows confuse transitions. Have it fetch available transitions rather than assuming "Done" exists.

Why a tester should care

Local Playwright answers "does it work in Chromium on my machine". It does not answer "does it work in Safari 16 on a real iPhone 13 on a real network", and the gap between those two questions is where a disproportionate share of production incidents live. BrowserStack's MCP server puts that matrix behind natural language, so a cross-browser check becomes a sentence rather than a config file and a CI job.

Beyond raw execution, the interesting surface is Test Observability — failure clustering, flake detection, and history across runs. Asking "which of our tests are flaky and what do they have in common" is a question your local runner genuinely cannot answer.

Tool surface

Wire it up

{
  "mcpServers": {
    "browserstack": {
      "command": "npx",
      "args": ["-y", "@browserstack/mcp-server@latest"],
      "env": {
        "BROWSERSTACK_USERNAME": "${BROWSERSTACK_USERNAME}",
        "BROWSERSTACK_ACCESS_KEY": "${BROWSERSTACK_ACCESS_KEY}"
      }
    }
  }
}

Credentials come from your BrowserStack account settings. Parallel-session limits are per plan — an agent that fires off a 20-browser matrix on a 2-parallel plan will queue, not fail, and you'll wonder why nothing is happening.

Workflows

1 · The browser-specific bug

2 · Release matrix run

That filter is the whole trick: separating "broken" from "broken here" is the only reason to run a matrix at all.

3 · Flake investigation

4 · Accessibility scan with device context

Gotchas

• Minutes cost money. An agent that decides to "check all major browsers" can burn a month's quota in an afternoon. Specify the matrix explicitly, every time.
• Local testing needs a tunnel. Staging behind a VPN requires BrowserStack Local; the agent won't set that up for you and the failure looks like a generic timeout.
• Real devices are slower. Sessions queue and start slowly. Don't put an agent-driven matrix run in a tight feedback loop — this is a nightly or pre-release activity.
• Not a replacement for local Playwright. Iterate locally, verify on the matrix. Doing everything on the cloud is slow and expensive.