Migrate from MCP to Chio

Moving an MCP connection behind the kernel changes one entry in your client's configuration. The server binary, its arguments, and your client's MCP library stay as they are, and from the first call through chio mcp serve the kernel admits each tools/call and signs a receipt for it.

Save the connection's current executable, arguments, environment, and working directory before you edit the launcher. Then rerun the same representative work through Chio, including one request your policy must refuse.

1. Read the tool names your server exposes

Grants and presets match server ids and tool names exactly, so read the live names before you write a rule. Put your own server command after --.

chio mcp wrap --server-id workspace --print-scopes \
  -- npx -y @modelcontextprotocol/server-filesystem ./workspace

[[capability]]
tool = "read_text_file"
scope = "read"
urn = "urn:chio:scope:tool:read"

You should see one [[capability]] block per tool. The filesystem package's read tool is read_text_file, while the code-agent preset grants read_file; write the policy for the names you see. The policy and captured checks below use read_file as their sample name. Wrap an MCP Server walks through the full scaffold.

2. Start from a deny-by-default policy

Allow one tool and refuse sensitive paths. Every other tool is denied, which gives you a baseline to widen one tool at a time.

hushspec: "0.1.0"
name: migration-baseline

rules:
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file

  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/.env.*"
      - "**/.ssh/**"
      - "**/*.pem"
      - "**/*.key"
      - "**/credentials*"
    exceptions: []

  secret_patterns:
    enabled: true

  velocity:
    enabled: true
    max_invocations_per_window: 100
    window_secs: 60

The agent can now call read_file on anything outside the forbidden patterns. Expect the first run to refuse tools that plain MCP allowed; add each one to the allow list with the guards it needs. Write a Policy covers the full rule set.

# No policy file required: the preset is built in.
chio --session-db ./session.db --receipt-db ./receipts.db \
    mcp serve --preset code-agent --server-id workspace \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

3. Check the policy before the agent meets it

Run chio check against the policy in full mode. This policy enables secret_patterns, which reads the tool's output, so --output-fixture takes a path to a JSON file standing in for the result; inline JSON is rejected.

$ chio --session-db ./admission-1.db --receipt-db ./receipts.db \
  check --policy ./policy.yaml --tool read_file \
  --params '{"path": "./workspace/README.md"}' \
  --mode full --output-fixture ./output-fixture.json

verdict:    ALLOW
tool:       read_file
server:     *
receipt_id: 8cf7f0cb9468defc881ba90137f5978636c7dc7e0d9911f5ed6f15061e2a9b84
policy:     60df7b477be3ee42dfbe33fec4bac9b95628ac5fcb8ae526e439b69cd322acd4
source:     b91346824d582bfba3f3fad1eb0627a2ede05f7c0fc778a93d224d055449c21d
mode:       full
fixture:    true

You should see ALLOW. Then check the two refusals the baseline exists to produce. The first is a scope refusal: write_file is outside the allow list, so the request never reaches a guard.

$ chio --session-db ./admission-2.db --receipt-db ./receipts.db \
  check --policy ./policy.yaml --tool write_file \
  --params '{"path": "./workspace/output.txt", "content": "hi"}' \
  --mode full --output-fixture ./output-fixture.json

verdict:    DENY
tool:       write_file
server:     *
reason:     requested tool write_file on server * is not in capability scope
receipt_id: 41cfc48636745c6113a5ad03f80c89a82d3cf0e1884566391ae7ddc31f9ad465
policy:     60df7b477be3ee42dfbe33fec4bac9b95628ac5fcb8ae526e439b69cd322acd4
source:     b91346824d582bfba3f3fad1eb0627a2ede05f7c0fc778a93d224d055449c21d
mode:       full
fixture:    true

The second is a guard denial. Its reason: line names the registered top-level guard, the compiled pipeline; the rule block that fired is recorded in the receipt, in step 6.

