MCP server
agent-qa's Model Context Protocol server, its 20 tools and resources, and how to run it over stdio or HTTP.
The agent-qa MCP server lets any MCP client write tests, run them, read the evidence, correct verdicts and manage knowledge. It runs on your machine, in your project, with your config.
Start it
| Transport | Command | Use it when |
|---|---|---|
| stdio | npx agent-qa mcp | The client starts and stops the server itself, like Claude Code and Codex. |
| HTTP | npx agent-qa mcp --http | The client connects to a server you keep running. Listens on http://127.0.0.1:3471/mcp. Pass a port to change it: --http 4000. |
npx agent-qa mcp --httpThe server reads agent-qa.config.yaml from the folder it starts in, or from the nearest folder above it that has one. Pass another file with npx agent-qa --config <path> mcp. Without a config, or with one that does not validate, the server still starts, and every tool answers not_initialized or config_invalid until you run npx agent-qa init or fix the config, then restart the server. The HTTP server listens on 127.0.0.1 only, rejects requests from other hosts and sites, and uses no tokens.
npx agent-qa init writes the server's entry for Claude Code and Codex, with a long tool timeout. Coding agents shows what it writes, and how to add the server to other clients.
Tools
Every tool name starts with agent_qa_. Tools that write apply their change in the call; there is no confirmation step.
Tests
| Tool | What it does |
|---|---|
agent_qa_write_test | Writes a test for an intent in plain words. It drafts the test, runs it, checks it is stable and has real checks, and writes the file unless a check rejects it. |
agent_qa_refine_test | Edits an existing test (action: authoring.draft.edit, with testRef and intent) or checks a draft (action: authoring.draft.verify, with draftPath). |
Runs
| Tool | What it does |
|---|---|
agent_qa_start_run | Runs the tests matching patterns. Answers with the run ID once the run has finished. |
agent_qa_list_runs | Lists finished runs, newest first, filtered by verdict, test, since and limit. |
agent_qa_get_run_digest | Summarizes a run: verdicts by cause, post-run status and marks. |
agent_qa_get_run_overview | Maps a run: tests, steps, evidence, screenshots and knowledge. |
agent_qa_get_run_evidence | Reads one step's evidence (action: runs.evidence, with kind console, network, a11y, aria or variables), or returns a screenshot as an image (action: runs.artifact, with sha). |
agent_qa_get_run_knowledge | Shows what a run was given and what it changed in memidex. |
Feedback
| Tool | What it does |
|---|---|
agent_qa_mark_run | Marks a verdict false-fail, false-pass or confirmed-bug, and applies the fix. See Mark a run. |
agent_qa_preview_run_mark | Shows what a mark would do, without writing. |
agent_qa_get_run_marks | Lists every mark on a run and what each changed. |
Knowledge
| Tool | What it does |
|---|---|
agent_qa_list_knowledge_bundles | Lists every record with its trust and status. |
agent_qa_inspect_knowledge_records | Filters records by product, scope, kind, status, anchor or run count. |
agent_qa_show_knowledge_record | Shows one record and where it came from. |
agent_qa_diff_knowledge_records | Lists changes since a run count. |
agent_qa_list_knowledge_gates | Shows the marks and approvals behind a record, and whether it would promote. |
agent_qa_explain_brief | Explains what a step's brief said, and why. |
agent_qa_change_knowledge | Accepts, rejects (with a reason) or forgets a record. |
Config and lookup
| Tool | What it does |
|---|---|
agent_qa_change_config | Sets a config field, adds or edits a web target, adds the subscription sign-in plugin, adds a hook, or sets up a project for a site. It never changes registry.remotes or other plugins entries. |
agent_qa_get_entity | Finds a test, run or record from a short ID, an agentqa:// URI or free text, and returns its card. |
Every client can see and call all 20 tools. Their full input schemas arrive with tools/list.
Resources
Entities are also MCP resources, addressed by URI:
| URI | Points at |
|---|---|
agentqa://test/{id} | A test |
agentqa://run/{id} | A run |
agentqa://memory/{id} | A knowledge record, such as MEM-001 |
agentqa://policy/{id} | A policy |
agentqa://target/{id} | A target |
The server has no prompts. When a client connects, it sends short instructions pointing to these tools and asking the client to read data through them, never from .agent-qa/ or the knowledge index.
Not on MCP
Some functions are available only from the CLI, with agent-qa fn <id>, or from chat: conversations, quarantine, the full config read and run event streams. agent_qa_start_run cannot cancel a run; stop it where it started.
Links to the dashboard
Results that mention a run end with a link to it when services.dashboard.baseUrl is set in your config. Without it they say no dashboard is configured.
When your config declares a services.mcp block, agent-qa dashboard also serves MCP on services.mcp.port, 3471 by default. That endpoint adds a live view of a running test for clients that can display MCP apps. Both cannot use port 3471 at once, so run either it or agent-qa mcp --http.