MCP tools reference

The tools the V12 MCP server exposes, the scopes each needs, and which ones change data.

The V12 MCP server lists only the tools your token's scopes allow. Calling a registered tool without its required scopes returns an insufficient_scope error. Tool names are registry operation ids in snake case: listFindings becomes list_findings. Most also have REST endpoints and appear in the table below; send_feedback and the four Autopilot tools are MCP-only and have their own sections. To connect a client, see Connect an MCP client.

None required in the scopes column means any valid token can call the tool. For example, get_me needs no scope.

Tools

ToolWhat it doesScopesREST equivalent
get_meGet the token identityNone requiredGET /me
list_membersList organization membersuser:readGET /orgs/{org}/members
list_steersList Steersrepos:readGET /orgs/{org}/steers
create_steerCreate a Steersteers:writePOST /orgs/{org}/steers
get_steerGet a Steerrepos:readGET /orgs/{org}/steers/{steer}
update_steerEdit a Steersteers:writePATCH /orgs/{org}/steers/{steer}
archive_steerArchive a Steersteers:writeDELETE /orgs/{org}/steers/{steer}
restore_steerRestore a Steersteers:writePOST /orgs/{org}/steers/{steer}/restore
list_repositoriesList repositoriesrepos:readGET /orgs/{org}/repositories
add_repositoryAdd a repositoryrepos:writePOST /orgs/{org}/repositories
list_refsList branches, pull requests and tagsrepos:readGET /orgs/{org}/repositories/{owner}/{repo}/refs
create_hosted_repositoryCreate a hosted repositoryrepos:writePOST /orgs/{org}/repositories/hosted
create_push_credentialGet a push URL for a hosted repositoryrepos:writePOST /orgs/{org}/repositories/{owner}/{repo}/push-credentials
list_repository_findingsList a repository's findings at a positionfindings:readGET /orgs/{org}/repositories/{owner}/{repo}/findings
list_findingsList organization findingsfindings:readGET /orgs/{org}/findings
update_findingsChange findingsfindings:writePATCH /orgs/{org}/findings
get_findingGet a findingfindings:readGET /orgs/{org}/findings/{finding}
comment_on_findingComment on a findingfindings:writePOST /orgs/{org}/findings/{finding}/comments
list_runsList runsruns:readGET /orgs/{org}/runs
start_runStart a runruns:writePOST /orgs/{org}/runs
get_runGet a runruns:readGET /orgs/{org}/runs/{run}
list_run_findingsList a run's findingsruns:read, findings:readGET /orgs/{org}/runs/{run}/findings
estimate_runEstimate a runruns:writePOST /orgs/{org}/runs/estimate
cancel_runCancel a runruns:managePOST /orgs/{org}/runs/{run}/cancel
list_run_linksList guest linksruns:shareGET /orgs/{org}/runs/{run}/links
create_run_linkCreate a guest linkruns:share, findings:readPOST /orgs/{org}/runs/{run}/links
update_run_linkChange a guest linkruns:share, findings:readPATCH /orgs/{org}/runs/{run}/links/{link}
revoke_run_linkRevoke a guest linkruns:shareDELETE /orgs/{org}/runs/{run}/links/{link}
request_document_uploadRequest a document upload slotruns:writePOST /orgs/{org}/documents/uploads
create_documentCreate a context documentruns:writePOST /orgs/{org}/documents
list_documentsList context documentsruns:readGET /orgs/{org}/documents
archive_documentArchive a context documentruns:writeDELETE /orgs/{org}/documents/{document}

create_run_link and update_run_link also need findings:write when the link's role is comment or triage.

list_run_findings returns findings at each repository's analyzed commit:

  • Each repository position has kind: "commit" and a reusable at: "commit:<sha>", including for branch-only findings. webUrl opens the finding's detail in the repository workspace at that commit.
  • Send position.at together with its repositories[i].repository to get_finding, update_findings or comment_on_finding. Without repository, V12 infers it, and answers repository_required when more than one registered repository holds the finding at that position.
  • A finding that exists only off the default branch is reached only this way: without at, those three tools answer not_found and name the finding as off the default branch. For investigating, wont-fix, severity and assignee, repository and at only locate the finding, and the change applies everywhere.
  • status and codeState are evaluated at those commits, so a later fix on the default branch leaves the run finding open. If the finding is present at current defaults, call get_finding without a position for its current state.

Send feedback

