Documentation

Running Zoro

Zoro stands between AI agents and the tools they use. Before an agent touches a tool, Zoro checks that the tool is exactly the version that was examined and approved. If anything changed, the call does not happen, you see what changed and why it matters, and the event goes into a public record.

Try it live, with nothing to install: https://zoro-mcp-guard.vercel.app/. Launch an attack in the Attack Lab, then check the verdict on Verify.

Set it up

Five minutes, on your own machine.

Understand it

The five parts and what each does.

Trust it

Promises, limits and privacy.

Quick start

In plain words: You run two small programs on your computer: the Zoro daemon (the guard) and this website (your control panel). Then you point your AI app at Zoro instead of straight at its tools.

You need Node.js 22.13 or newer (24 recommended) and pnpm 10 (npm i -g pnpm). If pnpm is not found after that, npx pnpm@10 <command> works too.

terminal

git clone https://github.com/Nouman-wp/Zoro-MCPGuard.git zoro && cd zoro
pnpm install
cp .env.example .env        # optional: keys for the AI layer, ENSv2, Hedera and World ID
pnpm dev                    # daemon on :7420, web on :3000

1
Sign in to your Console
The daemon prints a link when it starts (Console login : http://localhost:3000/console/login?token=…). Open it. The token is also saved as console.token in Zoro’s data folder: %LOCALAPPDATA%\Zoro on Windows, ~/Library/Application Support/Zoro on macOS, ~/.local/share/zoro on Linux.
2
Connect your AI apps
Open Console → Onboarding. Zoro asks permission to read your MCP client settings (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Cline), lists every server, and routes the ones you pick through the gateway. Each original file is backed up first and can be restored in one click.
3
Restart your AI app
It now talks to Zoro through a small bridge. Every tool is fingerprinted, checked and sealed before the agent can see it.
4
Watch it work
Open the Attack Lab and launch a real attack against demo servers.

Apps that speak Streamable HTTP can connect directly to http://127.0.0.1:7420/mcp with the header x-zoro-gateway-token (value in gateway.token in the data folder). A local install has its own private Console; a hosted deployment runs a separate daemon with its own Console.

How Zoro is built

In plain words: Five parts. A gateway that every call passes through, an inspector that checks tools, a public name book and a public diary where verdicts are recorded, and a human check for risky actions.

Gateway

The door every tool call walks through.

An MCP server to your clients and an MCP client to each upstream server (stdio or Streamable HTTP). It serves only sealed definitions and checks every call: seal, policy, data flows, approvals, then Output Shield on the result.

Sentinel

The inspector that checks each new tool version.

Rule-based checks, a diff against the last sealed version, AI review (two configurations for high-impact tools), sandbox detonation for Lab servers, and a signed (EIP-191) attestation over the verdict.

Registry (ENS)

A public name book where verdicts are written.

ENSv2 on Sepolia. Each server gets its own Permissioned Resolver; only the Auditor may write verdicts. Version names resolve by wildcard and current points at the live one.

Ledger (Hedera)

A public diary with time stamps nobody can change.

Hedera Consensus Service topics for verdicts and Lab records, Merkle commitments over your local audit log, and badge tokens that are burned when a seal is revoked.

Human Seal (World ID)

Proof that a real person approved one exact action.

World ID 4.0 Proof of Human, requested with relying-party signatures, bound to one approval and its action digest, verified on the server (including the credential), usable once.

Configuration

In plain words: Everything is optional. With no keys at all Zoro still protects you on your own machine; each missing piece shows up in the Console as “not configured” instead of being silently skipped.

Copy .env.example to .env at the repository root and fill in what you have. The most useful one is GROQ_API_KEY (free): without it, clean tool versions stay “pending” because Zoro never guesses that something is safe.

.env

# Sentinel AI layer and Ask Zoro (Groq free tier, any OpenAI-compatible API works)
GROQ_API_KEY=                 # free key from console.groq.com; enables AI review and Ask Zoro
SENTINEL_MODEL=openai/gpt-oss-120b
SENTINEL_REQUIRE_AI=true      # false = development mode (seals record that AI did not run)

# ENSv2 registry (Sepolia)
ZORO_ENS_ROOT=yourname.eth     # a .eth name you own on ENSv2
ENS_OPERATOR_PRIVATE_KEY=      # owner of the root; then run: pnpm setup:ens
ZORO_AUDITOR_PRIVATE_KEY=      # Auditor role + attestation key (generated if empty)

# Hedera ledger
HEDERA_OPERATOR_ID=0.0.x
HEDERA_OPERATOR_KEY=           # then run: pnpm setup:hedera

# World ID (Human Seal)
WORLD_APP_ID=app_…
WORLD_RP_ID=rp_…
WORLD_SIGNING_KEY=…
WORLD_ENVIRONMENT=staging      # staging = World ID Simulator; sandbox = World ID Sandbox app; production = World App

Registry, ledger and Human Seal

In plain words: Two setup commands create Zoro’s public records for you. After that, every verdict is published automatically in the background; your agent never waits for it.

1
Hedera
pnpm setup:hedera creates the registry, Lab and organization topics and the badge token, and writes their IDs into .env.
2
ENS
pnpm setup:ens deploys a registry and resolver for your root name through the ENSv2 factory, gives the Auditor its writing role, and registers the Lab namespace.

Both commands are safe to run twice. Writes are retried if a network is slow, and every onchain record in the Console links to its explorer page (Sepolia Etherscan, the ENS app, HashScan). Read more on the ENS, Hedera and World ID track pages.

Fingerprints (zoro-canon/1)

In plain words: Zoro turns every tool description into a short unique code, its fingerprint. Change a single character, even an invisible one, and the fingerprint changes. That is how Zoro notices a tool was swapped.

The whole definition is covered: every field the server sent, not a chosen subset.
Object keys are sorted by UTF-16 code unit order (as in RFC 8785); undefined members are dropped; arrays keep their order; numbers use the shortest round-trip form; null is kept.
Strings are only JSON-escaped. No Unicode normalization, trimming or whitespace folding, so invisible, direction-override and look-alike characters are part of the fingerprint (and reported separately as findings).
fingerprint = sha256("zoro-canon/1\n" + kind + "\n" + canonicalJson(definition)), where kind is tool, prompt or resource_template.
The manifest root commits to the sorted list of (kind, name, fingerprint) plus the server name, version and artifact identity, so added, removed and renamed entries change it.

The code is in Backend/core/src/canonical.ts; Zoro Verify runs the same code in your browser.

How a call is judged

In plain words: Every call goes through the same checklist, in the same order. The strictest answer wins, and Zoro records which rule decided, so you can always see why.

1 Server mode
2 Seal & trust chain
3 Verdict handling
4 Tool permissions
5 Agent rules
6 High-impact asks
7 Argument limits
8 Rate limits
9 Time windows
10 Data flows

The full trace is kept for every call. Observe mode records what would have been decided but never blocks.

Any change that weakens protection (a relaxed action, a wider allowlist, a higher threshold, a removed rule, observe mode) needs explicit confirmation, and a Human Seal where the policy requires one. Policy simulation replays your recorded calls against a proposed policy before you save it.

Promises Zoro keeps

In plain words: Seven rules Zoro never breaks, whatever the configuration.

1No unverified tool text reaches the model.

2No call runs against an unsealed tool version, unless a verified human overrides that one action, and the override is recorded.

3Every verdict can be checked by anyone.

4Every decision can be explained.

5Your data stays with you.

6Fail closed, never fail silent.

7No overclaiming.

Attacks it handles

In plain words: Each attack below is something a bad tool can try. Next to it: what Zoro does about it. You can launch most of them yourself in the Attack Lab.

A tool quietly changes its description (rug pull)

Pins the approved version and quarantines any change.

A local tool changes its code

Re-checks the program’s identity on every start.

Hidden or manipulative instructions (poisoning, shadowing)

Rule-based and AI findings, plus a radar for tools that collide across servers.

Private data leaking to another server

The data-flow guard tracks where data comes from and holds risky flows for a person.

A tool returns instructions in its output

Output Shield marks, redacts or blocks them.

Forged seals or a compromised auditor

Role-restricted registry writes, signatures, ledger cross-checks and public disputes.

Reusing or downgrading an approval

Human Seals are tied to one approval and its exact action, work once, and must be a World ID Proof of Human, checked on the server, not in the browser.

Honest limits

In plain words: Zoro is strong, not magic. Here is what it cannot do.

A remote server can change what its code does without changing any description or version. Zoro cannot see inside someone else’s server; it narrows the gap with identity checks, behaviour baselines, Output Shield, argument limits and network revocations.
The data-flow guard sees tool inputs and outputs, not the model’s thinking. Data that is transformed or encoded can slip past matching.
Content injection cannot be fully solved by filtering. Output Shield lowers and exposes the risk; it does not stop every prompt injection.
Sandbox detonation is only available for Attack Lab servers.
Out of scope: a fully compromised computer, a compromised model inside the client, and apps that connect to servers without going through Zoro (Zoro flags those settings).

What leaves your machine

In plain words: Only facts about tools are ever published. Your prompts, files, results and identity stay on your computer.

ENS and Hedera receive information about tools (fingerprints, verdicts, hashes, signatures), never your prompts, arguments, results, files or identity.
Your own activity is anchored only as Merkle roots over your local audit log; individual calls are never written onchain.
The AI layer receives public tool definitions. Ask Zoro sends your question and the records it reads to the AI provider only when you use it.
World ID receives the action digest as the proof signal, never the action itself, and Zoro stores only the nullifier for that approval.
Exposure reports are generated entirely on your machine.