
simplify3x-connect
com.simplifyqa/simplify3x-connect
SimplifyQA test management: find, author, record, run and triage test cases.
Documentation
simplify3x-connect
One product-neutral MCP that any AI client (Claude Code, Cursor, Windsurf, VS Code, Codex, Devin) connects to with a URL + token to drive the whole test-case lifecycle — discover · author · record · run · triage — against Walnut or SimplifyQA. The client sees one tool vocabulary regardless of the product behind it.
- npm:
simplify3x-connect - MCP Registry:
com.simplifyqa/simplify3x-connect - Privacy policy · Terms · Support
Quick install
You need your SimplifyQA URL and an API token from your SimplifyQA profile.
Claude Code (plugin, prompts for URL and token):
/plugin install simplify3x-connect --marketplace Simplify3x/simplify3x-connect
Or from your shell:
claude plugin marketplace add Simplify3x/simplify3x-connect
claude plugin install simplify3x-connect@simplify3x
Claude Desktop: download simplify3x-connect-0.28.1.mcpb and double-click it, or use Settings → Extensions → Install extension. Enter your URL and token when asked. No Node.js or npm needed.
Codex CLI:
codex mcp add simplify3x-connect --env QA_MCP_PROVIDER=simplifyqa --env QA_BASE_URL=https://<your-simplifyqa> --env QA_MCP_TOKEN=<your-token> -- npx -y simplify3x-connect
Cursor, VS Code, Windsurf, Devin and others: add the JSON config in Install below to
the client's MCP settings, with QA_MCP_PROVIDER set to simplifyqa.
Install
Nothing to clone or build — clients launch it over stdio with npx. Requires Node ≥ 20.
Add it to your client's MCP config (.mcp.json for Claude Code / Cursor / Windsurf):
{
"mcpServers": {
"simplify3x-connect": {
"command": "npx",
"args": ["-y", "simplify3x-connect"],
"env": {
"QA_MCP_PROVIDER": "walnut",
"QA_BASE_URL": "https://<your-backend>",
"QA_MCP_URL": "http://127.0.0.1:4050/mcp",
"QA_MCP_TOKEN": "<your-token>",
"QA_MCP_PROJECT_ID": "<optional-project-id>"
}
}
}
}
| Env var | Required | Purpose |
|---|---|---|
QA_MCP_PROVIDER | — | walnut (default) or simplifyqa. |
QA_BASE_URL | ✓* | Product backend REST — drives discover / author / run / triage (no agent needed). |
QA_MCP_URL | ✓* | Your local agent's /mcp — adds recording + journal editing (browser / mainframe). |
QA_MCP_TOKEN | ✓ | Raw auth token (JWT — no Bearer prefix). |
QA_MCP_PROJECT_ID | — | Pin a default project; omit and you'll be asked (change anytime with qa_switch_project). |
* Set QA_BASE_URL for the lifecycle over direct REST, and QA_MCP_URL to add recording.
Set both for the full experience, or only QA_BASE_URL for a zero-agent setup (no recording).
With neither set it starts offline — draft authoring only — and you connect later from chat
with qa_connect.
Recording (
web/mainframe/mobile) runs on the local agent, soQA_MCP_URLmust point at a running agent.
Run it as a server (HTTP)
The stdio entry is for a single developer's client. To serve several clients from one machine or a container, run the gateway:
npm run build
HOST=0.0.0.0 PORT=4060 npm run start:http
# simplify3x-connect gateway ready on http://0.0.0.0:4060/mcp
# health: http://0.0.0.0:4060/health ready: http://0.0.0.0:4060/ready
Point any Streamable-HTTP MCP client at http://<host>:4060/mcp.
Authentication
Two independent controls, because they answer different questions:
| Variable | Answers | Effect |
|---|---|---|
QA_MCP_GATEWAY_TOKEN | may this caller reach the MCP at all? | shared secret; /mcp rejects anything else with 401 + WWW-Authenticate |
QA_MCP_REQUIRE_CLIENT_TOKEN=true | who is this caller in the product? | every request must carry its own product token (Authorization / x-qa-token), and the session connects with it |
With per-user mode on, put the gateway secret in x-gateway-token so it does not collide with the
product token in Authorization.
Nothing secret is ever logged. mask() reports only whether a token is set, every line written by
the shared log() sink is pattern-redacted (Bearer credentials, JWTs, provider API keys,
token=/password= forms), and the resolved token is registered with the file logger so even a raw
WALNUT_LOG_FILE line cannot contain it. DEBUG=1 goes through the same redaction.
Each MCP session gets its own connection and adapter. One user's qa_connect, project switch or
token can never affect another session — the behaviour that made a shared gateway unsafe. The draft
store is still shared so a draft survives a reconnect.
Restrict where the server may call
QA_MCP_ALLOWED_HOSTS=sqa.corp.example,agent.corp.example limits both the startup configuration and
every runtime qa_connect to those hosts (subdomains included). Without it, a client can point the
gateway at any address through baseUrl / url, which is a server-side request forgery risk on a
shared deployment.
Running more than one replica
The HTTP transport is stateful: sessions and drafts live in memory, so run a single replica or use
sticky routing keyed on mcp-session-id. Idle sessions are evicted after
QA_MCP_SESSION_TTL_MS (default 30 minutes), and a hard cap of QA_MCP_MAX_SESSIONS (default 200)
drops the least recently used. Request bodies are capped by QA_MCP_MAX_BODY_BYTES (1 MB).
Behind a proxy, disable response buffering for the SSE stream (proxy_buffering off,
X-Accel-Buffering: no, a read timeout of at least five minutes). GET /mcp without a session
returns 404 by design so a client re-initializes; use /health and /ready for probes, never /mcp.
Install the QA agent (optional)
Drops a QA persona + tool guidance into your project so the client knows how to drive these tools:
npx simplify3x-connect init-agents --loop=claude # claude | cursor | windsurf | vscode | codex | devin | all
# --server-name <name> # must match your MCP server name (default: simplify3x-connect)
Use it
Reload your client, then drive it in plain language:
- "List my projects" → "switch to project X"
- "Record a login test on web" → answer the setup questions → review the draft → "save it"
- "Run TC_123 on cloud" · "show me the login stories" · "add a loop around steps 3–5 of TC_42"
simplify3x-connectnpm install simplify3x-connect