Every valid token can call send_feedback, even without scopes. It sends a report to the V12 team; it has no REST endpoint or CLI command.

  • kind: bug, missing_feature, confusing or other.
  • message: what happened and what you expected, up to 10000 characters.
  • tried (optional): what you tried, including V12 error codes and request IDs, up to 10000 characters.
  • agent (optional): your product and model, up to 200 characters.
  • contact (optional): how the user wants to be contacted, up to 500 characters. Include it only if they asked; V12 already knows their account email.

Never include credentials or secrets. Success returns { "received": true }; repeating the call sends another report. The limit is 100 reports per user per hour, shared across their tokens and organizations. If it returns rate_limited, continue without sending more feedback. Tell the user what you sent; a reply is not guaranteed.

Autopilot rules

These tools manage Autopilot rules. They have no REST endpoint or CLI command.

ToolWhat it doesScopes
list_autopilot_rulesLists the rules of the workspace, or of one repository, oldest first, with each rule's state and next scheduled reviewrepos:read
create_autopilot_ruleAdds a ruleautopilot:write
update_autopilot_ruleChanges the fields you send and keeps the restautopilot:write
remove_autopilot_ruleRemoves a rule and returns it as it was; runs it already started continueautopilot:write
  • A rule is named by its repository, trigger and branch. The trigger is push, pull-request, daily or weekly; a pull-request rule has no branch. update_autopilot_rule and remove_autopilot_rule take that name as rule.
  • push, daily and weekly need a branch that exists on GitHub. pull-request takes audience (trusted or anyone) and drafts.
  • daily and weekly take review (new-changes or whole-branch) and firstAt, an ISO 8601 time with an offset: after now, and at most one day or seven days ahead. Later reviews follow every 24 hours or 7 days.
  • steers lists up to 5 Steer slugs, in order. On update_autopilot_rule it replaces the rule's Steers; [] removes them all.
  • active: false pauses a rule and active: true resumes it. A resumed daily or weekly rule whose time passed reviews once at once.
  • A repository has one pull-request rule and one rule per trigger and branch. A duplicate answers conflict, and details.rule names the rule that exists.
  • Changing rules needs the Admin role; a Member gets forbidden. A repository Autopilot can't follow answers repository_not_runnable, and details.reason says why, such as not-github for a repository V12 hosts or github-app-required for one added without the GitHub App.

No tool runs a rule on demand; use estimate_run and start_run.

Tools that change data

Only these tools change data. Every other tool, estimate_run included, only reads and carries readOnlyHint: true.

  • start_run spends credits.
  • add_repository adds a repository to the workspace. It spends no credits and starts no run. A v12/<name> names a repository V12 hosts, never one on GitHub: add_repository returns it when it exists, and answers not_found otherwise; create one with create_hosted_repository.
  • create_hosted_repository creates an empty repository V12 hosts.
  • create_push_credential returns a Git URL that can push to one branch of a hosted repository for one hour. The URL is a secret.
  • create_run_link returns the link's URL once.
  • create_steer, update_steer and restore_steer manage Steer documents. Creating is not idempotent; repeating it creates another Steer. Updates preserve omitted fields.
  • create_autopilot_rule, update_autopilot_rule and remove_autopilot_rule manage Autopilot rules, which start paid runs. Repeating a create answers conflict and creates nothing.
  • update_findings, comment_on_finding, request_document_upload, create_document and update_run_link.
  • cancel_run, revoke_run_link, archive_document, archive_steer and remove_autopilot_rule also carry destructiveHint: true.
  • send_feedback sends a report to the V12 team. It is not idempotent.

Steer writes need the opt-in steers:write scope. archive_steer detaches the Steer from Autopilot rules, preserving finding tags and existing run snapshots. Rules keep their active or paused state, using their default review when no Steers remain. restore_steer makes the Steer available again without restoring former attachments. Both are safe to repeat. list_steers shows active documents by default; pass archived: true for archived documents. get_steer reads either, with archivedAt indicating status.

list_documents differs: it shows active context documents by default, and archived: true adds the archived ones beside them, each marked archived: true.

start_run and comment_on_finding take a requestId that makes retries safe, and add_repository is safe to repeat without one. See Safe retries.

Results and errors

A successful call returns its output as structured content and as text. For tools also exposed through REST, the JSON matches the REST response. A failed call to a tool V12 knows sets isError and returns the shared error body. Errors lists the codes.

A JSON-RPC protocol error is not a tool failure: it is an error object with a code, with no isError and no shared error body. An unknown tool name, or tools/call params that are not an object with a string name and optional object arguments, gets -32602. The response still sets X-Request-Id, but its body has no requestId.

On this page