Provides tools to review test coverage of Jira issues by fetching linked test cases, steps, and executions from Zephyr Scale Cloud.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Zephyr Review MCP review test coverage for STORY-123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read-only Model Context Protocol server that exposes Zephyr Scale Cloud test data as review-oriented tools, so Claude (e.g. in Cowork) can review a story against its actual test coverage.
It answers: does this story have adequate, well-formed tests, and are they passing?
The story text (description, acceptance criteria) is expected to come from Jira (e.g. the Atlassian Rovo MCP). This server supplies the test-coverage half of the picture from Zephyr.
Read-only. Every tool issues only GET requests. No tool creates, updates, or deletes
Zephyr data. "Draft new tests" is a Claude reasoning activity in the conversation, not a write
call.
Assumes your team links test cases to Jira issues in Zephyr (the issuelinks
relationship). If a story has no linked tests, coverage reads as empty.
Related MCP server: mcp-zephyr-scale
Tool | Purpose |
| Headline tool. Fans out over the linked test cases, their steps, and executions and returns one digested coverage bundle plus a pass/fail/not-run summary. Heavier — use when assessing coverage/quality/pass-fail. |
| Lightweight, story-scoped listing: the test cases linked to a story, each with key, name/title, priority, and status. No steps or executions. Use when you just want the list/titles of a story's tests. |
| Full detail of one test case, including ordered steps (empty expected-result fields kept visible for quality review). |
| Focused pass/fail view: each linked execution's status, cycle, and date. |
| Full execution history of one test case, newest-first — every run across all cycles plus ad-hoc runs (not just the latest). Each execution carries status, cycle, date, comment, timing (execution/estimated ms), who ran it, environment, custom fields, and linked Jira issues. Test-case-scoped; use |
| Project-wide discovery: test cases in a project whose key/name/objective match |
| Project identifier and metadata. |
Set via environment variables (see .env.example):
Variable | Required | Default | Notes |
| yes | — | JWT bearer token. Generate in Jira → profile → Zephyr API keys. The server fails fast if unset. |
| no |
| One of |
| no | derived from region | Full base URL override; takes precedence over |
Regional base URLs:
us → https://api.zephyrscale.smartbear.com/v2 (default)
eu → https://eu.api.zephyrscale.smartbear.com/v2
au → https://au.api.zephyrscale.smartbear.com/v2
de → https://de.api.zephyrscale.smartbear.com/v2
The token maps to a Jira/Zephyr user; the server sees only what that user can see.
For using the server in an MCP client. Requires Node.js 18+. No clone or build needed — npx fetches and runs the published package.
Add to your MCP client config (Claude Cowork / Claude Desktop):
{
"mcpServers": {
"zephyr": {
"command": "npx",
"args": ["-y", "@pabloveintimilla/zephyr-mcp"],
"env": {
"ZEPHYR_API_TOKEN": "<your-token>",
"ZEPHYR_REGION": "us"
}
}
}
}That's it — the client launches the server on demand.
For working on the server itself: clone the repository and install dependencies.
git clone https://github.com/pabloveintimilla/zephyr-mcp.git
cd zephyr-mcp
npm install
npm run buildRun it:
ZEPHYR_API_TOKEN=<your-token> npm start # from built dist/
ZEPHYR_API_TOKEN=<your-token> npm run dev # from source, no build stepRun the tests:
npm testPoint an MCP client at your local build (instead of the published package):
{
"mcpServers": {
"zephyr": {
"command": "node",
"args": ["/absolute/path/to/zephyr-mcp/dist/index.js"],
"env": {
"ZEPHYR_API_TOKEN": "<your-token>",
"ZEPHYR_REGION": "us"
}
}
}
}This project uses OpenSpec for spec-driven
development. Do not start coding a feature directly — capture the intent as a change
first, then implement against it. This keeps openspec/specs/ (the source of truth for
current behavior) accurate and makes each change reviewable before code is written.
Layout:
openspec/specs/ — the current, agreed behavior (one folder per capability).
openspec/changes/ — active changes in progress (proposal, design, specs delta, tasks).
openspec/changes/archive/ — completed changes, kept for history.
Workflow (run as slash commands in Claude Code, or with the openspec CLI):
Explore — /opsx:explore to think through the problem before committing to a design.
Propose — /opsx:propose to create a change with proposal.md, design.md,
a spec delta under specs/, and tasks.md.
Apply — /opsx:apply to implement the tasks, checking them off as you go.
Archive — /opsx:archive once the work is done and verified; this syncs the spec
delta into openspec/specs/ and moves the change to archive/.
Useful CLI commands:
openspec list # active changes
openspec status --change "<name>" # artifacts + task progress
openspec instructions <artifact> --change "<name>"Publishing to npm is automated by GitHub Actions (.github/workflows/publish.yml). Publishing a GitHub Release builds the package and runs npm publish --provenance --access public.
One-time setup:
Create an npm access token (Automation or Granular, with publish rights for @pabloveintimilla/zephyr-mcp).
Add it as a repository secret named NPM_TOKEN (Settings → Secrets and variables → Actions).
Each release:
Bump the version: npm version <patch|minor|major> (commits and tags).
Push with tags: git push --follow-tags.
Create a GitHub Release for that tag — the workflow publishes it.
Verify: npx -y @pabloveintimilla/zephyr-mcp on a clean shell resolves the new version.
The Zephyr Scale Cloud OpenAPI spec is vendored at docs/zephyr.api.yml.
Returns Zephyr project metadata (Zephyr id, Jira project id, key, enabled flag) for a project key. Useful to resolve keys and scope during a review. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | The Jira/Zephyr project key, e.g. LOYAL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description correctly states 'Read-only', which is the key behavioral trait. It also lists the return fields. It does not mention potential errors or permissions, but for a read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first stating the core function and the second adding context. No wasted words; front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 param, no output schema), the description covers the return fields, read-only nature, and use case. It could be improved by mentioning error handling or permissions, but it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already well-documented. The description does not add additional meaning beyond what the schema provides (e.g., 'Returns ... for a project key' is redundant with schema description).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states that it returns Zephyr project metadata (Zephyr id, Jira project id, key, enabled flag) for a project key, and the utility is clear. It distinguishes from sibling tools like get_test_case and list_story_test_cases by focusing on project-level metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it is useful for resolving keys and scope during a review, providing clear context. However, it does not explicitly state when not to use it or list alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the full detail of a single Zephyr test case, including ordered steps with expected results. Steps with an empty expected-result field are preserved so quality gaps stay visible. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| testCaseKey | Yes | The Zephyr test case key, e.g. LOYAL-T45 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and specific behavior: preserves steps with empty expected results. With no annotations, description carries burden well. Could mention more about response structure or authorization, but adequate for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load purpose and add key behavioral detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers returned content (steps, expected results) and behavioral nuance. Lacks mention of other possible fields (status, metadata), but sufficient for single-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description and pattern. Description adds only an example key, but no new semantic info beyond schema. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly defines verb 'Returns' and resource 'full detail of a single Zephyr test case', including specific content like ordered steps. Distinguishes from siblings that list or search test cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance. Usage is implied (when full details needed), but description does not contrast with sibling tools like list_story_test_cases or search_test_cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the test executions linked to a Jira issue (story) with their status, cycle, and date — a focused pass/fail view. Returns an empty list when the story's tests have not been run. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The Jira issue key of the story, e.g. LOYAL-1234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description declares read-only behavior and documents the empty-list case when tests haven't been run. This adds essential behavioral context, though it could mention any auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, no filler. Each sentence adds value: purpose, empty-list behavior, and safety profile.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description adequately conveys return values (status, cycle, date) and the empty-list case. The read-only annotation further clarifies expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description for issueKey. The tool description adds no additional parameter-level detail beyond what is in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns test executions linked to a Jira issue, specifying the output includes status, cycle, and date. The phrase 'focused pass/fail view' distinguishes it from sibling tools like list_story_test_cases, which likely return test cases themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing pass/fail status of test executions but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LIGHTWEIGHT list of the test cases linked to one story (Jira issue key) — each with key, name/title, priority, and status. No steps, no executions. Use this when asked for the test cases or titles of a specific story. Prefer this over search_test_cases (which is project-wide, not story-scoped) and over review_story_coverage (which is heavier) when you only need the list. Read-only; returns an empty list (not an error) when no tests are linked.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The Jira issue key of the story, e.g. LOYAL-1234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses behavior: lightweight listing, no steps/executions, read-only, returns empty list instead of error. This informs the agent of exactly what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences, front-loaded with key info, no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description covers all necessary context: what is returned, what is excluded, and behavior for empty results. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description provides an example (e.g., LOYAL-1234), adding practical context beyond the schema's pattern. This extra hint justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists test cases linked to a story, with specific fields (key, name/title, priority, status). It distinguishes from siblings like 'search_test_cases' and 'review_story_coverage', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (when asked for test cases or titles of a specific story) and when to prefer alternatives (e.g., 'search_test_cases' is project-wide, 'review_story_coverage' is heavier). Also notes read-only nature and empty list behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FULL execution history of ONE test case (Zephyr test case key), newest-first — every run across all cycles plus ad-hoc runs, not just the latest. Each execution includes status, cycle, date, comment, automated flag, timing (execution/estimated ms), who ran it, environment, custom fields, and linked Jira issues. Use this when asked about a specific test case's runs, history, or flakiness. This is TEST-CASE scoped — for the executions of a whole story (Jira issue key) use list_story_executions instead. Read-only; returns an empty list (not an error) when the test case has never been run.
| Name | Required | Description | Default |
|---|---|---|---|
| testCaseKey | Yes | The Zephyr test case key, e.g. LOYAL-T45 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is read-only, returns empty list on no runs, and lists included fields. Lacks mention of pagination or limits but acceptable for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences, front-loaded with purpose, no fluff, efficient use of space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description covers scope, ordering, contents, edge case behavior, and sibling distinction—fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the parameter with description and pattern; description adds minimal extra context beyond reinforcing the key format. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it lists the full execution history of one test case, newest-first, clearly distinguishing from the sibling tool list_story_executions which is story-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (specific test case's runs, history, flakiness) and when not to use, directing the agent to list_story_executions for story-scoped queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FULL coverage for one story (Jira issue key), including every step and execution. Use when assessing whether a story is well covered, well-formed, or passing. Returns a digested bundle: linked test cases with objective, priority, status, steps (action / expected result / data), each case's most recent execution, referenced test cycles, and a coverage summary (passed / failed / not-run counts and step-quality flags). Heavier than list_story_test_cases — if you only need the list/titles of a story's tests, use that instead. Read-only; returns empty coverage (not an error) when no tests are linked.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The Jira issue key of the story, e.g. LOYAL-1234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses read-only nature and behavior when no tests are linked (returns empty coverage, not error). Could add more about performance or auth, but adequate for agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-organized sentences: purpose, when-to-use, detailed return. No fluff; every sentence adds value. Front-loaded with core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly enumerates the returned bundle content (linked test cases with details, executions, cycles, coverage summary). Sufficient for agent to understand what it gets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for issueKey. The description adds a useful example (LOYAL-1234) but does not provide new semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('review' coverage) and resource ('story'), and clearly distinguishes from sibling tools by stating it returns a full digested bundle, while 'list_story_test_cases' only returns list/titles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (assess coverage, well-formedness) and when not to (if only list needed), providing a direct alternative: 'use list_story_test_cases instead'. Also notes it is heavier than the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PROJECT-WIDE search across ALL test cases in a project, matching key/name/objective (case-insensitive, client-side; the Zephyr API has no full-text search). This is NOT scoped to a story — do not use it to get the tests of a specific issue. Use it only when you do NOT have a Jira issue key, or to look beyond the tests linked to a single story. For a story's tests, use list_story_test_cases (titles) or review_story_coverage (full). Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to match against key/name/objective. Empty returns all. | |
| projectKey | Yes | The Jira/Zephyr project key, e.g. LOYAL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it is client-side, case-insensitive, read-only, and notes that the Zephyr API lacks full-text search. This goes beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each providing essential information. The most critical point (project-wide, not scoped) appears first. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no output schema, and moderate complexity, the description is fully complete. It explains behavior, limitations, and alternatives. No gaps for an agent to misinterpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are described already. The description adds valuable context: query matches key/name/objective and empty returns all, and projectKey is the Jira/Zephyr key. This slightly exceeds the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs a PROJECT-WIDE search across all test cases in a project, matching key/name/objective, and distinguishes itself from scoped searches by specifying it's not for a specific story. The verb 'search' and resource 'test cases' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (when you do NOT have a Jira issue key or need to look beyond a single story) and when not to use (do not use to get tests of a specific issue). It also provides two named alternatives: list_story_test_cases and review_story_coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1get_projectget_test_caselist_story_executionslist_story_test_caseslist_test_case_executionsreview_story_coveragesearch_test_casesScored across 7 tools
Each tool targets a distinct resource and action: project metadata, individual test case details, story-level test listing, story-level execution summary, test-case-level full execution history, comprehensive coverage review, and project-wide search. Descriptions explicitly differentiate between similar-sounding tools (e.g., list_story_test_cases vs review_story_coverage).
All tools follow a consistent verb_noun pattern with snake_case (get_project, get_test_case, list_story_executions, list_story_test_cases, list_test_case_executions, review_story_coverage, search_test_cases). The verbs are appropriately varied (get, list, review, search) and clearly indicate the operation type.
With 7 tools, the server is well-scoped for a read-only Zephyr review interface. Each tool serves a clear purpose without redundancy, covering project lookup, test case retrieval, story-level test listing, execution history (both story and test-case scoped), full coverage review, and project-wide search.
The tool surface fully covers the read-only Zephyr review domain: project metadata, individual test cases (with steps), story-linked tests (lightweight), story executions (pass/fail view), test case execution history (detailed), full coverage bundle (with step quality, cycles, summary), and project-wide search. No obvious gaps for the intended use case.
An MCP server that provides access to Testiny projects, test cases and test runs
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