$ chio --session-db ./admission-3.db --receipt-db ./receipts.db \
  check --policy ./policy.yaml --tool read_file \
  --params '{"path": "./workspace/.env"}' \
  --mode full --output-fixture ./output-fixture.json

verdict:    DENY
tool:       read_file
server:     *
reason:     guard denied the request: guard "guard-pipeline" denied the request
receipt_id: b1c490817e95b7b8a3340f1fc0a8d79a4a83f9a4cbc3773241f35b387345d58b
policy:     60df7b477be3ee42dfbe33fec4bac9b95628ac5fcb8ae526e439b69cd322acd4
source:     b91346824d582bfba3f3fad1eb0627a2ede05f7c0fc778a93d224d055449c21d
mode:       full
fixture:    true

Without --mode full, the check stops with CHIO-CLI-PREFLIGHT-NEEDS-OUTPUT: preflight never runs the tool, so it cannot evaluate post-output guards.

4. Change the client's launcher

Point the client's server entry at chio. Everything after -- is the literal command Chio runs as the child process, so copy your original command verbatim.

{
  "mcpServers": {
    "workspace": {
      "command": "chio",
      "args": [
        "--session-db", "/abs/path/session.db",
        "--receipt-db", "/abs/path/receipts.db",
        "mcp", "serve",
        "--policy", "/abs/path/policy.yaml",
        "--server-id", "workspace",
        "--",
        "npx", "-y",
        "@modelcontextprotocol/server-filesystem", "./workspace"
      ]
    }
  }
}

Use absolute paths for the policy and both databases: the client chooses the working directory, so a path that resolves in your shell may not resolve under the client. Restart the client. If you run several MCP servers, migrate them one at a time; each wrapped server takes its own --server-id, and the others keep working unwrapped.

A launcher missing either database flag exits before it spawns anything, and the preset does not exempt it:

$ chio mcp serve --preset code-agent --server-id fs \
  -- npx -y @modelcontextprotocol/server-filesystem ./workspace

error[CHIO-CLI-ADMISSION-STORE-REQUIRED]: durable admission needs a session database so operations and tool outcomes survive a restart
  help: pass --session-db <path>
  code: urn:chio:error:cli:admission-store-required
  docs: https://chio.computer/docs/reference/errors#error-cli-admission-store-required

5. Confirm one permitted call and one refusal

Each check is a command with an answer.

1. The edge starts. Run your chio mcp serve line from a shell in the client's working directory. It stays running; an immediate exit prints the missing flag.
2. The client sees the same tools. Compare the tool list before and after: names, descriptions, and schemas match.
3. An ordinary call passes. Ask the agent for its most routine task, then run chio --receipt-db <path> receipt list --admin-all and find a receipt whose decision.verdict is allow.
4. A forbidden call fails. Ask it to read a .env. The agent gets an error, and the store holds a deny whose evidence[].guard_name is forbidden-path. A migration with no captured deny is untested.

6. Export the receipts and verify them offline

Read the receipts back with the path the edge wrote. A local read names its boundary with exactly one of --tenant <id> or --admin-all, and output is JSON Lines whatever format flags you pass. The three checks from step 3, projected down to the decision:

$ chio --receipt-db ./receipts.db receipt list --admin-all \
  | jq -c '{tool: .tool_name, verdict: .decision.verdict,
$             reason: .decision.reason, guard: .decision.guard,
$             evidence: [.evidence[]?.guard_name]}'

{"tool":"read_file","verdict":"allow","reason":null,"guard":null,"evidence":[]}
{"tool":"write_file","verdict":"deny","reason":"requested tool write_file on server * is not in capability scope","guard":"kernel","evidence":[]}
{"tool":"read_file","verdict":"deny","reason":"guard denied the request: guard \"guard-pipeline\" denied the request","guard":"kernel","evidence":["forbidden-path"]}

