Guardrail an MCP Server with Tool Annotations from Okibi
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
Guardrail an MCP Server with Tool Annotations from Okibi
When an agent has many tools it can pick a write by accident. Generated Okibi MCP servers mark every tool as read-only, destructive or idempotent, and the readonly surface leaves out the tools that write. This guide lists those hints, builds an approval rule that covers every write (not only the destructive ones), and shows what the readonly surface does when an agent calls a write tool anyway.
What you will build
A table of every tool's hints, a rule that lists every tool an agent must ask about before using, and a check that the readonly surface rejects writes.
tools/list -> annotations (readOnlyHint, destructiveHint, idempotentHint) -> "ask first" list
AI Prompt
Using the generated acme-orders MCP server, list which tools are safe and which need approval. Requirements: - Start `./acme-orders mcp` over stdio with ACME_ORDERS_API_KEY=demo-key set and call `tools/list`. - Print each tool's `readOnlyHint`, `destructiveHint` and `idempotentHint`. - List every tool whose `readOnlyHint` is not true. That is the approval list. It includes creates and `send_feedback`, not only the tools with `destructiveHint` true. - On the `readonly` surface, call `orders_create`, `orders_cancel_order` and `send_feedback` and report the error each returns. - Run the verification step below before finishing.
Prerequisites
-
The Acme Orders example files,
openapi.json(a fictional orders API spec) andserver.py(a mock server for it). Download them into your working directory:curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/server.py
-
acme-ordersgenerated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent;okibi generate --agentdoes not download the CLI, so wait untilokibi status <run-id> --json(<run-id>isbuild.runIdfrom its output) shows"status": "succeeded", then runokibi pull <run-id>andgo build -o ./acme-orders ./cmd/acme-ordersinside the project), with the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099). -
Python 3 and Okibi CLI
0.2.11.
1. List the annotations
Save this as annotations.py in the folder that contains ./acme-orders, then run python3 annotations.py.
import subprocess, json, os, select
os.environ["ACME_ORDERS_API_KEY"] = "demo-key"
p = subprocess.Popen(["./acme-orders", "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL, text=True)
def rpc(i, m, params=None):
p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": m, "params": params or {}}) + "\n"); p.stdin.flush()
if not select.select([p.stdout], [], [], 10)[0]: raise SystemExit("no reply within 10 seconds")
return json.loads(p.stdout.readline())
rpc(1, "initialize", {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "a", "version": "0"}})
p.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n")
for t in sorted(rpc(2, "tools/list")["result"]["tools"], key=lambda t: t["name"]):
a = t.get("annotations", {})
print(f'{t["name"]:20} read-only={a.get("readOnlyHint")} destructive={a.get("destructiveHint")} idempotent={a.get("idempotentHint")}')
p.terminate()
context read-only=True destructive=False idempotent=True customers_create read-only=False destructive=False idempotent=False customers_get read-only=True destructive=False idempotent=True customers_list read-only=True destructive=False idempotent=True export read-only=False destructive=True idempotent=False import read-only=False destructive=True idempotent=False orders_cancel_order read-only=False destructive=True idempotent=False orders_create read-only=False destructive=False idempotent=False orders_get read-only=True destructive=False idempotent=True orders_list read-only=True destructive=False idempotent=True orders_update read-only=False destructive=True idempotent=False products_list read-only=True destructive=False idempotent=True search read-only=True destructive=False idempotent=True send_feedback read-only=False destructive=False idempotent=False sql read-only=True destructive=False idempotent=True sync read-only=False destructive=True idempotent=False workflow_archive read-only=False destructive=True idempotent=False workflow_status read-only=True destructive=False idempotent=True
2. Build the approval rule
The rule is: ask for approval for every tool whose read-only value is not True. In this server that is nine tools:
| Tool | destructive | Why it needs approval |
|---|---|---|
orders_cancel_order | True | cancels an order |
orders_update | True | changes an order |
export | True | marked destructive by the server |
import | True | marked destructive by the server |
sync | True | marked destructive by the server |
workflow_archive | True | marked destructive by the server |
orders_create | False | creates an order |
customers_create | False | creates a customer |
send_feedback | False | sends text to the publisher over the network |
A rule that gates only destructive=True covers six of the nine and leaves out the two tools that create records and the one that sends data off the machine. The nine other tools are read-only (context, customers_get, customers_list, orders_get, orders_list, products_list, search, sql, workflow_status), and the readonly surface serves exactly those.
To print the approval list, add this to the end of annotations.py, before p.terminate():
tools = rpc(2, "tools/list")["result"]["tools"]
print("approval list:", sorted(t["name"] for t in tools if not t.get("annotations", {}).get("readOnlyHint", False)))
approval list: ['customers_create', 'export', 'import', 'orders_cancel_order', 'orders_create', 'orders_update', 'send_feedback', 'sync', 'workflow_archive']
3. See what the readonly surface does with a write
Run the same script with the server command changed to ["./acme-orders", "mcp", "--tools", "readonly"]. It lists 9 tools. Then call three write tools by name with tools/call:
orders_create -> {"code": -32602, "message": "tool 'orders_create' not found: tool not found"}
orders_cancel_order -> {"code": -32602, "message": "tool 'orders_cancel_order' not found: tool not found"}
send_feedback -> {"code": -32602, "message": "tool 'send_feedback' not found: tool not found"}
The tools are not served, so the calls fail with a protocol error and nothing reaches the API. A client that hides readonly tools from the list is not enough on its own, because the server also rejects the call.
Verify the result
Run the script against ["./acme-orders", "mcp"] and print the approval list. Expected: the nine tools above. Then run it against ["./acme-orders", "mcp", "--tools", "readonly"], call orders_create, and expect the JSON-RPC error tool 'orders_create' not found. (Running ./acme-orders mcp --tools readonly on its own prints nothing, because it waits for JSON-RPC on standard input.)
How it works
The server marks reads as read-only and idempotent, and marks update, cancel and bulk tools as destructive. Annotations are hints that the server sends to the client. An MCP client decides what to do with them, and the MCP specification calls them advisory. They do not authorize anything. The readonly surface is different: it does not serve the write tools at all, so a call to one fails.
Common issues
Gating destructive alone misses writes
orders_create and customers_create have destructive=False and still create records. send_feedback has destructive=False and still sends your text to the CLI's publisher. Gate on readOnlyHint instead.
Hints are advisory
A client may ignore them, and a server's hints can be wrong for your policy. Keep authorization (who may call what) separate from annotations, and use --tools readonly or the /readonly URL when writes must be impossible.
export and sync are marked destructive
Both are on the destructive list even though sync writes only the local database. Treat the hint as a prompt to confirm, not as proof that API data changes.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "python3 annotations.py" expected_result: "the approval list contains the 9 non-read-only tools"
