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 | user:read | GET /me |
list_members | List organization members | user:read | GET /members |
list_focuses | List focuses | repos:read | GET /focuses |
get_focus | Get a focus | repos:read | GET /focuses/{focus} |
list_repositories | List repositories | repos:read | GET /repositories |
list_refs | List branches, pull requests and tags | repos:read | GET /repositories/{owner}/{repo}/refs |
list_repository_findings | List a repository's findings at a position | findings:read | GET /repositories/{owner}/{repo}/findings |
list_findings | List organization findings | findings:read | GET /findings |
update_findings | Change findings | findings:write | PATCH /findings |
get_finding | Get a finding | findings:read | GET /findings/{finding} |
comment_on_finding | Comment on a finding | findings:write | POST /findings/{finding}/comments |
list_runs | List runs | runs:read | GET /runs |
start_run | Start a run | runs:write | POST /runs |
get_run | Get a run | runs:read | GET /runs/{run} |
list_run_findings | List a run's findings | runs:read, findings:read | GET /runs/{run}/findings |
estimate_run | Estimate a run | runs:write | POST /runs/estimate |
cancel_run | Cancel a run | runs:manage | POST /runs/{run}/cancel |
request_document_upload | Request a document upload slot | runs:write | POST /documents/uploads |
create_document | Create a context document | runs:write | POST /documents |
list_documents | List context documents | runs:read | GET /documents |
archive_document | Archive a context document | runs:write | DELETE /documents/{document} |
Tools that change data
Only these tools change data. Every other tool, estimate_run included, only reads, and says so with readOnlyHint: true.
update_findingscomment_on_findingrequest_document_uploadstart_run, which spends creditscreate_documentcancel_runandarchive_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.
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.