> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.qa.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.qa.army/_mcp/server.

# QA.army MCP

> Connect a local MCP client, maintain saved Tests, and inspect Runs with the same account authorization as the CLI.

QA.army MCP is the agent-native interface for discovering Projects, managing
saved Tests, operating Runs, and reading results through structured tools.

## Connect a local client

Install the reviewed MCP package from the
[official releases](https://github.com/QA-army/mcp/releases):

```sh
npm install --global https://github.com/QA-army/mcp/releases/download/v0.1.4/venkat-mcp-0.1.4.tgz
```

Node.js 22 or newer and your operating system's credential store are required.
Configure your MCP client to launch `venkat-mcp` as a local stdio server. For
clients that use an `mcpServers` configuration:

```json
{
  "mcpServers": {
    "qa-army": {
      "command": "venkat-mcp",
      "args": []
    }
  }
}
```

Complete [CLI authorization](/interfaces/cli) once with
`qa-army auth agent-register --email you@example.com`. MCP reuses that existing
claimed identity; you do not need to export a token, create a second API key,
or sign in again. Both interfaces refresh the same stored credential safely.
Keep the native credential store available to the process running MCP.

Hosted MCP connections and a separate MCP browser sign-in are unavailable.
The `venkat-mcp` executable is the published QA.army adapter's compatibility
name, not a separate service. Do not copy access tokens into MCP client config.

## Who uses MCP

| Reader or operator                     | Why                                                | When                                     |
| -------------------------------------- | -------------------------------------------------- | ---------------------------------------- |
| Coding agents sponsored by the CTO     | Turn a code change into focused QA work            | During implementation and review         |
| Product agents sponsored by the CPO    | Review saved coverage and propose missing journeys | During planning and release acceptance   |
| Marketing agents sponsored by the CMO  | Protect acquisition and conversion journeys        | Before campaign or site releases         |
| Operations agents sponsored by the COO | Check critical journeys across Projects            | During operational review and escalation |
| CIO and security teams                 | Govern which agents may reach Workspace data       | During connection approval and audit     |

MCP is normally used by an agent on a person's behalf. It does not create a new
type of Workspace member.

## Tool families

The current interface defines structured tools for:

* `workspaces.*` — discover and create authorized Workspaces with a claimed identity;
* `projects.*` — list and create Web or Mobile Projects;
* `groups.*` — organize durable journey families;
* `tests.*` — create, read, and update saved Tests;
* `runs.*` — create, read, start, watch, cancel Runs, and list finalized evidence; and
* `prs.watch` and `prs.watch_update` — read and update an existing connected GitHub deployment watch as a Workspace Owner.

Claimed agent access remains limited to authorized Workspace operations. Test
deletion, Test Account metadata and credentials, Live View, membership changes,
billing, and integration consent are not granted by the claim. A listed tool
does not expand the credential's permissions.

## Update and organize Tests

Use `groups.list`, `groups.create`, `groups.get`, and `groups.update` to manage
journey families. Read the current version before updating a Group or Test.
`tests.update` accepts a complete editable definition, not a partial patch.
Preserve its steps and settings; change `group_id` to move it or `enabled` to
enable or disable it. A Test has one Group, and `group_id: null` selects the
Project's Default group. Reload and reconcile version conflicts.

For an explicitly requested group execution, call `groups.run` with
`project_id`, `group_id`, `request_key`, and a `selection` of 1–20 unique
enabled Test IDs and current versions. Each selected Test is an independent
Run. `DISPATCHED` confirms dispatch, not success; `INCOMPLETE` returns partial
Run IDs for reconciliation. Preserve the same request key and selection on
retry, inspect cleanup outcomes, and never restart a child already in progress.

`runs.evidence` returns finalized artifact IDs, types, sizes, and checksums.
Use the CLI's `evidence download` command for verified artifact bytes; MCP does
not return signed download URLs to the model. Review each Run's actual result
and required screenshots before claiming the journey passed.

## Select regression coverage

Use `prs.watch` with `integration_id` before changing a deployment watch.
`prs.watch_update` accepts the complete `integration_id`, `repository_id`,
`test_group_ids`, and `enabled` object. Preserve the existing repository and all
Groups not intentionally removed, then read back the saved selection. Only
existing Groups from the same Project may be selected.

The same claimed identity can perform this operation for a Workspace Owner. It
does not create an integration, grant provider consent, or enable Dynamic PR
Tests. No version precondition or request key is accepted; reconcile conflicts
and uncertain responses without automatic retries. Saving the selection is not
a passing result. See the [regression watch guide](/github-pull-request-testing#select-regression-test-groups-with-an-agent)
for the full workflow and subsequent Run evidence.

## Scope stays server-controlled

An agent supplies the identifier required for the requested action. QA.army then
checks the authenticated account and stored relationships before returning or
changing anything.

An agent cannot make a foreign Project accessible by naming its identifier. It
also cannot use MCP to choose credentials, bypass Workspace permissions, or
alter the meaning of a Run result.

## Example agent workflow

```text
1. List the Projects the account may access.
2. Select the Project that owns the changed customer surface.
3. Review its saved Tests and Test Groups.
4. Create or update a Test using observable expectations.
5. Create a Run from the saved Test.
6. Watch the Run and inspect its final result when execution is available.
```

The workflow can describe Web, Android, iOS, desktop, or a cross-application
journey. Current target availability still applies: Android, iOS, and Desktop
execution are not generally available. Web Runs return their actual result and
available evidence; describing a broader journey does not prove that it executed.

## MCP is not the test runtime

MCP is a customer and coding-agent interface to QA.army. The autonomous QA
execution itself does not ask an external agent to choose a Workspace, Project,
credential, or execution endpoint.

This separation keeps agent-native adoption compatible with the same access
rules used by the SaaS app and CLI.

## Next

Read [QA.army CLI](/interfaces/cli) for terminal workflows, or [Security and Privacy](/security-and-isolation) for the Workspace access model.