DocsStart
Set up with your coding agent
This page is written for a coding agent to follow from top to bottom, with a person beside it for the two steps that need one. It connects the agent to TestFinch, finds the project, reads and fixes a bug, writes a test that proves the fix, and runs it. Each step ends with a check; do not move on until the check holds. If you are the person, hand this page to your agent: "Follow https://testfinch.com/docs/coding-agent-setup/ end to end."
Before you start#
- A TestFinch account and a workspace. If there is none yet, the person starts free at app.testfinch.com/register; there is no card and no call.
- A coding agent that speaks MCP: Claude Code, Codex, Cursor, or any other MCP client.
- The repository of the product the bugs are about, open in the agent's session, so it can read and change the code.
1. Create a token (the person)#
In TestFinch, open Agents and create a token. The page makes a read and write token, for every project or for one; this page needs read and write. A read-only token, which lets an agent look but not change anything, is made under Settings, then API tokens. A reporter connects by signing in from the agent (Claude.ai and Claude Desktop do this with "Add custom connector") instead of with a token.
Check: the person has a token to paste in the next step.
2. Connect the agent#
The server URL is https://api.testfinch.com/mcp, and the token goes in an Authorization: Bearer header.
Claude Code, in your repository:
claude mcp add --transport http testfinch https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
Codex:
codex mcp add testfinch -- npx -y mcp-remote https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
Cursor, in .cursor/mcp.json:
{ "mcpServers": { "testfinch": { "url": "https://api.testfinch.com/mcp", "headers": { "Authorization": "Bearer <token>" } } } }
Any other MCP client takes the same URL and header, or bridges over stdio with mcp-remote.
Claude.ai and Claude Desktop connect with "Add custom connector" and a sign-in instead of a token.
Start a new agent session after adding the server, so the tools load.
Check: the agent's tool list has the TestFinch tools, such as list_projects, get and flowqa_guide.
In Claude Code, claude mcp list shows testfinch as connected.
3. Find the project#
Call list_projects.
Each project lists its halves: bugs always, and tests once the project is set up for FlowQA.
Pick the project whose name matches the product in the repository, and keep its project_id.
Check: you have one project_id, and you know whether it has a tests half.
If it has none, step 6 creates it when it reproduces a bug as a test.
4. Read a bug#
Call get_board with the project_id to see the bugs by status, or search with status: ["inbox", "triaged"] for the open ones.
Choose one and call get with its id.
get returns the report, the page and browser, the steps that led there, the console errors, the failed network requests, the comments, and up to five screenshots as images.
Check: you can say in one sentence what the person saw, on which page, and which console error or request points at the cause.
If the evidence does not point anywhere, comment on the bug with what you need and stop here.
5. Fix it#
Find the cause in the repository and change the code, the way you would for any bug.
When the change is ready, comment on the bug with what was wrong and what changed, then call update with changes: { "status": "fixed" }.
Check: get on the bug shows the status fixed and your comment.
On the board, the card has moved to the Fixed column.
6. Write a test that proves it#
Call flowqa_guide once and read it: it is how FlowQA tests are written, and every save is checked against it.
Then, for the bug you fixed, either:
- call
reproduce_as_testwith the bug's id, which writes a test in the bug's project that walks the trail Snag captured, or - call
flowqa_get_project, write the test yourself, and save it withflowqa_save_tests.
A test from reproduce_as_test is a draft, not a finished repro.
It does not capture the values the person typed (those steps come back as outline lines), and it adds an assertion only when the bug had a console error or a failed request.
Read it with flowqa_get_test, fill in the values and the assertion that proves the fix, and save it with flowqa_save_tests, passing test_id and base_revision set to the current_revision you read, before you run it.
A saved test is published at once and shows in the project's Tests, written by the person through your agent. Resolve every finding the save returns (no assertion, a weak locator, a typed password) before you call the test done.
Check: flowqa_tests_for_snag with the bug's id lists the test, it has no outline lines left, and the last save returned no findings you left unresolved.
7. Run it#
Call flowqa_run_tests with snag_id to run the tests linked to the bug, or with test_ids.
Runs happen on a cloud Chromium browser, or on the person's FlowQA Desktop when the environment is only reachable from their machine (pass target: "local").
Poll flowqa_get_run until it finishes; for a failing step, flowqa_get_artifact returns its screenshot.
Check: the run passed. If it failed, read the failing step and its screenshot, fix the code or the test, and run it again. Runs an agent starts count against the workspace's allowances exactly as if the person started them.
8. Hand it back#
Tell the person what you changed, which test covers it, and the run that passed.
Whoever reported the bug, or an admin, closes the loop with verify_fix or in the app: verified moves the bug to Verified, and a note sends it back.
From now on the test can run on a schedule, from CI or on every GitHub deployment, so the bug cannot come back unnoticed; see Schedules and CI and GitHub deploy hooks.
What the token allows#
- A read and write token reaches every tool your project role allows: reading and filing bugs, triage and updates for members, and writing and running tests where the project has a Tests half.
- A read-only token, made under Settings, then API tokens, sees only the reading tools.
- Reporters have no Tests half and see no FlowQA tools.
The full list of FlowQA tools, and what each one does, is in Coding agents.