okibi.ai

Command Palette

Search for a command to run...

Guardrail an MCP Server with Tool Annotations from Okibi

Last updated: 11/18/2026

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) and server.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-orders generated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent; okibi generate --agent does not download the CLI, so wait until okibi status <run-id> --json (<run-id> is build.runId from its output) shows "status": "succeeded", then run okibi pull <run-id> and go build -o ./acme-orders ./cmd/acme-orders inside 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:

TooldestructiveWhy it needs approval
orders_cancel_orderTruecancels an order
orders_updateTruechanges an order
exportTruemarked destructive by the server
importTruemarked destructive by the server
syncTruemarked destructive by the server
workflow_archiveTruemarked destructive by the server
orders_createFalsecreates an order
customers_createFalsecreates a customer
send_feedbackFalsesends 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"

Related Articles