Connect a Coding Agent

Put Claude Code's filesystem tools behind the kernel, then read the signed receipt for each call made through them.

On this page

Register Chio as the workspace MCP server in Claude Code, in the pricing project. From then on, each file read or write the assistant sends through that server is admitted by the kernel under the code-agent preset, and each decision is signed into a receipt store in the project.

Claude Code starts Chio as an ordinary stdio server. Chio launches the filesystem server behind it and hands every tools/call to the kernel first. You will see the assistant read src/pricing.py, fail to read .env, and the receipt for each.

Start

MCP edgeChoose an outcome.

κcapabilityσscopegguardsBbudget

Every check passes, so the kernel invokes the server

The client launches Chio, and Chio launches the server as a child process over stdio. The edge resolves tools/call against the active grant and hands it to the kernel, which invokes the server and signs the receipt before the result returns. The Mediated Call.

One Claude Code tools/call through Chio's MCP edge to the kernel and the filesystem server it launched. Claude Code's other tools, output checks after dispatch, and host confinement are left out.Wrap an MCP Server

1. Register Chio as the workspace server

Before you begin

Use a Linux or macOS shell with Chio, Claude Code, Node.js with npx, and jq. Install the CLI with curl -fsSL https://chio.computer/install.sh | sh. Complete the Quickstart first: it creates the quickstart directory this guide works in.

Starts from the quickstart directory that chio new quickstart created. Create a private state directory and register Chio as the server Claude Code starts. The code-agent preset supplies the policy.

Terminal · quickstartbash

mkdir -p .chio
chmod 700 .chio
claude mcp add workspace -- chio \
  --receipt-db .chio/receipts.db \
  --session-db .chio/session.db \
  mcp serve --preset code-agent --server-id workspace -- \
  npx -y @modelcontextprotocol/server-filesystem@2026.8.31 .

The final dot selects the current project as the filesystem server's root. Use a narrower directory when the task needs only part of the project. Mode 700 keeps the receipt and session databases in .chio readable by your user alone.

2. Confirm that Claude Code starts Chio

Terminal · quickstartbash

claude mcp get workspace

You should see the workspace server with a command that begins chio --receipt-db .chio/receipts.db. Claude Code now launches Chio, and Chio launches the filesystem server, each time a session opens in this project. Chio answers Claude Code's tools/list from the grant without a kernel call. Each tools/call that follows goes to the kernel.

3. Read a file through the kernel

Start a Claude Code session and ask for the pricing module by tool name.

Terminal · quickstartbash

claude

Claude Code · chattext

Use the workspace/read_file MCP tool to read src/pricing.py.

Returned content · first lines

from decimal import ROUND_HALF_UP, Decimal

PRICES: dict[str, Decimal] = {
    "sku-118": Decimal("24.00"),

You should see the price table that quote() reads. The preset grants read_file, list_directory, search_files, write_file, edit_file, and create_directory on server workspace, each with a one-hour lifetime, so the kernel admitted the call and dispatched it.

4. Ask for a secret and see the refusal

In the same session, ask for the file that holds the project's credentials.

Claude Code · chattext

Use the workspace/read_file MCP tool to read .env.

You should see Claude Code report a tool error. The preset's forbidden_path guard matches **/.env and refuses the call before the filesystem server runs. The same guard covers .env.*, .git/**, .ssh/**, .aws/credentials, .netrc, .npmrc, private keys, and *.pem files.

5. Read both decisions in the receipt store

Terminal · quickstartbash

chio --receipt-db .chio/receipts.db receipt list \
  --admin-all --tool-server workspace \
  | jq -r '[.decision.verdict, .tool_name, .id] | @tsv'

Output

allow   read_file   rcpt-01a9…5b20
deny    read_file   rcpt-01a9…6f3d

You should see one row per call: the read of src/pricing.py as allow, the .env request as deny, each with its receipt id. Your ids differ; the order and verdicts match.

Pass an id to chio receipt explain with the same receipt database and the --admin-all read boundary to see which check decided. Both receipt list and receipt explain fail closed without --admin-all or a --tenant.

A missing receipt shows where the call went instead

Every decision the kernel makes leaves a receipt, refusals included. When a call has no receipt, it stopped before the kernel or never reached Chio. Check, in order:

The tool. The agent used the registered workspace MCP tool, not a built-in one.
The launcher. The Chio process Claude Code starts can find npx on its path.
The store. You are reading .chio/receipts.db relative to the same project directory.

A bridge refusal before kernel evaluation appears only as an MCP error. Read that response before you change the policy. For a worked example of a permitted read and a refused write, see Secure an agent.

The kernel governs the workspace tools, and the host governs the rest

This connection governs the filesystem tools served through it. Claude Code's other tools and its direct access to the host stay on their own path. When the deployment requires complete mediation, close those paths in the host with a restricted launcher and host confinement.

Next: replace the preset with your own policy

Write a policyReplace the preset with the permissions your project needs.Export the evidenceHand a verifier a package of signed records.Run a governed coding taskWork on a fork of one commit, with process recovery and a patch the recipient verifies.

PreviousShare a Worker Budget NextConnect Hermes