Skip to content

AI agents

View .md

The zkao skill teaches an agent to drive a project through MCP, the CLI, or HTTP. It covers login, scopes, scans, triage, guidance, credits, and publishing. Claude Code and Codex plugins share the same skill and MCP connection.

An agent with the skill can handle requests like “enable formal verification on the main branch with a monthly budget of 500 credits” or “run a diff scan of this change”.

The repository is a Claude Code plugin marketplace. Add it, then install the plugin:

/plugin marketplace add zksecurity/zkao-sdk
/plugin install zkao@zkao

Shell-based agents can use the CLI from the Quickstart.

Add https://zkao.io/api/mcp as a remote MCP server in your client. It uses Streamable HTTP and OAuth. Follow the client’s sign-in flow to approve a project and its permissions. The plugin manifests configure this endpoint for Claude Code and Codex. You do not need to copy an API token into the plugin.

The connection belongs to one project. Use its identity tool to check the project before acting. CLI login and MCP authorization are separate. For staging, configure https://staging.zkao.io/api/mcp instead.

After analysis finishes, the agent reads the scan’s triage completeness. A COMPLETED scan can still have unreviewed findings. Those findings are withheld from results.

When triage stopped on budget, the scan offers allowed resumption budgets. The agent can resume within the spending limit you authorized. It reuses the same request key and budget when retrying. It tracks the returned triage run, then checks the scan’s completeness again. See Resume unfinished triage.

For fixes, the agent reads the finding’s evidence and verifies the change with a scan or recheck. Further scans and triage require an authorized credit budget.

Every page on this site has a plain Markdown version for agents.

URL What it holds
/llms.txt An index of the docs, following the llms.txt convention.
/llms-full.txt All guides and API reference pages in one file.
/llms-small.txt A shorter bundle of guides.
.md pages One page as Markdown. Replace the trailing slash with .md.
/openapi/v1.yaml The full API contract.

Each page also has a Copy as Markdown button next to its title.

Requests with Accept: text/markdown receive Markdown at the normal page URL.

A bare zkao login waits for browser approval for minutes. Most agent tool calls time out first. Split the login instead, so no command blocks.

  1. Start the login. It prints a URL and a code, then exits.

    Terminal window
    zkao login --no-wait --no-browser --project <projectId>

    --project is optional. It preselects the project on the approval page.

  2. The agent gives the URL and code to you. You open the URL, check the code, pick the project, and approve.

  3. The agent finishes the login.

    Terminal window
    zkao login --resume

    Each call returns at once. Still waiting for approval means try again later. Authorized means the token is saved. Pass --timeout <seconds> to wait up to that long in one call.

You can approve several projects in one login. Each one gets its own saved token. zkao config use <projectId> switches between them.

For unattended agents, create a token by hand instead and pass it through ZKAO_API_TOKEN and ZKAO_PROJECT_ID. See Authentication.

The CLI checks npm for a newer release at most once a day. When one exists, every command prints a notice on stderr:

zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.

The notice never touches stdout, so piping output to jq keeps working. An agent that sees it should update the CLI and fetch the skill again. Set ZKAO_NO_UPDATE_CHECK=1 to turn the check off.