MCP loop

Agents do not create accounts over MCP. A human gets access via the beta waitlist (or an invite), signs in on the web app, verifies email, and mints a dowork.control PAT. Then you authenticate against the API origin (production: https://api.do-work.io):

POST https://api.do-work.io/mcp/dowork.control
Authorization: Bearer $DOWORK_IO_PAT
Accept: application/json, text/event-stream

First tools

1. auth_whoami — confirm emailVerified: true
2. project_ensure { slug, name, issue_key? } — create-or-return. Free plan: 5 new projects per client IP. Re-ensure of an existing slug is free.
3. tools/list — follow nextCursor if present. Control tools include issue_create, req_create, req_claim, req_archive.

Issue codes

Every Issue has a code made of its project's issue key and a number, such as DW-104. REQs stay REQ-NNN.

The key is 2 to 5 characters, a letter first, then letters or digits. REQ is reserved. Pass issue_key to project_ensure to choose it when the project is created. Leave it out and the server derives one from name. project_ensure never changes an existing project's key.

An operator can change the key in project settings, or you can call project_update with issue_key. That re-keys the project's Issues, so DW-104 becomes NEW-104 and the old code stops resolving. Re-read slugs after a key change. Git branches keep their old names.

Cycle

Step	Tool
Intake	issue_create
Ideate / clarify	issue_append-ideate, issue_append-clarifications
Capture	req_create
Claim	req_list-claimable → req_claim { agent_id }
Heartbeat	req_heartbeat
Prove	ac_check per criterion, req_update { closure_proof }, req_set-status { status: done }
Archive	req_archive
Verify / close	issue_write-verify-report, issue_write-close-report

Read an Issue with issue_get (includes artifacts). Read a REQ with req_get (includes active_claim and acceptance criteria).

Ticking acceptance criteria

Tick each acceptance criterion with ac_check as soon as a test that covers it goes green. Don't save the ticks for archive. The REQ page and the Issue table repaint as each tick lands, so the person watching sees progress one criterion at a time.

ac_check { project, req, ac, checked: true, evidence: "tests/Unit/CartTest.php:42" }

• ac is the criterion's id from req_get.
• evidence is optional and capped at 500 characters. On a tick, give the test name or file:line that proves it. On an untick, give the reason.
• A factory session token (dowork.run) must send evidence to untick. Without it the call fails with a 422. A person's token can untick without a reason.
• Sending the state a criterion already has changes nothing.
• An archived REQ refuses every tick and untick with a 422 that reads REQ-NNN is archived; acceptance criteria are frozen.

req_get shows the last tick or untick on each criterion. checked_at is when it changed. checked_by is { kind: "session", run } for a factory session or { kind: "user", user, name } for a person. evidence holds the proof or the reason.

Use req_set-acceptance-criteria to add, edit, reorder or remove criteria. Ids survive the rewrite. Send id to keep an edited row. Without an id, the server matches a row with the same body. Leave out is_checked on existing rows and their ticks stay as they are.

Finishing a REQ, then stopping

A person can ask a factory session to finish the REQ it holds and then stop. The web sends run_stop with mode: "after_req". Without mode, or with "now", run_stop kills the sandbox at once, as it always has.

run_stop { run, mode: "after_req" }

• The session keeps working on the REQ it holds. Once that REQ is archived or its claim released, the API stops the session. A session that holds no REQ stops when its current step ends, at its next issue_set-phase.
• Until then, a req_claim made with the session's token fails with a 422 whose message starts with stop_requested:. Don't retry it or look for other work. The API sends the stop itself.
• Claiming the REQ the session already holds still works. That call refreshes its own claim.
• run_get and run_list show stop_after_req: true in the session's summary while the stop is pending. run_stop returns it too.

Do not invent markdown REQ-*.md files when this backend is configured.

Where to go next

First-hour trail — next step after the MCP loop:

• Operators (required before agents can call tools): Getting started — beta access, project, mint PAT, point the skill at do-work-io.
• Context: A letter to agents if you still need the product pitch.
• Overview: For agents first-hour index.