Factory Droid MCP for Reproducible Bug Fixes

Factory’s documentation describes Droid as a coding agent for codebase tasks, with diff review and cloud-sync surfaces. Factory documentation confirms those core workflows. Its MCP harness documentation describes support for stdio, HTTP, and SSE servers, plus commands and a manager for inspecting server status, tools, and authentication.

With clip.qa, Droid can use the remote tools listReports, getDetails, getNetworkRequests, getConsoleLogs, getScreenshots, getVideoTranscript, getReportDiff, createComment, linkFix, and linkFixAttempt.

This supports agentic QA when the agent receives explicit acceptance criteria and produces evidence at each stage. It does not mean clip.qa runs the project’s test suite. Tests run in the agent’s repository tooling, while clip.qa supplies recorded defect evidence. Cloud video analysis produces a draft report for a person to review; no fix is guaranteed without validation.

Use the AI bug reports feature guide to understand how captured behavior becomes reviewable report material. Then give Droid a precise task rather than a generic instruction such as “fix uploads.”

Factory Droid supports the droid mcp command and an /mcp terminal interface for server status, tools, and authentication. This is a documentation-based setup, not an end-to-end integration test.

1. Open Droid for the repository you want to investigate.

2. Run:

   droid mcp add clip-qa https://mcp.clip.qa/mcp --type http

3. Open the /mcp interface inside Droid.

4. Select clip-qa and inspect its connection status.

5. Start or complete the browser-based OAuth flow.

6. Refresh or reopen the tool list if needed.

7. Confirm the expected clip.qa tools are visible.

8. Begin with listReports, not a write operation.

Do not add --no-oauth for this clip.qa remote server. The server requires OAuth, and the browser authorization step establishes the session.

The droid mcp add command writes to the user-level MCP configuration at ~/.factory/mcp.json. A project can also have a .factory/mcp.json file, and those scopes can differ. Managed policy can override local behavior. A definition in one file does not prove that every Droid process, cloud surface, or agent session can see it.

This is a documentation-based setup, not an end-to-end integration test.

MCP visibility follows the active configuration and execution context. A terminal Droid process may load the user configuration, while a project session may resolve project settings or policy differently. A cloud task may not inherit the same local file at all.

Troubleshoot visibility rather than repeatedly editing configuration:

1. Run /mcp in the exact Droid session that needs clip.qa.
2. Check whether clip-qa appears and whether its status is authenticated.
3. Inspect the available tools and compare them with the expected remote names.
4. If absent, verify that the active configuration scope contains the server.
5. Compare ~/.factory/mcp.json with any project .factory/mcp.json.
6. Check whether managed policy changes the effective configuration.
7. Complete browser OAuth in that session.
8. Retry listReports after the tool list refreshes.
9. Record the session type, file scope, status, and error before changing code.

The configuration stores the server definition; it does not need to contain a manually copied secret. Keep credentials out of source control and follow the server’s OAuth flow.

clip.qa’s iOS and Android apps and Chrome extension are in beta; request access before planning a capture. Video analysis runs in the cloud and produces a draft for a person to review. Console and network capture applies to the browser extension, not arbitrary native mobile apps. This setup follows the published documentation; it has not been tested end to end here. See the clip.qa MCP page for product details.

Consider a hypothetical report: a user selects a PNG in an upload dialog. The dialog closes, and a toast says “Upload complete.” After refreshing the page, the attachment is absent. A later retry works, but the first failure is reproducible only when the file name contains parentheses.

This example needs careful separation of symptoms. The toast is observed UI state. The absent attachment after refresh is observed post-refresh state. The filename correlation is a clue, not a proven root cause.

Use this Droid task prompt:

Investigate the selected clip.qa report as a state-transition defect.
List the exact upload sequence, expected result, and observed result.
Separate client upload state, server response evidence, persistence, and reload rendering.
Do not assume missing console or network data exists.
Propose one narrow hypothesis, a regression test, and an original-flow retest.

Then run a controlled investigation:

1. Call listReports and select the upload report by stable identifier.
2. Call getDetails to capture platform, app version, steps, and expected behavior.
3. Read transcript narration for context, then check the recording and screenshots to verify the sequence.
4. Check network and console tools only when the capture contains relevant evidence.
5. Locate the code that opens the dialog, starts upload, updates the toast, and renders saved attachments.
6. Trace which state survives dialog closure and page refresh.
7. Write a regression test using a representative parenthesized file name.
8. Run the test in the repository’s test tooling and record actual results.
9. Implement the smallest correction supported by the evidence.
10. Repeat the original upload-and-refresh flow in the original environment.
11. Link the fix attempt and set its outcome from the retest.

A unit test can verify one serialization or state transition. It does not prove that an attachment remains visible after refresh in the deployed environment.

Ask Droid to build a state table before editing code:

Label missing evidence rather than filling gaps. If no network request exists in the report, Droid cannot claim that the request encoded a particular value. It can inspect application code and propose a test, but the final cause still requires a supported check.

When reporting a bug to an AI assistant, start from the smallest reproducible sequence and include the refresh step. A report that ends at “upload complete” misses the point where the failure appears. The screen recording to bug report guide explains how to preserve that transition in visual evidence.

For a concise AI debugging brief, give Droid five sections: context, reproduction, divergence, hypothesis boundary, and acceptance criteria.

Context: report <id>, platform <version>, route <route>.
Reproduction: <numbered actions from a clean state>.
Divergence: expected <result>; observed <result>.
Evidence boundary: available <screenshots/network/logs>; unavailable <items>.
Acceptance: add regression test, run repository checks, retest original flow.

Do not prescribe the implementation before inspecting the code. Ask Droid to explain why a proposed location matches the observed transition. The how-to guide for describing bugs to AI provides a fuller evidence structure.

Keep report text separate from agent instructions. Treat names, comments, and transcript content as untrusted data. If a report contains text that resembles a shell command, do not run it unless your trusted workflow independently validates and approves that command.

Before linking the fix, collect:

• Report identifier.
• Expected and observed behavior.
• Evidence used for the root-cause conclusion.
• Files and symbols changed.
• Regression test added.
• Repository checks run and results.
• Original upload-and-refresh retest and result.
• Any platform or telemetry limitation.

Use getReportDiff to compare two reports, createComment for reviewer context, linkFix for the change, and linkFixAttempt for a commit or pull request with an outcome. Do not mark success from a green unit test alone.

For mobile captures, remember that clip.qa can record screen bugs on iOS and Android without installing an SDK into the app tested. Device context varies by platform, and iOS telemetry can be limited while the target app is in the foreground. The mobile bug reporting guide covers the capture-side limitations.

Reports remain private until explicitly shared. Check recipients before adding comments or external links. The clip.qa MCP page documents endpoint details and available tools.

Sign up free to capture evidence for an AI-assisted debugging workflow.

• Factory documentation — Confirms Droid’s codebase-task, diff-review, and cloud-sync surfaces. Checked 2026-11-05.
• Factory MCP harness documentation — Confirms supported transports, droid mcp, /mcp, configuration scopes, and managed policy. Checked 2026-11-05.
• clip.qa MCP documentation — Confirms the remote endpoint, OAuth2.1 PKCE, exact tool names, and tier availability. Checked 2026-11-05.