Admin API

An operator holding the admin token can inspect a running MCP edge, rotate its issuing key, revoke capabilities, and drain sessions over the same listener that serves /mcp.

The /admin/* routes belong to chio mcp serve-http. The Trust Control Plane is a separate service with its own routes and credentials.

Agent sessions present the session credential at /mcp; the operator presents the admin token at /admin/*. The admin token permits every admin operation, reads and writes alike, with no read-only role, so restrict the listener at the network boundary. Admin routes share the listener's exposure and run outside the MCP request rate limiter.

1. Give the edge its own admin token

Set CHIO_ADMIN_TOKEN to a value distinct from the MCP session credential in CHIO_AUTH_TOKEN, then start the edge with its three databases in a private state directory.

mkdir -p .chio/admin && chmod 700 .chio .chio/admin
export CHIO_AUTH_TOKEN="$(openssl rand -hex 32)"
export CHIO_ADMIN_TOKEN="$(openssl rand -hex 32)"
chio mcp serve-http \
  --policy policy.yaml --server-id pricing \
  --listen 127.0.0.1:8931 \
  --receipt-db .chio/admin/receipts.db \
  --authority-db .chio/admin/authority.db \
  --session-db .chio/admin/session.db \
  -- python mcp_server.py &
CHIO_ADMIN_PID=$!

You should see the edge listening on 127.0.0.1:8931; stop it later with kill "$CHIO_ADMIN_PID". Without CHIO_ADMIN_TOKEN, the admin door accepts the static session token, and startup refuses a configuration with neither token. The durable admission authority behind --session-db owns revocation and budget state, so give it no separate revocation or budget database flags.

2. Read the node's health

Send the admin token as Authorization: Bearer <admin-token>. The admin door also checks Origin when a request carries one, allowing localhost, 127.0.0.1, and ::1; a server-side client can omit the header. This request selects four fields from an edge with no connected sessions.

$ curl --fail-with-body -sS \
  -H "Authorization: Bearer $CHIO_ADMIN_TOKEN" \
  http://127.0.0.1:8931/admin/health \
  | jq '{ok, serverId: .server.serverId, authMode: .auth.mode, activeSessions: .sessions.activeCount}'

{
  "ok": true,
  "serverId": "demo-server",
  "authMode": "static_bearer",
  "activeSessions": 0
}

You should see ok: true, the server id, the static_bearer auth mode, and zero active sessions. ok confirms that this handler answered. The store flags in the full response describe configuration and say nothing about whether a store is reachable.

$ curl -sS -w '\nHTTP %{http_code}\n' http://127.0.0.1:8931/admin/health

missing or invalid bearer token
HTTP 401

Without the bearer, the edge answers 401 before any handler runs.

3. Rotate the issuing key

POST to /admin/authority with an empty body.

curl -sS -X POST \
  -H "Authorization: Bearer $CHIO_ADMIN_TOKEN" \
  http://127.0.0.1:8931/admin/authority

You should see the new public key in the response. Rotation applies to sessions opened afterward; existing sessions keep the capabilities they hold, and rotation revokes none of them. An edge with no authority backend answers this request with 409.

4. Revoke a capability

POST the capability id as JSON to /admin/revocations.

curl -sS -X POST \
  -H "Authorization: Bearer $CHIO_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"capability_id": "cap-01a8…31f2"}' \
  http://127.0.0.1:8931/admin/revocations

You should see newlyRevoked, which tells a new revocation from a repeat. To revoke everything one session holds, POST to /admin/sessions/{session_id}/trust, then read each capability's revoked field; the top-level flag and the newly-revoked count alone leave a failed attempt unreported.

5. Drain a session

Drain stops a session admitting new work, removes its resumable state, and sets a deadline. Shutdown closes the session and removes it at once. Both take an empty body and act on one session.

curl -sS -X POST \
  -H "Authorization: Bearer $CHIO_ADMIN_TOKEN" \
  "http://127.0.0.1:8931/admin/sessions/$SESSION_ID/drain"

You should see lifecycle.state report the drain. Cleanup later moves the drained session out of the active map. See Session Lifecycle for the states.

With a control URL, authority state lives in the trust control plane

Start the edge with --control-url and --control-token, and authority, receipt, budget, and revocation operations go to the trust control plane. Health keeps local configuration and session data but loads authority remotely. Session trust keeps local session data and resolves each capability's revocation state remotely.

Session listing, drain, shutdown, and metrics stay on the edge. A URL without a token returns 409 on every affected route, health included. Forwarded responses follow the control-plane API: optional fields can be omitted, and budget records carry additional cost data.

A status code names the check that refused

Handler errors carry plain-text bodies, so check the status before parsing a response as JSON. Request extraction can reject a malformed query or JSON body before the handler's authentication checks run.

$ curl -sS -w '\nHTTP %{http_code}\n' \
  -H 'Authorization: Bearer wrong-token' \
  http://127.0.0.1:8931/admin/health

missing or invalid admin bearer token
HTTP 401

Admin endpoints

const DEFAULT_ADMIN_LIST_LIMIT: usize = 50;
const MAX_ADMIN_LIST_LIMIT: usize = 200;

Next: know what the node keeps on disk