@qcentriq/mcp

Official Model Context Protocol (MCP) server for QCentriq automated test discovery, error diagnostics, script retrieval, and local test execution.

Connect your AI coding assistants (Cursor, Claude Desktop, VS Code Cline / Roo Code, Windsurf, Zed, or Gemini / Antigravity) directly to your QCentriq QA projects to inspect test cases, analyze failure logs, retrieve Playwright test scripts, and validate fixes locally.

⚡ Highlights

• Remote Cloud Discovery & Diagnostics: Instantly query test cases, groups, run logs, failure stack traces, and environment variables via authenticated REST client endpoints.
• Local Playwright Test Execution: Safely execute tests locally with pytest without triggering unwanted cloud runners. Supports headless and headed modes across Chromium, Firefox, and WebKit.
• Smart Environment Setup: Probes installed local Python package managers (uv, poetry, conda, or standard venv) and generates ready-to-run setup commands (prefers uv for lightning-fast setup).
• Direct Workspace Script Saving: Download test scripts and their helper files into a dedicated qcentriq_tests/ workspace directory (kept apart from your own tests/, so an existing conftest.py is never overwritten). Before each local run there, qcentriq_run_local_test refreshes the conftest.py QCentriq cloud runs use with path traversal protections.
• Zero-Leak Redaction: Automatically filters all outgoing tool payloads, masking API keys (qc_...), bearer tokens, and URL credentials before sending them to the LLM.
• Strict Stdio Isolation: Protocol JSON-RPC frames communicate cleanly over stdout, while all diagnostic logs route to stderr.

🚀 Quick Start

Using npx (No installation needed)

Launch the MCP server directly using npx:

npx -y @qcentriq/mcp@latest --api-key "qc_your_api_key_here"

Or pass your configuration via environment variables:

export QCENTRIQ_API_KEY="qc_your_api_key_here"
export QCENTRIQ_BASE_URL="https://api.qcentriq.com" # Optional, defaults to production
export QCENTRIQ_PROJECT_ID="your-project-uuid"      # Optional default project ID

npx -y @qcentriq/mcp@latest

Global Installation

npm install -g @qcentriq/mcp
qcentriq-mcp --api-key "qc_your_api_key_here"

📋 CLI Options & Environment Variables

⚙️ Assistant Configuration Guides

1. Claude Desktop

Add QCentriq to your configuration file:

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

{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com",
        "QCENTRIQ_PROJECT_ID": "optional-default-project-uuid"
      }
    }
  }
}

2. Cursor IDE

In Cursor, open Settings $\to$ Features $\to$ MCP Servers $\to$ Add New MCP Server, or edit ~/.cursor/mcp.json (or .cursor/mcp.json in your repository root):

{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com"
      }
    }
  }
}

3. VS Code (Cline / Roo Code)

In VS Code with the Cline or Roo Code extension, open cline_mcp_settings.json:

{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      },
      "disabled": false,
      "autoApprove": [
        "qcentriq_list_tests",
        "qcentriq_get_test",
        "qcentriq_get_test_groups",
        "qcentriq_get_test_run_logs"
      ]
    }
  }
}

4. Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      }
    }
  }
}

5. Zed

In your Zed settings.json (under experimental.context_servers):

{
  "context_servers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      }
    }
  }
}

6. Gemini / Antigravity IDE

In ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in workspace):

{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com"
      }
    }
  }
}

7. Claude Code CLI

Add the QCentriq MCP server using the Claude CLI:

claude mcp add qcentriq -- npx -y @qcentriq/mcp@latest --api-key "qc_your_api_key_here"

🎭 Add Playwright MCP for writing tests (recommended)

Before writing a test plan or script, the assistant is told to explore your app in a real browser with the Playwright MCP server. That way, URLs, labels and selectors come from the pages themselves instead of guesses. QCentriq MCP cannot call Playwright MCP itself, so add it to the same client next to qcentriq:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

With Claude Code: claude mcp add playwright -- npx @playwright/mcp@latest. If Playwright MCP is not connected, the assistant should say so before it writes a plan.

Sites behind HTTP basic auth (common on staging) answer 401 with a blank page until the browser logs in. The assistant is told to notice this and continue on its own. It takes the credentials from your request, or from the environment's BASIC_AUTH_USERNAME / BASIC_AUTH_PASSWORD variables (or the keys that QCENTRIQ_BASIC_AUTH_USERNAME_KEY / QCENTRIQ_BASIC_AUTH_PASSWORD_KEY name). Then it reopens the site with them in the URL, and Chromium remembers them for the rest of the session. It asks you only when the credentials are stored as secrets, because QCentriq never sends secret values to the assistant. To avoid that question, give Playwright MCP the credentials up front by starting it with --config playwright-mcp.json:

{
  "browser": {
    "contextOptions": {
      "httpCredentials": { "username": "staging-user", "password": "staging-password" }
    }
  }
}

