MCP Server

V12 is an automated security audit platform. It analyzes code repositories — primarily smart contracts — for vulnerabilities, then produces findings with severity, validity, source locations, and optional fix/PoC artifacts.These notes cover what you need beyond what the tool schemas already tell you.## Audit lifecyclediscover → audit → poll → review → triageNot every session follows every step. A user may jump in at "review" with an existing runUid, or ask to triage a single finding without listing anything first. Adapt to what the user actually asks.## Starting an auditThere are two audit tools depending on the source, plus an upload helper for large zips.### v12_audit_githubAudit a GitHub repository. Requires exactly one of repoUid or repoFullName.- **Full audit:** pass branch/sha (auto-resolves to default HEAD if omitted) and optional paths to scope.- **Diff review:** pass `diffReviewConfig` with either (fromRef + toRef) for branch/tag/commit comparison, OR `patchContent` with a raw unified diff — not both. Include `prMetadata` when auditing a pull request.### v12_audit_zipAudit source code from a zip archive. Accepts either:- `zipUid` from `v12_upload_zip` (preferred for files over ~750 KiB)- `sourceZip` as inline base64 (convenient for small projects)Provide exactly one.- **Full audit:** just pass the zip source (+ optional paths to scope).- **Diff review:** also pass `patchContent` with a unified diff.### v12_upload_zipPre-upload a zip archive for use with `v12_audit_zip`. Returns `{ zipUid, uploadUrl }`. The agent must:1. Call `v12_upload_zip` to get the presigned URL2. HTTP PUT the raw zip bytes to `uploadUrl`3. Call `v12_audit_zip` with `zipUid`Use this when the zip exceeds the ~750 KiB inline limit (which is bounded by the MCP request body size).### v12_estimate_costEstimate the billable cost before starting an audit. Takes the same target selectors as the audit tools: exactly one of repoUid/repoFullName (with optional branch/sha/paths) or zipUid. Diff reviews are supported via `diffReviewConfig` — (fromRef + toRef), patchContent, or patchUid — and inline patches are stored and echoed back as `patchUid`, which you should pass to the audit tool so the queued run reviews the exact quoted patch. Returns the resolved scope file list plus billable file/LOC counts and a cost band in USD cents (`meanCostCents` / `upperCostCents`). Use it when the user asks what an audit will cost, or before queueing a large audit. The audit tools return the same `estimate` object once a run is queued.## Preparing a zip for uploadWhen auditing local source code:1. **Include only source files.** The zip should contain the auditable source tree (e.g., `.sol`, `.rs`, `.move` files and their directory structure). Exclude `node_modules`, `.git`, `build/`, `dist/`, `target/`, compiled binaries, and other non-source artifacts.2. **Preserve directory structure.** Paths inside the zip should match the project layout so findings reference the correct file locations.3. **Keep it small.** A typical smart contract project zips to well under 1 MiB. If your zip is larger, use `v12_upload_zip` instead of inline `sourceZip`.## The `paths` fieldThe `paths` field serves two purposes depending on audit mode:- **Full audit:** scopes which files are analyzed (only files matching these paths are audited).- **Diff review:** selects which affected files to include in the review (maps to `selectedFiles` internally). The diff scope computation determines affected files; `paths` narrows that set.## Repo selection (GitHub audits)v12_audit_github needs exactly one repo selector. Pick based on what you have:- A repoUid from v12_repos → use repoUid (preferred — no lookup ambiguity)- An owner/name string or git remote URL → use repoFullName (V12 validates installation itself)There is no separate repo-resolution step. v12_audit_github handles it.### Local git contextWhen running inside a code editor, resolve the local checkout so the audit matches what the user has open:- git remote get-url origin → parse into owner/name → repoFullName- git branch --show-current → branch- git rev-parse HEAD → shaIf local git is unavailable or the user explicitly wants the default branch, omit branch and sha. V12 resolves the repo's default-branch HEAD server-side. Never pass sha without branch.## PollingAll audit tools return nextPollAfterSeconds. Call v12_watch after that many seconds. Each v12_watch response updates the interval — always honor it. When terminal is true, stop. Typical audits take 5-15 minutes. Do not synthesize progress updates between polls.## Presenting resultsWhen the run completes: link the run webUrl first, then one sentence with severity counts from findingCounts, then list critical and high findings with title, sourceLocations, and webUrl. Skip info and qa severity unless the user asks. sourceLocations is an array — iterate all entries when a finding spans multiple files.## Reading finding detail- v12_findings tool: filtered, paginated listing. Use severity and validity filters to narrow.- v12://runs/{uid}/findings/{findingUid} resource: full detail for one finding including description, impact, root cause, and source URLs.- The aggregate resource v12://runs/{uid}/findings is capped to a first page. When hasMore is true, switch to v12_findings with offset.- Findings are always addressed by findingUid — not by number or title.## Resources- v12://runs — list of the user's runs- v12://runs/{uid} — single run detail- v12://runs/{uid}/findings — first page of findings (use v12_findings to paginate)- v12://runs/{uid}/findings/{findingUid} — full finding detail- v12://runs/{uid}/findings/{findingUid}/poc — proof-of-concept (404 if none recorded)- v12://runs/{uid}/findings/{findingUid}/fix — fix artifact (404 if none recorded)- v12://runs/{uid}/report — audit report as JSON- v12://runs/{uid}/report.md — audit report as Markdown## Triagev12_triage_finding is the single write tool for findings. It handles validity changes (valid, invalid, unreviewed, acknowledged), severity changes, comment-only notes (pass only comment), or any combination atomically. Only call after explicit user instruction. Restate the action before executing. One comment per finding is enforced server-side.## Cancellationv12_cancel_run stops a non-terminal run. Only call when the user explicitly asks.## ScopesCall v12_whoami to check available scopes. Main boundaries: runs:read enables v12_watch, v12_findings, v12_estimate_cost, and all resources; runs:write enables v12_audit_github, v12_audit_zip, and v12_upload_zip; runs:manage enables v12_cancel_run; repos:read enables v12_repos; findings:write enables v12_triage_finding; user:read enables v12_whoami.Tokens are account-bound: `v12_whoami` returns the token's `orgUid`, `orgName`, and `orgKind`. If the user needs access to another org, they need a different PAT or a separate OAuth authorization in that org.## Error handling- Repo unavailable: v12_audit_github returns a clear error when the repo is not installed or not accessible to this token. Surface it to the user and stop — do not retry with the same inputs.- Run not found (404): Accessing a run the token cannot see returns 404. This is intentional — the server does not distinguish "does not exist" from "not yours."- Rate limits: Tools are rate-limited per scope. If a call fails due to rate limiting, wait and retry.## Host noteSome MCP hosts display tool names with a prefix like `mcp_v12_<tool>`. V12 registers canonical `v12_*` names. Use whatever name your host shows.## Do not- Poll faster than nextPollAfterSeconds.- Auto-triage based on your own judgment.- Summarize info/qa findings unless the user asks.- Retry after a repo-availability failure without the user changing context.- Assume finding numbers are stable identifiers — always use findingUid.