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
| Tool | What it does | Scopes | REST equivalent |
|---|---|---|---|
get_me | Get the token identity | None required | GET /me |
list_members | List organization members | user:read | GET /orgs/{org}/members |
list_steers | List Steers | repos:read | GET /orgs/{org}/steers |
create_steer | Create a Steer | steers:write | POST /orgs/{org}/steers |
get_steer | Get a Steer | repos:read | GET /orgs/ |
update_steer | Edit a Steer | steers:write | PATCH /orgs/ |
archive_steer | Archive a Steer | steers:write | DELETE /orgs/ |
restore_steer | Restore a Steer | steers:write | POST /orgs/ |
list_repositories | List repositories | repos:read | GET /orgs/ |
add_repository | Add a repository | repos:write | POST /orgs/ |
list_refs | List branches, pull requests and tags | repos:read | GET /orgs/ |
create_hosted_repository | Create a hosted repository | repos:write | POST /orgs/ |
create_push_credential | Get a push URL for a hosted repository | repos:write | POST /orgs/ |
list_repository_findings | List a repository's findings at a position | findings:read | GET /orgs/ |
list_findings | List organization findings | findings:read | GET /orgs/{org}/findings |
update_findings | Change findings | findings:write | PATCH /orgs/ |
get_finding | Get a finding | findings:read | GET /orgs/ |
comment_on_finding | Comment on a finding | findings:write | POST /orgs/ |
list_runs | List runs | runs:read | GET /orgs/{org}/runs |
start_run | Start a run | runs:write | POST /orgs/{org}/runs |
get_run | Get a run | runs:read | GET /orgs/ |
list_run_findings | List a run's findings | runs:read, findings:read | GET /orgs/ |
estimate_run | Estimate a run | runs:write | POST /orgs/ |
cancel_run | Cancel a run | runs:manage | POST /orgs/ |
list_run_links | List guest links | runs:share | GET /orgs/ |
create_run_link | Create a guest link | runs:share, findings:read | POST /orgs/ |
update_run_link | Change a guest link | runs:share, findings:read | PATCH /orgs/ |
revoke_run_link | Revoke a guest link | runs:share | DELETE /orgs/ |
request_document_upload | Request a document upload slot | runs:write | POST /orgs/ |
create_document | Create a context document | runs:write | POST /orgs/ |
list_documents | List context documents | runs:read | GET /orgs/ |
archive_document | Archive a context document | runs:write | DELETE /orgs/ |
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 reusableat: "commit:<sha>", including for branch-only findings.webUrlopens the finding's detail in the repository workspace at that commit. - Send
position.attogether with itsrepositories[i].repositorytoget_finding,update_findingsorcomment_on_finding. Withoutrepository, V12 infers it, and answersrepository_requiredwhen 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 answernot_foundand name the finding as off the default branch. Forinvestigating,wont-fix, severity and assignee,repositoryandatonly locate the finding, and the change applies everywhere. statusandcodeStateare evaluated at those commits, so a later fix on the default branch leaves the run findingopen. If the finding is present at current defaults, callget_findingwithout 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,confusingorother.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.
| Tool | What it does | Scopes |
|---|---|---|
list_autopilot_rules | Lists the rules of the workspace, or of one repository, oldest first, with each rule's state and next scheduled review | repos:read |
create_autopilot_rule | Adds a rule | autopilot:write |
update_autopilot_rule | Changes the fields you send and keeps the rest | autopilot:write |
remove_autopilot_rule | Removes a rule and returns it as it was; runs it already started continue | autopilot:write |
- A rule is named by its
repository,triggerandbranch. The trigger ispush,pull-request,dailyorweekly; apull-requestrule has no branch.update_autopilot_ruleandremove_autopilot_ruletake that name asrule. push,dailyandweeklyneed abranchthat exists on GitHub.pull-requesttakesaudience(trustedoranyone) anddrafts.dailyandweeklytakereview(new-changesorwhole-branch) andfirstAt, 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.steerslists up to 5 Steer slugs, in order. Onupdate_autopilot_ruleit replaces the rule's Steers;[]removes them all.active: falsepauses a rule andactive: trueresumes it. A resumed daily or weekly rule whose time passed reviews once at once.- A repository has one
pull-requestrule and one rule per trigger and branch. A duplicate answersconflict, anddetails.rulenames the rule that exists. - Changing rules needs the Admin role; a Member gets
forbidden. A repository Autopilot can't follow answersrepository_not_runnable, anddetails.reasonsays why, such asnot-githubfor a repository V12 hosts orgithub-app-requiredfor 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_runspends credits.add_repositoryadds a repository to the workspace. It spends no credits and starts no run. Av12/<name>names a repository V12 hosts, never one on GitHub:add_repositoryreturns it when it exists, and answersnot_foundotherwise; create one withcreate_hosted_repository.create_hosted_repositorycreates an empty repository V12 hosts.create_push_credentialreturns a Git URL that can push to one branch of a hosted repository for one hour. The URL is a secret.create_run_linkreturns the link's URL once.create_steer,update_steerandrestore_steermanage Steer documents. Creating is not idempotent; repeating it creates another Steer. Updates preserve omitted fields.create_autopilot_rule,update_autopilot_ruleandremove_autopilot_rulemanage Autopilot rules, which start paid runs. Repeating a create answersconflictand creates nothing.update_findings,comment_on_finding,request_document_upload,create_documentandupdate_run_link.cancel_run,revoke_run_link,archive_document,archive_steerandremove_autopilot_rulealso carrydestructiveHint: true.send_feedbacksends 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.