Scripts never contain the credentials. The conftest.py QCentriq ships applies them from BASIC_AUTH_USERNAME / BASIC_AUTH_PASSWORD, which the assistant passes to qcentriq_run_local_test in env_vars for local runs.

🛠️ Available MCP Tools

The QCentriq MCP Server cleanly separates remote cloud discovery/diagnostics (connected via authenticated REST endpoints to /api/v1/mcp-client/) and local client operations (executed purely inside your machine's local workspace):

🌐 Remote Discovery & Diagnostics (Cloud REST Endpoints)

✍️ Authoring (Cloud REST Endpoints, writes require test:write)

The intended order is: qcentriq_get_authoring_guide and qcentriq_get_environment, then explore the app with Playwright MCP, then qcentriq_create_plan, then write the script, run it with qcentriq_run_local_test until it passes, and upload it with qcentriq_save_group_script. The server sends this order to the assistant as its MCP instructions.

Both write tools send to QCentriq as soon as they are called; your MCP client's own tool-approval prompt is the check before an upload (see Security & Privacy).

💻 Local Client Tools (Executed in Your Local Workspace)

🔄 End-to-End AI Self-Healing Workflow

Here is how an AI assistant (e.g. Cursor or Claude) uses @qcentriq/mcp to diagnose and fix a failing test:

sequenceDiagram
    autonumber
    actor User
    participant AI as AI Assistant
    participant MCP as QCentriq MCP Server
    participant API as QCentriq Cloud API
    participant Local as Local Workspace & Subprocess

    User->>AI: "Fix the failing login test in QCentriq"
    AI->>MCP: qcentriq_list_tests(priority="high")
    MCP->>API: GET /api/v1/mcp-client/tests
    API-->>MCP: Test cases metadata
    MCP-->>AI: List of tests

    AI->>MCP: qcentriq_get_test_run_logs(test_case_id="...")
    MCP->>API: GET /api/v1/mcp-client/tests/{id}/run-logs
    API-->>MCP: Failure trace (e.g. SelectorTimeoutError)
    MCP-->>AI: Error diagnostics & stack trace

    AI->>MCP: qcentriq_get_setup_instructions()
    MCP-->>AI: Recommended setup commands (uv venv, uv pip install ...)

    AI->>MCP: qcentriq_download_script(group_id="...")
    MCP->>API: GET /api/v1/mcp-client/groups/{id}/script
    API-->>MCP: Script & helper files
    MCP->>Local: Write qcentriq_tests/test_login.py
    MCP-->>AI: File paths confirmed

    AI->>Local: Inspect and update selector in test_login.py
    AI->>MCP: qcentriq_run_local_test(file_path="qcentriq_tests/test_login.py", headless=false)
    MCP->>Local: Run pytest with Playwright
    Local-->>MCP: Test result (PASSED)
    MCP-->>AI: PASSED (exit code 0, 1.42s)
    AI->>User: "Fixed selector in qcentriq_tests/test_login.py and verified locally!"

🔒 Security & Privacy

• Safe Network Boundary: The client MCP server connects exclusively to ${baseUrl}/api/v1/mcp-client/ using HTTPS. Discovery and diagnostics tools only read. The authoring tools qcentriq_create_plan, qcentriq_update_test_case, qcentriq_save_group_script and qcentriq_recheck_blocked_case write to your project (creating and editing test groups/cases, replacing a group's script, and unblocking a case when QCentriq's live recheck confirms it works), and the backend rejects them unless the API key carries the test:write scope.
• Local Pass Before Upload: qcentriq_save_group_script refuses a script unless that exact content passed qcentriq_run_local_test in the current server session, as a whole file: no test_name, node id, or -k/-m/--deselect/--lf-style filters, and at least one test passed (not all skipped). Each companion file must match the file that sat next to the script during that run and not have changed since. Passing runs are kept in memory, so after a restart the script has to be run again. If no Python package manager is installed, the refusal says to install uv first (recommended), then use qcentriq_get_setup_instructions.
• Client-Side Control: Test executions, script modifications, and environment setups happen locally on your machine. No local code or files are uploaded without your knowledge.
• Zero-Leak Redaction: The server actively scans and redacts API keys (qc_...), bearer tokens, and embedded basic-auth credentials before returning data to the LLM.
• Filesystem Security: Path traversal attacks (e.g. ../../etc/passwd) are blocked when writing test scripts and fixtures to disk.
• Stdio Integrity: All server diagnostic logs are strictly routed to stderr. Standard output (stdout) is reserved purely for JSON-RPC 2.0 communication.

💻 Local Development

# Clone the repository
git clone https://github.com/qcentriq/qcentriq.git
cd packages/qcentriq-mcp

# Install dependencies
npm install

# Run typecheck
npm run typecheck

# Run test suite
npm test

# Build production bundle with tsup
npm run build

# Run local development server with live reload
QCENTRIQ_API_KEY="qc_your_key" QCENTRIQ_BASE_URL="http://localhost:8787" npm run dev

📄 License

Apache-2.0 © QCentriq