Coding agents & MCP

Give your coding agent the same context you investigate in the dashboard: original feedback, captured browser context, AI interpretation and available attachments. An authorized agent can also check project readiness, configure a coding role and start a bounded draft-PR run.

Connect your agent#

In Settings → Access, create a management key with Readonly enabled. Configure your MCP client to connect over HTTP to https://testosaurus.dev/mcp using an Authorization bearer header. Keep the sk_… key outside browser code.

claude mcp add --transport http testosaurus https://testosaurus.dev/mcp \
  --header "Authorization: Bearer ${TESTOSAURUS_SK}"

The example reads the key from your shell's TESTOSAURUS_SK variable. Other MCP clients can use the same endpoint and header.

Read a report#

Ask your agent: “Inspect the latest checkout report before proposing a fix.” Reading reports does not start a coding run or change your application's code.

list_issues and get_issue#

Start with list_issues for the grouped inbox. Filter by project, status, category, severity or search text, and page with page and perPage. Each item's issue_id identifies its shared issue; id opens the representative report. Pending reports remain visible. Counts mean reports, not distinct people.

Call get_issue({ issueId }) for the shared analysis, current revision, tracker links and original occurrences. Pass the returned nextCursor as cursor to inspect more occurrences. Use the report tools below for individual evidence and attachments.

Correct grouping#

With a writable key, use merge_issues with issueId, targetIssueId, expectedRevision and expectedTargetRevision. Use split_issue with issueId, submissionIds and expectedRevision to move selected captures into a pinned new issue, leaving at least one report in the source.

update_issue_status and redistill_issue also require the current issue revision. Reinspect after a stale edit or active-work conflict. Merge, split and refresh queue analysis under the project's configured model and credit controls; queued:false means the edit succeeded but queue delivery needs attention.

If a tracker creation is unconfirmed, inspect the tracker and use reconcile_issue_link with the saved provider, destination and existing issue URL. Testosaurus verifies the destination before recording the shared link; it does not create another external issue.

Split responses include sourceQueued and createdQueued. Retry analysis only for a failed side, using its current revision, to avoid repeating analysis that was already queued successfully.

list_reports#

Find reports using optional project (project ID), status, severity and since filters. The limit defaults to 20 and is capped at 100. Pass the returned nextCursor as cursor to read another page.

{
  "project": "YOUR_PROJECT_ID",
  "status": "new",
  "limit": 20
}

Each result includes its ID, project, creation time, status, distilled fields and whether a screenshot or replay is available. Distilled fields can be null while AI processing is pending.

get_report#

Pass { "id": "REPORT_ID" } to retrieve the full report. The response separates raw feedback, context, distilled interpretation and attachments. Keep an AI-suggested cause distinct from evidence captured in the browser.

{
  "raw": "I click Pay and nothing happens.",
  "context": { "url": "https://store.example/checkout" },
  "attachments": [
    { "ref": "ATTACHMENT_REF", "kind": "screenshot" }
  ]
}

This is a shortened example response. Available context can also include the page title, user agent, viewport, language and console entries. Screenshot and replay availability depend on consent and successful capture.

get_asset#

Pass an attachment reference from get_report, such as { "ref": "ATTACHMENT_REF" }. The result contains a short-lived download url and expiresAt. The URL is valid for 15 minutes and can retrieve a screenshot or replay bundle.

Read-only access#

Management keys are scoped to their account. Unknown or foreign reports and attachments are rejected. Read-only keys can use list/get tools; mutating tools return a read-only error. Report and attachment access, management changes and denied write attempts are recorded in the account audit log.

Manage your setup#

list_projects returns project IDs for subsequent calls. get_config reads account configuration, and list_storage inspects stored attachments. For agents that you intend to let change the account, create a management key without the read-only restriction to use apply_config, delete_storage_object and clear_project_storage.

apply_config applies an account configuration document. Pass the current ETag as expectedEtag to reject stale changes. Storage deletion tools remove stored data; use a read-only key when the agent only needs investigation context.

Prepare and run a coding role#

Pass projectId from list_projects to get_project_readiness. It checks collection, integrations, coding roles, workflow and prepaid funding, and returns actionable blockers. OAuth connections and payment authorization remain in the dashboard. Reading readiness does not install a workflow or spend credit.

1. Read get_coding_roles with { "projectId": "YOUR_PROJECT_ID" }. Use its project AI-settings etag as expectedEtag in upsert_coding_role, together with projectId and the complete role. Existing unrelated roles and AI settings are preserved. On a conflict, read again before retrying.
2. Review get_coding_workflow, then explicitly call install_coding_workflow with the same projectId. The preview does not write to GitHub.
3. Call start_coding_run with submissionId and roleSlug. Starting reserves the role's maximum run budget from prepaid credit and dispatches GitHub Actions.
4. Inspect list_coding_runs with projectId and optional submissionId and limit. To stop a cancellable run, call cancel_coding_run with runId. Wait for reservation settlement before retrying the same role and report.

Read-only keys can inspect readiness, roles, workflow and runs. Creating or updating a role, installing a workflow, starting a run and cancelling a run require a writable key. Coding roles constrain the model, base branch, editable paths, setup, tests and budgets; all configured tests must pass before a draft PR is created. Review the proposed diff before merging.

Revise a draft PR#

After reviewing a proposal, give the agent specific feedback to address on the same draft PR. Call get_coding_revision with the completed proposal's runId. It inspects the live draft and returns its current headSha, role and maximum run cost without spending credit.

With a writable key, call revise_coding_run using that run ID, the inspected head as expectedHeadSha, and feedback of 1–4000 characters:

{
  "runId": "COMPLETED_RUN_ID",
  "expectedHeadSha": "CURRENT_40_CHARACTER_COMMIT_SHA",
  "feedback": "Restore the exact project-list assertion, include the returned project ID, and remove the unused probe setup. Preserve the regression test and production fix."
}

A revision reserves the current role's run budget and counts toward its monthly limit. It starts from the inspected PR head, applies changes within the configured paths, reruns every configured test and adds a commit to that PR. Review feedback and each attempt's cost remain in run history. A changed head, closed PR or active same-role run can prevent revision; inspect again and review the latest diff before retrying. Read-only keys cannot start revisions.

The dashboard provides the same flow through Revise draft PR. Tests are evidence for review; a passing run does not establish that every assertion or change is appropriate. Revisions remain drafts and are never merged automatically.

Keep the work moving#

Create GitHub or Linear issues deliberately from a report in the dashboard. A coding run's draft PR links back to the report and its available related issue. See Reports & distillation and Dashboard & data.