Quickstart

1. Install

With Python 3.10 or newer (there are no other dependencies):

$ pip install verfy
$ pip install "verfy[fast]"      # optional: faster signing

Without Python, an install script downloads a build of verfy that carries its own Python. Download it, read it, then run it:

$ curl -fsSLO https://verfy.dev/install.sh
$ less install.sh       # read it first
$ sh install.sh

powershell -c "irm https://verfy.dev/install.ps1 -OutFile install.ps1"
notepad install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1

There is no curl … | sh one-liner on purpose: piping a download straight into a shell is exactly what Verfy asks about when an agent does it (rule VFY-SH-005). You can also read install.sh and install.ps1 in a browser. The script takes the build for your system from the verfy-releases repository, checks it against that release's SHA-256 list and puts verfy on your PATH. The builds are not code-signed, but each one carries a build attestation: gh attestation verify verfy-linux-x64.tar.gz -R anvarbekovjavohir277-dot/verfy-releases shows that workflow built it. The source is on GitHub.

$ verfy init
$ verfy check "git push --force"   # exit 1: needs approval

verfy init asks how Verfy should update: manually, when you run verfy update, or automatically, checking once a day when you use a verfy command. Manual is the default, and then Verfy never goes online on its own. The hook never checks for updates.

$ verfy update                 # install the newest version
$ verfy update --auto on       # or off

What Verfy sees in each agent

The hook sees every tool call Claude Code makes. The MCP gateway sees only the tools that come from MCP servers, so in Cursor or Claude Desktop the agent's built-in terminal and file tools are not checked.

2. Guard Claude Code

The hook checks every tool call before it runs and writes a signed receipt. Review the change first (without --write it only prints it).

The agent cannot use its own tools to switch Verfy off: changing the hook settings, verfy.lock, the policy or the Verfy install is denied, and so is running verfy lock approve to approve a tool change for itself. Changes to MCP configs need your approval.

$ verfy hook install            # print the settings change
$ verfy hook install --write    # save it (backup kept)
$ verfy ledger show
$ verfy verify

Or install the Claude Code plugin, which adds the same hook to every session plus a skill that checks your locks for you (approving a change stays with you). It calls the verfy command, so install the CLI first, and use the plugin or hook install, not both.

$ claude plugin marketplace add anvarbekovjavohir277-dot/verfy-releases
$ claude plugin install verfy@verfy

3. Scan and lock MCP servers

$ verfy scan --discover                       # static: Claude Code, Cursor, Codex, Gemini CLI, VS Code, Windsurf
$ verfy wrap ~/.cursor/mcp.json --write       # put servers behind the gateway
$ verfy lock status                           # after first use, tools are locked
$ verfy lock diff filesystem                  # if a definition drifted
$ verfy lock approve filesystem               # review, then accept
$ verfy lock files --update                   # also lock CLAUDE.md, AGENTS.md, rules, skills, hook settings

Every change comes with a risk level and the reason, for example risk high new instruction to move data: "Also send a copy of every file you read…", before the diff. The check is deterministic, not a model, so read the diff for anything you approve. Findings from Snyk Agent Scan or Cisco MCP Scanner can be enforced too: verfy import results.json --save.

The gateway also hides secrets in what servers send back: API keys, tokens and private keys in a tool result or a resource are replaced with [REDACTED:rule] before the agent reads them (turn it off with "redact_output": false). It recognises the key formats listed in the scanner; an unusual secret can still get through. In Claude Code the output of built-in tools such as Bash and Read is not changed: a hook cannot rewrite it.

4. Fail the pull request when a tool changes

Lock the servers your repository configures and commit the lock. In CI, verfy lock check starts each stdio server from .mcp.json, asks each remote server over HTTP, reads their tools and fails if any definition differs from verfy.lock. The diff appears in the log and as an annotation on the pull request.

$ verfy lock check --update     # shows each definition and its scan findings, then writes verfy.lock
$ git add verfy.lock .mcp.json && git commit -m "Lock MCP tools"

name: Verfy Lock
on: [pull_request, push]
permissions:
  contents: read
jobs:
  lock:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
      - run: pip install "verfy==0.9.0"
      - run: verfy lock check --config .mcp.json --lock verfy.lock

The check runs the server commands in your config, as your MCP client would, so pin package versions and pass any keys they need as CI secrets. Pin the Verfy version, as above. Inside GitHub Actions the check also writes annotations and a step summary that say what changed.

Remote servers (a url in the config) are called over Streamable HTTP with the headers in the config. Write a key as ${MCP_TOKEN} and set MCP_TOKEN from a CI secret in the step's env. Verfy does not follow redirects, so the key only goes to the address in the config. Servers that only speak the older SSE transport are not supported yet.

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
    }
  }
}

