--- title: "Xray MCP" canonical: "https://docs.getxray.app/space/XRAYCLOUD/1864335368/Xray%20MCP" format: markdown --- > Macro (rw-ui-expands-macro) > > > Macro (rw-expand) > > > Macro (toc) # Introduction > ℹ️ MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. The Xray MCP Server enables any MCP-compatible agent to work directly with Xray. Your workflows, your way. Simply connect your preferred agent and start incorporating Xray tasks into your agentic workflows within minutes. The MCP Server provides access to 100+ tools based on [Xray’s GraphQL](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565894) and [REST APIs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565892). These tools allow you to work with Xray entities, including creating Tests, updating Test Plans, identifying coverage gaps, and more. Xray Agent Skills provide additional workflows for code generation quality and impact analysis. See [Xray Agent Skills](https://docs.getxray.app/space/XRAYCLOUD/1864335368/Xray+MCP#Xray-Agent-Skills) below for more information. > ⚠️ **Beta Feature** > ⚠️ > ⚠️ The Xray MCP is currently available as a closed Beta feature. Capabilities, tool availability, and behavior may change as the integration evolves, and some limitations may be addressed in future releases. # Configuration Configuration details are currently only accessible to Beta participants. If you are interested in early access or have questions about the Beta, [contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2). # Xray MCP Workflows, Tools, and Skills ## Workflows The Xray MCP grants your agents access to all your Xray data and opens the door to building many custom workflows. Here are a few things you can try among the many possibilities: - Generate Test cases: draft new Tests from a feature description, diff, or user story. ``` Draft Tests for user story XSP-123 and add them to the Checkout folder. ``` - Find coverage gaps: identify code paths with no corresponding Tests before a release. ``` Which API endpoints in this repository have no corresponding Xray Tests? ``` - Submit automation results: write results back after running your automated suite; no manual entry. ``` Push the results from this JUnit XML to run XSP-456. ``` - Plan Test Executions: suggest which Tests to include in a regression run based on what changed. ``` Based on the diff in PR 567, which Tests should go in the regression run? ``` - Analyze execution history: summarize flaky Tests, consistently failing areas, and long-untested Tests. ``` Summarize the flakiest Tests in the last 10 runs of the nightly suite. ``` ## Tools A full list of all available MCP tools and their capability scopes can be found on the Configuration page which is currently only accessible to Beta participants. If you are interested in early access or have questions about the Beta, [contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2). ## Xray Agent Skills With the MCP server connected and the plugin skills installed, there are several powerful workflows you can try first. Each one is a skill the agent runs for you. ### Spec Implementer #### What it Does The Spec Implementer reads your Xray Tests and feeds them directly into your coding agent as structured context. The agent gets the actual acceptance criteria your QA team defined - manual steps, [Gherkin](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565320), or an unstructured definition - so the code it produces is grounded in the real spec, not a guess. #### When to Use It - QA has written Tests for a feature you're about to build. - Right after QA marks a plan as ready for development. - When you want to skip the QA bug-filing cycle. #### What you Get Back - First-attempt implementation aligned with QA. - Inline comments tracing each decision to a Jira key. #### Example - Claude Invocation ``` /xray:spec-implementer Tests for this are in Xray under project XSP, folder "/Login". ``` #### Example - Invocation in Another AI Agent ``` /xray-spec-implementer Tests for this are in Xray under project XSP, folder "/Login". ``` ### Change Evaluator #### What it Does Reads your recent code changes and cross-references them against your Xray Tests. For each Test, it predicts PASS, FAIL, or UNCERTAIN with specific reasoning tied to the exact lines of code that changed. #### When to Use It - Before you push code, not after Tests fail in continuous integration. - After a refactor, to catch regressions early. - When reviewing a PR for Test impact. #### What You Get Back - Risk level: Low / Medium / High. - Impact table sorted FAIL first, with reasoning per Test. - Recommended actions: fix, verify, or update Tests. #### Example - Claude Invocation ``` /xray:change-evaluator Evaluate PR 123 against the Xray Tests in project XSP. Which ones are at risk? ``` #### Example - Invocation in Another AI Agent ``` /xray-change-evaluator Evaluate PR 123 against the Xray Tests in project XSP. Which ones are at risk? ``` ### Regression Preventer #### What it Does Works out what your change can actually reach, then reads the Xray Tests already guarding that surface. Tests are weighed by their recent Test Runs, so a Test that passes today counts for more than one that has never run. It presents a guard rail brief and waits for you to confirm it before writing anything, then implements new code, or repairs code you've already started, so those contracts survive. #### When to Use It - Before or while building in an area existing Tests already cover. - After a refactor touches shared code that many features depend on. - When you want the blast radius before the code, not after continuous integration. #### What You Get Back - A guard rail brief: impact surface, protected contracts, and coverage gaps. - Code annotated with the Jira key of the contract each decision protects. - Deliberate contract changes raised for your decision, never made silently. #### Example - Claude Invocation ``` /xray:regression-preventer I'm adding bulk delete to the Projects API. What existing Xray Tests in project XSP could this break? ``` #### Example - Invocation in Another AI Agent ``` /xray-regression-preventer I'm adding bulk delete to the Projects API. What existing Xray Tests in project XSP could this break? ``` ### Test Importer #### What it Does The Test Importer reads the tests out of a file you already have — a spreadsheet, CSV, Markdown, XML, plaintext, feature files, or existing test code — and creates them as Xray Tests in a Jira project, along with any Test Repository folders they need and any shared Preconditions you ask for. It shows you everything it found first, in the source's own wording, and writes nothing until you choose which ones to import. #### When to Use It - Migrating off spreadsheets, so your Tests live in Xray instead of a shared drive. - When a feature's tests were drafted in a doc or a ticket and never made it into Xray. - When automated tests exist in code but have no Xray Tests behind them. #### What You Get Back - A numbered index of every candidate Test, faithful to the source, so you can take all of them or just a range. - Sign-off on every decision — which Tests, the destination folder, the Test Type, and how the fields map — with nothing written to Xray until you confirm. - Created Tests with their new Jira issue keys — and any failure named with Xray's error, never silently skipped. > ℹ️ Xray creates one Test per API call, so a large selection means a large number of round trips. The plan it shows you before writing states the exact call count, so you can narrow the selection first if that number looks too high. #### Example - Claude Invocation ``` /xray:import ./legacy-cases.xlsx ``` #### Example - Invocation in Another AI Agent ``` /xray-import ./legacy-cases.xlsx ``` # Limitations and Best Practices ## Limitations | **Limitation** | **Guidance** | | --- | --- | | API rate limits | Most of the tools surfaced in this version of the Xray MCP rely on Xray’s existing API endpoints to query Xray data. We are rapidly expanding the API and working on improvements to performance as we uncover more MCP-related use cases. In the meantime, you may experience some delays when using the Xray MCP, especially when your AI agent needs to make multiple sequential API calls while staying within Xray’s API rate limits. To help reduce friction during the Beta, we are temporarily increasing the API rate limit for Beta participants to 400 requests per minute. | | Large folders (500+ Tests) | The AI may try to retrieve all Test you have in your repository, leading to context window issues, performance issues, and high token consumption. Break requests by section or folders to ensure the context is focused. | | Domain-specific business logic | If your feature involves rules not described in the prompt or the Test, the AI will make assumptions, breaking the goal of the closed Beta. Make sure the Tests provided are accurate and well detailed. | ## Best Practices | | | | | --- | --- | --- | | **Principle** | **Bad Example** | **Good Example** | | Be specific - add scope when possible | Find login Tests | List Tests from Space ABC folder “Functional” covering the login landing page and components | | Be intentional | Write Tests for the new checkout flow | Create 10 cucumber Tests covering User Story [Key] to ensure robust functionality of the checkout flow and its new components. Test both positive and negative scenarios and make sure all acceptance criteria are accounted for. | | Reduce requested data | Show all Tests in Test Plan ABC | List the Tests (summary and description fields only) in Test Plan ABC | | Ask to preview bulk/destructive changes | Delete all Tests in the [deprecated] folder | List all Tests in the [deprecated] folder, then delete them once I confirm | > ⚠️ **Data Management Considerations** > ⚠️ > ⚠️ There are **no additional restrictions or safeguards** added to the existing Xray API capabilities when using the MCP Server. Your MCP host will be able to perform **all **Create, Read, Update, and Delete** **actions available to the user who generated the Xray API key. Additionally, there is no built-in “rollback” ability, so **it is advised to use extra caution when taking bulk or destructive actions.** # Troubleshooting | | | | --- | --- | | **Problem** | **What to Check** | | MCP doesn't appear | Restart/reload your agent | | Authentication fails | Check Client ID/Secret | | No Xray data returned | Check API key permissions | | Wrong data region | [Verify Jira data residency](https://docs.getxray.app/space/XRAYCLOUD/44565771/Data+Residency#Viewing-where-your-Jira-Data-is-Hosted) | | Tool times out | Reduce the scope of the request | | Agent retrieves too much data | Narrow the request to a folder/Space/Work item | > Macro (rw-ui-expands-macro) > > > Macro (rw-expand) > > If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577312).