Claude MCP Connector

QAID ships a Model Context Protocol (MCP) connector that lets Claude — running in Claude Desktop or Claude Code — drive your QAID instance directly. Claude can explore your crawled pages, author tests from plain English intent, run test plans, and review heal proposals, all grounded in your project's real crawl data and prior heals.

What MCP is, in one paragraph

MCP is a standard for plugging tools into AI assistants. A connector exposes a set of named tools the assistant can call; the assistant decides when and how to call them. QAID's connector exposes 20 tools spanning the full test lifecycle. It runs locally on your machine and talks to your QAID instance using the same /api/v1 public API and qaid_ token you'd use from a script — so it works with QAID's single-tenant / private-network deployment without exposing anything to the public internet.

Who it's for

Developers and QA engineers who use Claude Desktop or Claude Code and want their assistant to read your real selectors and write tests grounded in them, rather than guessing.
Teams running QAID inside a VPC. The connector runs on your own machine and only talks to your QAID URL with your token — Anthropic's servers never see your QAID instance.
Anyone who wants the heal loop to compound. Heals you approve through Claude feed into QAID's cross-test knowledge base, so the next authoring session gets smarter.

Install

There are three paths. Pick the one that matches your client.

A — Claude Desktop (one-click bundle)

This is the easiest path.

Get qaid-mcp.mcpb from your QAID release assets.
Open the .mcpb file with Claude Desktop. Claude treats it as a Desktop Extension and walks you through install.
When prompted, enter:
- QAID URL — your QAID instance origin, e.g. https://qaid.acme.internal (no /api/v1, no trailing slash).
- QAID API token — a qaid_ token (see API Tokens and scopes below).
Done. Claude can now call QAID tools.

B — Claude Code (CLI)

claude mcp add qaid \
  --env QAID_API_URL=https://qaid.acme.internal \
  --env QAID_API_TOKEN=qaid_xxx \
  -- npx -y @qaid/mcp

Until @qaid/mcp is published to npm, point command/args at a local dist/index.js build (node /abs/path/to/qaid-mcp/dist/index.js) instead of the npx -y @qaid/mcp form.

C — Manual config (any MCP client)

{
  "mcpServers": {
    "qaid": {
      "command": "npx",
      "args": ["-y", "@qaid/mcp"],
      "env": {
        "QAID_API_URL": "https://qaid.acme.internal",
        "QAID_API_TOKEN": "qaid_xxx"
      }
    }
  }
}

Config can also be passed as flags instead of env vars: --api-url, --api-token.

API tokens and scopes

The connector talks to QAID with a qaid_ API token you provide. Create one from Account → API Tokens in QAID. Tokens are deny-by-default — they only do what their granted scopes allow.

The scopes you'll typically want for the MCP connector:

Scope	What it unlocks
`projects:read`	List the projects the token can see (`qaid_whoami`, `qaid_list_projects`)
`pages:read`	List pages and read crawled elements for grounding (`qaid_list_pages`, `qaid_get_page_elements`)
`crawl:read` / `crawl:write`	Poll crawl jobs / trigger new crawls from Claude
`tests:read` / `tests:write`	List, read, author, update test cases (`qaid_author_test`, `qaid_author_status`, `qaid_get_test_learnings`, `qaid_suggest_tests`, `qaid_get_suggestions`)
`plans:read` / `plans:write`	List test plans / create new ones (`qaid_list_test_plans`, `qaid_create_test_plan`)
`runs:read` / `runs:write`	Read run status / queue + cancel test plan runs
`results:read`	Read per-test run outcomes and diagnoses (`qaid_run_results`)
`heal:read` / `heal:write`	List heal proposals / approve or reject them

If Claude calls a tool the token's scopes don't cover, the connector returns an actionable error explaining which scope is missing. The simplest path is to grant all of the above when you're exploring; tighten later if you want a narrow-purpose token.

You can scope the token to a specific project, or leave it organization-scoped so Claude can switch between projects mid-conversation.

What Claude can do (20 tools)

Tools are grouped by where they sit in the test lifecycle.

Discover & ground

These let Claude orient itself in your QAID instance before authoring.

qaid_whoami — Returns the caller's identity, projects, and effective scopes.
qaid_list_projects — Lists projects the token can see.
qaid_list_pages — Lists crawled pages for a project (path, title, page status).
qaid_get_page_elements — Returns the real crawled selectors for a page — the same selectors QAID uses internally for zero-hallucination authoring.
qaid_get_test_learnings — Returns prior heal corrections for the project. Claude uses this to avoid repeating fixes QAID already learned.
qaid_start_crawl / qaid_get_crawl_status — Trigger and poll a new crawl when pages need refreshing.

There's also a resource — qaid://guide/authoring — that Claude reads automatically to learn QAID's authoring conventions.

