Xray MCP connector

A standalone MCP server that exposes Xray Cloud as tools, so any skill or agent can read run-level results and write test-execution data without bundling curl. Shared by the QA skills:

• test-report-executive-summary, test-status-dashboard, tsr-traceability-reporting — read run-level pass/fail.
• test-execution — write Test Run status and add Tests to a Test Execution at its gated push.

It's a connector, not a skill: install it once and it's available everywhere, exactly like the Atlassian/Playwright MCPs.

Tools

| Tool | Direction | Purpose | |------|-----------|---------| | xray_get_test_run_results | read | Tally PASS/FAIL/TODO (+ pass rate) across Test Executions. | | xray_set_test_run_status | write | Set one Test Run's status (PASSED/FAILED/TODO/…). | | xray_add_tests_to_test_execution | write | Add Tests to a Test Execution. | | xray_graphql | read | Run any Xray GraphQL query (escape hatch). Mutations are rejected. |

All take Xray internal issue IDs (numeric), not Jira keys — resolve keys→IDs via the Jira MCP first. IDs are schema-validated as numeric, so a Jira key is rejected with a clear message rather than a confusing Xray error.

Writes are reachable only through the two write tools. The escape hatch is read-only by construction: a document that doesn't start with query/{, or that contains mutation/subscription, is refused before any request is made. This keeps the read/write split real — an arbitrary-mutation tool would hand any content that reaches the model's context (Jira descriptions, test output, PR bodies) a path to deleteTest and friends.

All caller input travels as GraphQL variables, never interpolated into the query string, so a crafted status or ID cannot append extra root fields to a mutation.

Credentials — from the environment only

Create an Xray Cloud API key (Jira → Xray → Global Settings → API Keys). Export before launching Claude — never commit them or paste them into a chat:

export XRAY_CLIENT_ID='...'
export XRAY_CLIENT_SECRET='...'

The server reads them from the environment, fetches a bearer token on demand, caches it in memory, and never logs the token or the secret. See .env.example.

Install

Published on the public npm registry as xray-mcp-connector. No registry auth needed — teammates just run the command below.

1. Register with Claude Code

claude mcp add -s user xray -- npx -y xray-mcp-connector

Or via .mcp.json (project or user scope) — do not put secrets here; they come from your shell env or .env:

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "xray-mcp-connector"]
    }
  }
}

Pin a version for reproducible behaviour across the team: npx -y [email protected].

2. Supply your own Xray key

npx runs the package from a cache directory, so there is no .env to edit in the installed package. Pick one of these.

Recommended — pass them at registration. Works no matter how Claude is launched (terminal or desktop app), because Claude injects them into the server process directly:

claude mcp add -e XRAY_CLIENT_ID=your-id -e XRAY_CLIENT_SECRET=your-secret -s user xray -- npx -y xray-mcp-connector

Note the flag order: at least one other option (-s user here) must sit between the last -e and the server name, or the CLI reads the name as another KEY=value pair and rejects it. The values are stored in plaintext in ~/.claude.json — same exposure class as a .env file, so treat that file as secret and never copy it around.

Alternative — shell environment. Export in ~/.zshrc / ~/.bashrc:

export XRAY_CLIENT_ID='...'
export XRAY_CLIENT_SECRET='...'

Only works when Claude is started from a terminal that sourced your profile. A desktop app launched from Finder or the Dock will not see these.

Alternative — shareable .mcp.json with no secrets in it. Commit this; each person supplies the values via their own shell environment:

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "xray-mcp-connector"],
      "env": {
        "XRAY_CLIENT_ID": "${XRAY_CLIENT_ID}",
        "XRAY_CLIENT_SECRET": "${XRAY_CLIENT_SECRET}"
      }
    }
  }
}

If a variable is unset and has no ${VAR:-default} fallback, the config still loads but claude mcp list reports a missing-variable warning and the literal ${VAR} text is passed through — so the connector will report absent credentials rather than fail mysteriously.

Alternative — project .env. The connector also reads .env from the directory Claude was launched in, so an existing gitignored project .env works unchanged.

Then restart Claude and confirm:

claude mcp get xray

Install — Claude Desktop app

Claude Desktop does not use claude mcp add or .mcp.json, and it has no shell environment to inherit from. It reads one JSON file, and credentials must go in that file's env block.

1. Claude menu → Settings → Developer → Edit Config. (The Claude menu in the OS menu bar, not the in-window settings.) That opens, or creates:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server, with your own key:

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "xray-mcp-connector"],
      "env": {
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

${VAR} expansion is a Claude Code feature and does not work here — the values must be literal. That makes this file secret: it sits outside any repo, so keep it there and never paste it into a ticket or chat.

3. Quit Claude Desktop completely and reopen it. Reloading the window is not enough. The connector then appears under the / indicator → Connectors → Manage connectors.

If it doesn't connect

Read the server's own stderr — the connector logs its startup line and any credential error there:

tail -n 30 -f ~/Library/Logs/Claude/mcp-server-xray.log

On Windows: type "%APPDATA%\Claude\logs\mcp-server-xray.log".

Two failure modes worth knowing:

• ENOENT / npx not found, most often on Windows launched from the GUI. Confirm %APPDATA%\npm exists; if not, run npm install -g npm. If the log mentions a literal ${APPDATA} in a path, add "APPDATA": "C:\\Users\\<you>\\AppData\\Roaming\\" to the same env block.
• Credentials not set. Means the env block is missing or misspelled — Claude Desktop passes nothing else through.

Publishing a new version (maintainer only)

npm version patch          # or minor / major
npm publish                # publishConfig pins the registry
git push --follow-tags

Local development (from a clone)

npm install
claude mcp add -s user xray-dev -- node "$PWD/src/index.mjs"

install.sh / install.bat automate this clone-based path; they are not part of the published package.

Behaviour / safety

• Read-only tools never write. Write tools (set_test_run_status, add_tests_to_test_execution) are used by test-execution only at its confirmed, gated push.
• No secrets in output or logs — auth failures report status codes, not bodies; the token is never printed.
• TLS verification is never disabled.
• Requests time out after 30 s (XRAY_REQUEST_TIMEOUT_MS to override) — a hung Xray fails the tool instead of stalling it.
• Token recovery — a rotated or revoked API key returns 401; the connector drops the cached token and retries once instead of failing every call until restart. Concurrent calls on a cold start share a single /authenticate.
• Pagination is honest — the run tally pages until a short page arrives and reports truncated if it ever hits the page ceiling, so a partial read can never masquerade as a complete one.
• Output is capped at 50 000 characters (XRAY_MAX_OUTPUT_CHARS to override) so one wide GraphQL response can't swallow the caller's context. A capped result says plainly that it is incomplete and not valid JSON, rather than looking like a whole answer.
• If credentials are absent, tools return a clear error — consumers fall back to counts-only / manual, never fabricate.

Credentials are per-person

Each teammate uses their OWN Xray API key — never share yours, and never paste one into a chat or a ticket. The package ships no credentials: files in package.json is an allowlist of src/, README.md and .env.example, so .env cannot reach the registry even by accident. Verify any release with npm pack --dry-run before publishing.

Credentials are resolved in this order, first match wins:

1. Shell environment (XRAY_CLIENT_ID / XRAY_CLIENT_SECRET) — use this for an npx install.
2. .env next to the connector, then src/.env, then .env in the directory Claude was launched from.

If you ever commit or share a real key, treat it as compromised and rotate it in Jira immediately.

Requirements

Node ≥ 18 (uses global fetch). Deps: @modelcontextprotocol/sdk, zod.