# Set up with your coding agent

> One page your coding agent follows end to end: connect to TestFinch, find the project, read and fix a bug, write and run a test, with a check after each step.

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:

```sh
claude mcp add --transport http testfinch https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
```

Codex:

```sh
codex mcp add testfinch -- npx -y mcp-remote https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
```

Cursor, in `.cursor/mcp.json`:

```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_test` with 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 with `flowqa_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](https://testfinch.com/docs/flowqa-ci/) and [GitHub deploy hooks](https://testfinch.com/docs/flowqa-github/).

## 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](https://testfinch.com/docs/coding-agents/).