Author tests

qaid_author_test — The core authoring tool. Takes plain-English intent ("Test that a logged-in user can add an item to cart") and returns a grounded, self-healing test. Claude doesn't write selectors — QAID resolves selectors against the live crawl and bakes in the same defensive runtime behavior the recording flow uses.
qaid_author_status — Poll authoring progress for long-running generations.
qaid_suggest_tests / qaid_get_suggestions — Ask QAID to suggest test scenarios for a page; ephemeral suggestions become durable tests only after Claude approves one via qaid_author_test.

Run

qaid_create_test_plan / qaid_list_test_plans — Organize tests into a runnable plan.
qaid_run_start — Queue a test plan run.
qaid_run_status — Poll the run's overall status.
qaid_run_results — Read per-test outcomes (pass/fail/skipped) and diagnoses.
qaid_run_cancel — Stop a running plan.

Heal

qaid_list_heal_proposals — Pending heals awaiting user review (the same ones surfaced as "Review fix" badges in the UI).
qaid_approve_heal — Approve a heal. The applied selector lands in the test, and the correction feeds the cross-test knowledge base so the next similar break heals faster.
qaid_reject_heal — Reject; the heal is dropped and not used by the knowledge base.

The loop

The connector's value isn't any single tool — it's the loop:

Ground on real crawled selectors and prior per-project heals.
Author from intent. QAID resolves selectors against the live crawl, not Claude's guess.
Run the test plan.
Review and approve heals. Approvals make the next authoring + heal step smarter for this project.

Per-project accuracy compounds the more you use the connector.

Security model

Local execution. The connector runs as a local process on your machine. Anthropic's cloud never directly sees your QAID URL or token.
Private network safe. The connector talks to your QAID instance over the URL you provide — typically a VPC-internal address. QAID does not need to be reachable from the public internet.
Token never logged. Your QAID_API_TOKEN is sent only to your QAID and is not written to logs.
Deny-by-default scopes. Whatever Claude can't do via the token's scopes, it can't do at all. Mint narrow-scoped tokens for narrow tasks.
Remote/web connector (claude.ai) is not supported by default. claude.ai connectors reach in from Anthropic's cloud, and QAID is built private-network-first. A customer who deliberately exposes QAID over public HTTPS could add a Streamable-HTTP transport + OAuth; the connector's core is transport-agnostic to keep that option open, but it's not something QAID ships turnkey.

Common workflows

"Author a test that does X"

Ask Claude something like "Write a test that logs in as a Pro user and exports analytics as CSV." Claude will typically:

Call qaid_list_pages to find the login and analytics pages.
Call qaid_get_page_elements on each to ground in real selectors.
Call qaid_get_test_learnings to see prior heals for that project.
Call qaid_author_test with your intent; QAID resolves selectors and emits the spec.
Poll qaid_author_status until done.

"Run yesterday's regression plan and tell me what broke"

Ask "Run our regression test plan and summarize the failures." Claude will typically:

qaid_list_test_plans to find the right plan.
qaid_run_start to queue it.
Poll qaid_run_status until completed.
qaid_run_results to read per-test outcomes.
For failures with a parked heal, suggest reviewing via qaid_list_heal_proposals + qaid_approve_heal.

"Review pending heals"

Ask "Show me the pending heal proposals and walk me through each." Claude calls qaid_list_heal_proposals, summarizes each one in plain English, and waits for your call on qaid_approve_heal / qaid_reject_heal.

Troubleshooting

"Missing scope" error from a tool call

Your token doesn't have the scope that tool requires. Mint a new token from Account → API Tokens with the scope listed in the error, or grant it to the existing token.

Claude can't reach my QAID instance

Confirm QAID_API_URL has no /api/v1 suffix and no trailing slash (just the origin).
If QAID is in a VPC, confirm your local machine can reach that URL — the connector runs on your machine, not in Anthropic's cloud. Try curl https://qaid.acme.internal/api/v1/me -H "Authorization: Bearer qaid_xxx" from the same machine.
If you use a corporate proxy, ensure it's exported as HTTPS_PROXY for the shell that launches the MCP client.

Authoring returns "no real selectors for that intent"

QAID author refuses to invent selectors — that's the zero-hallucination guarantee. The page hasn't been crawled, or the elements you're targeting weren't captured. Have Claude call qaid_start_crawl for that page (or do it from the QAID UI), then re-run authoring.

The `.mcpb` bundle won't open

Claude Desktop is what opens .mcpb files. If you're seeing a generic file dialog instead, install or update Claude Desktop. The bundle format is the Desktop Extension standard.

Settings — Where to mint API tokens
Scenario Tests — How the same authoring engine works inside QAID

Claude MCP Connector

On this page