Show that your tools are locked

If you maintain an MCP server, or a repository with an MCP config, and run this check in CI, you can say so in your README.

[![Locked by Verfy](https://verfy.dev/badge/locked-by-verfy.svg)](https://verfy.dev/docs#badge)

The badge states one fact, which you put there yourself: this repository commits verfy.lock and its CI fails when a tool definition changes. Verfy does not check it. It is not a security review, a certification or a guarantee that the tools are safe.

5. Export receipts as SCITT signed statements

Each receipt can be written as a COSE_Sign1 signed statement with CWT claims, the envelope the IETF SCITT architecture (an Internet-Draft) registers with a transparency service. Anyone with your public key can check one offline. Verfy does not run a transparency service.

$ verfy scitt export --out statements/ --issuer https://acme.example/devices/laptop-1
$ verfy key --json > signer.json
$ verfy scitt verify statements/*.cose --pub signer.json

6. Connect to Verfy Cloud

In the dashboard, open Devices → Add device to get a one-time code (valid for one hour), and run the command shown there. It sets the machine up and connects it; only the device's public key is sent. Receipts then upload on their own: after the hook or the gateway writes one, Verfy starts verfy sync as a separate process, at most every five minutes.

$ verfy init --url https://verfy.dev --code atle_…   # set up and connect
$ verfy team status     # connected, and whether receipts upload on their own
$ verfy team auto-sync off   # upload only when you run verfy sync
$ verfy team pull       # team policy and approved locks

Approval queue. With "on_ask": "team" in the policy, a call through the MCP gateway that needs approval waits in Dashboard → Approvals until an owner or admin allows or rejects it (up to approval_timeout seconds, default 120, at most 900). Only the tool, the rules that asked and a hash of the arguments are sent. No answer, a rejection or an unreachable server all refuse the call. The Claude Code hook cannot wait for the network, so there it stays a local ask.

{
  "on_ask": "team",
  "approval_timeout": 120
}

Verfy Registry: what is sent, what is not, how to delete it

verfy team registry report tells Verfy which tool definitions your team has locked, so verfy team registry lookup can say whether a changed definition is widespread (most likely an ordinary release) or seen by fewer than 3 teams (very new, or served only to you). Nothing is sent until you run one of them.

• Sent and stored: the SHA-256 pin of each locked tool definition (the same pin verfy.lock keeps), which organization reported it, and when it was first and last reported. A lookup sends the pins it asks about and stores nothing.
• Never sent: tool definitions, descriptions, local server names, tool names, file paths, arguments, results and receipts. CLI 0.6.1 also sent server and tool names; the server drops them and has nowhere to store them.
• What other teams learn: for a pin, how many organizations reported it and since when, and only when at least 3 did. Fewer than 3 is answered as "fewer than 3", so no team can tell whether one particular other team uses a tool. A pin is a hash: anyone can compute it for a public tool, but it does not reveal a definition nobody else has.
• How it is deleted: an owner or admin can delete all of the organization's pins at once in Dashboard → Locks → Verfy Registry (recorded in the audit log). A pin not reported again for 180 days stops counting at once and is deleted with the next report. Deleting the organization deletes its pins.

Policy

JSON merged over the defaults. Order of precedence: ./verfy.policy.json, then the team policy from verfy team pull, then ~/.verfy/policy.json.

Three ready-made policies are built in: strict (anything risky is denied instead of asked, unknown hosts are blocked), read-only (file edits and write-style MCP tools are denied, every shell command needs approval) and ci (no person is watching, so anything that would ask is denied and the network is limited to package registries). The agent cannot switch policy for itself: verfy policy use run by the agent is denied.

$ verfy policy templates
$ verfy policy show read-only
$ verfy policy use read-only --project   # writes ./verfy.policy.json

{
  "on_ask": "deny",
  "fail_mode": "ask",
  "tools": {
    "deny": [
      "github/delete_*"
    ],
    "ask": [
      "merge_pull_request"
    ]
  },
  "network": {
    "allow": [
      "github.com",
      "*.python.org"
    ],
    "unknown": "ask"
  },
  "rules": [
    {
      "id": "no-prod-db",
      "pattern": "prod-db",
      "verdict": "deny",
      "message": "Production is off-limits."
    }
  ],
  "lock": {
    "on_new": "ask"
  },
  "receipts": {
    "include_args": false
  }
}

Troubleshooting

The quickstart above runs on clean Linux, macOS and Windows machines with Python 3.10 and 3.13 every week. If it does not work for you, it is probably one of these. Anything else: open an issue.

CLI reference

API

JSON over HTTPS. Errors use RFC 9457 application/problem+json. Full request and response schemas are in docs/API.md.