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 any other tool returns an insufficient_scope error. Each tool name is its REST operation's operationId in snake case: listFindings becomes list_findings. To connect a client, see Connect an MCP client.
Tools
| Tool | What it does | Scopes | REST equivalent |
|---|---|---|---|
get_me | Get the token identity | GET /me | |
list_members | List organization members | user:read | GET /orgs/{org}/members |
list_steers | List Steers | repos:read | GET /orgs/{org}/steers |
get_steer | Get a Steer | repos:read | GET /orgs/{org}/steers/{steer} |
list_repositories | List repositories | repos:read | GET /orgs/{org}/repositories |
add_repository | Add a repository | repos:write | POST /orgs/{org}/repositories |
list_refs | List branches, pull requests and tags | repos:read | GET /orgs/{org}/repositories/{owner}/{repo}/refs |
create_hosted_repository | Create a hosted repository | repos:write | POST /orgs/{org}/repositories/hosted |
create_push_credential | Get a push URL for a hosted repository | repos:write | POST /orgs/{org}/repositories/{owner}/{repo}/push-credentials |
list_repository_findings | List a repository's findings at a position | findings:read | GET /orgs/{org}/repositories/{owner}/{repo}/findings |
list_findings | List organization findings | findings:read | GET /orgs/{org}/findings |
update_findings | Change findings | findings:write | PATCH /orgs/{org}/findings |
get_finding | Get a finding | findings:read | GET /orgs/{org}/findings/{finding} |
comment_on_finding | Comment on a finding | findings:write | POST /orgs/{org}/findings/{finding}/comments |
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/{org}/runs/{run} |
list_run_findings | List a run's findings | runs:read, findings:read | GET /orgs/{org}/runs/{run}/findings |
estimate_run | Estimate a run | runs:write | POST /orgs/{org}/runs/estimate |
cancel_run | Cancel a run | runs:manage | POST /orgs/{org}/runs/{run}/cancel |
list_run_links | List guest links | runs:share | GET /orgs/{org}/runs/{run}/links |
create_run_link | Create a guest link | runs:share, findings:read | POST /orgs/{org}/runs/{run}/links |
update_run_link | Change a guest link | runs:share, findings:read | PATCH /orgs/{org}/runs/{run}/links/{link} |
revoke_run_link | Revoke a guest link | runs:share | DELETE /orgs/{org}/runs/{run}/links/{link} |
request_document_upload | Request a document upload slot | runs:write | POST /orgs/{org}/documents/uploads |
create_document | Create a context document | runs:write | POST /orgs/{org}/documents |
list_documents | List context documents | runs:read | GET /orgs/{org}/documents |
archive_document | Archive a context document | runs:write | DELETE /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 uses kind: "commit" and a reusable at: "commit:<sha>", including for branch-only findings; webUrl opens finding detail in the repository workspace at that commit. Send position.at together with its repositories[i].repository to get_finding or update_findings. Without repository, V12 infers it and answers repository_required when more than one registered repository holds the finding at that position. status and codeState are evaluated at those commits: a later fix on the default branch leaves the run finding open. If the finding is present at current defaults, use get_finding without a position for its current state.
Tools that change data
Only these tools change data. Every other tool, estimate_run included, only reads, and says so with readOnlyHint: true.
add_repository, which adds a repository to the workspace; it spends no credits and starts no runcreate_hosted_repository, which creates an empty repository V12 hostscreate_push_credential, which returns a Git URL that can push to one branch of a hosted repository for one hour; the URL is a secretupdate_findingscomment_on_findingrequest_document_uploadstart_run, which spends creditscreate_documentcreate_run_link, which returns the link's URL once, andupdate_run_linkcancel_run,revoke_run_linkandarchive_document, which also carrydestructiveHint: true
Retrying start_run or comment_on_finding with the same requestId returns the original result instead of starting a second run or posting a second comment. Repeating add_repository needs no requestId: a repository already added comes back with added: false.
Results and errors
A successful call returns the same JSON as the REST response, as structured content and as text. A failed call sets isError and returns the REST error body; its codes are listed under Errors.