You should see guard: "kernel" on both denials and forbidden-path in evidence[].guard_name on the guard denial. Filter and alert on that field; the reason string names only the pipeline. Pipe the same stream to jq for decision counts, denied tools, and cost histograms. Then export a package with the same explicit boundary, and verify it without contacting the kernel.

$ chio --receipt-db ./receipts.db evidence export --output ./pkg --admin-all

$ chio evidence verify --input ./pkg

evidence package verified
tool_receipts:          3
child_receipts:         0
checkpoints:            0
checkpoint_publications: 0
checkpoint_witnesses:   0
checkpoint_consistency_proofs: 0
checkpoint_equivocations: 0
capability_lineage:     3
inclusion_proofs:       0
uncheckpointed_receipts: 3
authorized_receipts:     1
trace_observations:      0
advisory_evaluations:    0
verified_files:         12
child_receipt_scope:    FullQueryWindow
transparency_preview_logs: 0
publication_state:      transparency_preview

You should see evidence package verified with three tool receipts and their capability lineage. The package bundles receipts, capability lineage, checkpoints, and inclusion proofs, and a gap or a mutation fails verification with a non-zero exit. The audit trail starts at the first call through chio mcp serve; calls made before the migration have no receipts.

$ chio --receipt-db ./receipts.db receipt list --admin-all \
  | jq 'select(.action.parameters.path == "./workspace/.env") | del(.metadata)'

{
  "id": "b1c490817e95b7b8a3340f1fc0a8d79a4a83f9a4cbc3773241f35b387345d58b",
  "timestamp": 1788597783,
  "capability_id": "cap-01a070bc-4b26-7422-bf79-e5a64fe86edd",
  "tool_server": "*",
  "tool_name": "read_file",
  "action": {
    "parameters": {
      "path": "./workspace/.env"
    },
    "parameter_hash": "01a3da31bac3d250f150339143ffea8d946d0b78c2373e0470878a1ab14b802e"
  },
  "decision": {
    "verdict": "deny",
    "reason": "guard denied the request: guard \"guard-pipeline\" denied the request",
    "guard": "kernel"
  },
  "receipt_kind": "mediated_decision",
  "boundary_class": "prevent",
  "tool_origin": "caller_executed",
  "redaction_mode": "none",
  "content_hash": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
  "policy_hash": "60df7b477be3ee42dfbe33fec4bac9b95628ac5fcb8ae526e439b69cd322acd4",
  "evidence": [
    {
      "guard_name": "forbidden-path",
      "verdict": false,
      "details": "action=deny; reason=guard denied request"
    }
  ],
  "trust_level": "mediated",
  "kernel_key": "50e420c0095f75b0dfa7d5b0d22763207a5afcd04ab08b035f5bd997018bc30d",
  "signature": "35ebb666768125063f446bb07065d9f3192f1af733b3aba2975ed6c2fd3c8c59c06b4eff9e08e1095bcd9d398e37042ee8646e8c17a13cbb57228102c18c4306"
}

Read more in Verify Receipts Offline.

$ chio --session-db ./admission-0.db --receipt-db ./receipts.db \
  check --policy ./policy.yaml --tool read_file \
  --params '{"path": "./workspace/README.md"}'

error[CHIO-CLI-PREFLIGHT-NEEDS-OUTPUT]: preflight cannot evaluate post-output guards, because it never runs the tool
  help: run the check with --mode full --output-fixture <JSON> so output-sensitive guards see explicit fixture output
  code: urn:chio:error:cli:preflight-needs-output
  docs: https://chio.computer/docs/reference/errors#error-cli-preflight-needs-output

$ chio --receipt-db ./receipts.db evidence export --output ./pkg

error[CHIO-KERNEL-RECEIPT-READ-CONTEXT-MISSING]: evidence export needs a read boundary
  help: pass --tenant <id> to export one tenant's receipts, or --admin-all to export every tenant as the operator
  code: urn:chio:error:kernel:receipt-read-context-missing
  docs: https://chio.computer/docs/reference/errors#error-kernel-receipt-read-context-missing