Connect external AI agents (MCP)

You can connect an external AI tool that speaks MCP (Model Context Protocol), such as a coding agent, to reopt QA. A connected agent can read projects, test cases, reports and AI session status. It can run tests or request AI sessions only for operations the project allows.

The reopt-qa mcp command provides the connection. It talks to the MCP client over standard input/output (stdio) and forwards requests only to the reopt QA app running on this computer. It never connects to another machine's address.

reopt-qa mcp currently ships with the CLI in the reopt QA repository (bin/reopt-qa.mjs). It is not yet part of the desktop app installer. The desktop app (or pnpm dev in development) must be running while the bridge is in use.

1. A project is required

The bridge refuses to run without knowing which project to use. You need one of:

• --project <id>: pins the connection to this project. This is the recommended form.
• A linked project: run the bridge in a directory linked with reopt-qa link and it uses that project.
• --unbound: an explicit opt-out of pinning. The bridge follows the project currently selected in the app and can read several projects.

Without any of these, the bridge exits with an error (exit code 2) before contacting the app.

Example MCP client configuration:

{
  "mcpServers": {
    "reopt-qa": {
      "command": "reopt-qa",
      "args": ["mcp", "--project", "my-app"]
    }
  }
}

2. Choose what to allow (default: nothing)

A new project lets external agents start nothing. Reading (projects, test cases, reports, debug info and session status) is always available.

To allow an operation, edit the project in the app and turn on only what you need under 외부 에이전트(MCP) 허용 작업 (operations allowed for external agents).

You can also change it from the CLI:

reopt-qa ai config external-mcp investigate,fix   # allow investigate and fix sessions only
reopt-qa ai config external-mcp none              # turn everything off again

A request for an operation that is not allowed returns a not_allowed error, and nothing starts.

3. Fixes always need a person

A fix session started by an external agent always uses manual approval, whatever approval mode the project uses. Even with automatic or conditional approval turned on, the proposal is not written to your files. A person must review and approve it on the app's AI session screen.

External agents cannot approve, reject or publish anything. Those decisions happen only in the app.

4. What an external agent can do

• Read the project list, test cases, the latest report and debug info
• When allowed, run tests and start AI sessions (explore, investigate, fix)
• Read session status, optionally waiting up to 20 seconds for a change
• A session waiting for a browser action approval reports awaiting_input, and one waiting for proposal review reports awaiting_review. Both continue only after a person answers in the app
• Stop only the sessions it started. Work started from the app cannot be stopped this way

Sessions started by an external agent carry an MCP badge in the app's AI session list, and the session detail shows 외부 에이전트 (MCP) as the start origin.

5. Security notes

• The connection stays on this computer and is protected by the session token the app issues. Web pages in your browser cannot use it.
• Text returned to the agent has the passwords, tokens and similar values registered in your environments and personas masked. Text taken from reports or pages is marked as untrusted data.
• Each project allows at most 3 active external-agent sessions at a time. Resending a request with the same idempotencyKey returns the existing session instead of starting a new one. The bridge adds such a key when it retries, so a session never starts twice.
• Screenshot images are not masked, so be careful with pages that display secret values.

Troubleshooting

• "reopt QA agent에 연결할 수 없습니다" (cannot reach the reopt QA agent): check that the desktop app (or pnpm dev) is running. If the app restarts on a new address, the bridge finds it again automatically.
• not_allowed error: check that the operation is turned on under the project's 외부 에이전트(MCP) 허용 작업.
• The bridge exits immediately: pass --project <id>, or run it in a linked project directory.

A practical collaboration flow

Start with read access and a request such as:

Read this project's tests and latest failure reports. Separate observed facts from possible causes.

With investigation and test execution enabled, continue through investigation, review in the app, application of a reviewed fix, rerun, and inspection of the latest result. Check that the change has not weakened the intended assertions.

Read scope

get_report is not an arbitrary historical analytics query. Trace responses from get_debug_info list files; they do not interpret an entire trace. Use Reports and analytics for trends and detailed evidence.

Without a globally installed CLI

Use absolute paths to Node and the repository CLI. Replace the example paths and project ID with real values. The configuration file location and supported format depend on the MCP client.

{
  "mcpServers": {
    "reopt-qa": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/reopt-qa/bin/reopt-qa.mjs", "mcp", "--project", "my-app"]
    }
  }
}

Connecting MCP does not schedule tests or automatically deliver AI reports. Scheduled checks is a separate app feature. Also review how the external AI client sends returned data to its model and bills that usage.

Read product structure and improvements

The MCP control tool get_product_context reads a project's features, user flows, and improvement records. Set projectId to select a project and offset to page each collection in groups of 20. hasMore indicates additional records. The tool reads stored context; it does not run verification or change improvement status.

Check each flow's source and confirmation state. An AI proposal is distinct from an observed or user-confirmed flow.