Quick Start

Wrap an MCP server, watch the first signed receipt land, in under five minutes. The path: install the CLI, write a minimal policy, dry-run a tool call, wrap a live MCP server, inspect the receipts.

1. Install the CLI

Chio ships as a single binary. Install it with the hosted installer:

bash

$ curl -fsSL https://www.chio.world/install.sh | sh

Or install with Cargo if you already have Rust:

bash

$ cargo install chio

Verify the installation:

bash

$ chio --version
chio-cli 0.1.0

SDK alternatives

If you prefer to embed Chio directly in your application, use one of the language SDKs instead: @chio-protocol/sdk (TypeScript), chio-py (Python), chio-go (Go), or the chio crate (Rust). The CLI is the fastest way to get started.

2. Write a minimal policy

A policy pins the guard rules; a capability scopes the agent. Create a policy.yaml that allows reading files under a project directory and not much else:

policy.yaml

hushspec: "0.1.0"
name: workspace-readonly

rules:
  # Only allow access to files under ./workspace
  path_allowlist:
    enabled: true
    read:
      - ./workspace/**

  # Block access to secrets and credentials
  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/*.pem"
      - "**/credentials*"

  # Limit to read-only filesystem tools
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file
      - list_directory
      - search_files

  # No shell commands
  shell_commands:
    enabled: false

  # No network egress
  egress:
    enabled: true
    allow: []

  # Cap invocations
  velocity:
    enabled: true
    max_invocations: 100
    window_seconds: 60

  # Validate patches (auto-enabled)
  patch_integrity:
    enabled: true

  # Scan for leaked secrets
  secret_patterns:
    enabled: true

Eight rules, conjunctive: a single deny from any rule denies the call.

3. Check a single tool call

Before running a live server, you can dry-run a tool invocation against your policy using chio check:

bash

# This should be ALLOWED: reading a file under ./workspace
$ chio check --policy ./policy.yaml \
    --tool read_file --server srv-files \
    --params '{"path": "./workspace/README.md"}'

verdict:    ALLOW
tool:       read_file
server:     srv-files
receipt_id: rcpt-019dbbf8-33db-7f21-81c7-aab0427616c8
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799

bash

# This should be DENIED: reading a .env file
$ chio check --policy ./policy.yaml \
    --tool read_file --server srv-files \
    --params '{"path": "./workspace/.env"}'

verdict:    DENY
tool:       read_file
server:     srv-files
reason:     guard denied the request: guard "forbidden-paths" denied the request: path matches forbidden pattern **/.env
receipt_id: rcpt-019dbbf8-3405-74b2-86b5-07ac94779b39
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799

bash

# This should be DENIED: tool not in the allowlist
$ chio check --policy ./policy.yaml \
    --tool write_file --server srv-files \
    --params '{"path": "./workspace/output.txt", "content": "hello"}'

verdict:    DENY
tool:       write_file
server:     srv-files
reason:     requested tool write_file on server srv-files is not in capability scope
receipt_id: rcpt-019dbbf8-33ef-7dc3-9143-25968ddd18e9
policy:     a40c24d0930d773e060fac86dd77e24e68af4cb0a59b1b836759ed63fbaa23b8
source:     d14550004f854d4131839bd2388b3ec9aa3784c898a47f261d434bffbc88d799

Every deny is explained

Chio always reports which guard rejected a call and why. No silent failures, no ambiguous error codes.

4. Wrap an MCP server

Now run a real MCP server with Chio governance. This wraps the official filesystem MCP server:

bash

$ chio --receipt-db ./receipts.sqlite mcp serve \
    --policy ./policy.yaml --server-id srv-files \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

Chio starts, spawns the MCP server as a subprocess, and intercepts every tool call. The proxy is transparent. Your agent connects to Chio the same way it would connect to any MCP server. The top-level --receipt-db flag persists every decision to ./receipts.sqlite so you can inspect them in the next step.

Any MCP server works

Chio is server-agnostic. Swap in any MCP server (databases, APIs, browsers) and the same policy governs all tool calls through it.

5. View receipts

After your agent makes a few tool calls, inspect the cryptographic receipt log:

bash

$ chio --receipt-db ./receipts.sqlite receipt list \
    --tool-server srv-files --limit 3

{"id":"rcpt-019dbbf8-4cfe-...","timestamp":1776975105,"capability_id":"cap-019dbbf8-4cdd-...","tool_server":"srv-files","tool_name":"read_file","action":{"parameters":{"path":"./workspace/README.md"},"parameter_hash":"a3c8a200..."},"decision":{"verdict":"allow"},"content_hash":"42e9fd40...","policy_hash":"a40c24d0...","kernel_key":"25403c1e...","signature":"7be63cdb..."}
{"id":"rcpt-019dbbf8-4d46-...","timestamp":1776975105,"capability_id":"cap-...","tool_server":"srv-files","tool_name":"read_file","action":{"parameters":{"path":"./workspace/.env"},"parameter_hash":"..."},"decision":{"verdict":"deny","reason":"guard \"forbidden-paths\" denied the request","guard":"forbidden-paths"},...}
{"id":"rcpt-019dbbf8-4d78-...","timestamp":1776975106,"capability_id":"cap-...","tool_server":"srv-files","tool_name":"list_directory","action":{"parameters":{"path":"./workspace"},...},"decision":{"verdict":"allow"},...}

The default output is JSON Lines (one receipt per line). Pipe to jq for summaries or filter by server, tool, outcome, or cost using the flags on chio receipt list --help.

Every receipt is cryptographically signed. Receipts are non-repudiable evidence: they prove exactly what was requested, what decision was made, and which guards were evaluated. They cannot be altered after the fact.

Receipts are append-only

Once a receipt is committed, it cannot be modified or deleted. The append-only log ensures any tampering is detectable. Export receipts to external storage for long-term retention.

What just happened

You wrapped an existing MCP server without changing a line of its code, and every tool call that flowed through it produced a signed receipt the security team and the finance team can read from the same artifact. The same shape will hold for the next MCP server, for an A2A endpoint, or for an HTTP API behind Envoy. The policy file you wrote is the only thing that is workload-specific; everything around it is the protocol.

Next steps

Explore the full capabilities of Chio:

Architecture: understand the kernel, guard pipeline, and trust model
Capabilities: scoped, time-bounded, delegatable authority
Policy Schema: full guard configuration options
Receipts: cryptographic audit trail deep dive

PreviousIntroduction NextInstallation