Validate Agent Parameters over MCP in an Okibi Server
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.
Validate Agent Parameters over MCP in an Okibi Server
Agents invent parameters and send values of the wrong type. This guide sends seven bad calls to a generated Okibi MCP server and records how each one is answered, so you know which mistakes the server catches and which reach the API.
What you will build
A table of seven bad tool calls, each with the error text the agent would see.
tools/call (bad input) -> server check -> isError result with a message the agent can act on
AI Prompt
Using the generated acme-orders MCP server, send these bad calls and record the result of each: 1. orders_list with an unknown argument 2. orders_list with an invalid status 3. orders_list with limit "many" 4. orders_list with limit 500 5. orders_get with no id 6. orders_create with no customer_id 7. a tool name that does not exist Requirements: - Use stdio and set ACME_ORDERS_API_KEY=demo-key. - Report whether each is an `isError` result or a JSON-RPC error. - 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. Send the bad calls
Use a stdio client that sends initialize, then notifications/initialized, then tools/call for each. This script (save it as call.py in the folder that contains ./acme-orders) does that for one call, taking the tool name and its JSON arguments:
import json, os, select, subprocess, sys
os.environ.setdefault("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, method, params=None):
p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "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": "call", "version": "0"}})
p.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n")
r = rpc(2, "tools/call", {"name": sys.argv[1], "arguments": json.loads(sys.argv[2])})
print(json.dumps(r.get("result", r.get("error")), indent=1))
p.terminate()
For example, python3 call.py orders_list '{"statuz":"paid"}'. The results:
| Call | Result |
|---|---|
orders_list {"statuz": "paid"} | isError: unknown argument "statuz"; valid arguments: cursor, customer_id, limit, status, all_pages, fields |
orders_list {"status": "bogus"} | isError: invalid value "bogus" for --status: must be one of [pending paid shipped cancelled] |
orders_list {"limit": "many"} | isError: usage error: invalid argument "many" for "--limit" flag: strconv.ParseInt: parsing "many": invalid syntax |
orders_list {"limit": 500} | isError: API error: GET /orders returned HTTP 400: ... limit must be an integer from 1 to 100 |
orders_get {} | isError: missing required argument(s): id |
orders_create {"items": [{"product_id": "prd_1", "quantity": 1}]} | isError: missing required argument(s): customer_id |
orders_destroy {} | JSON-RPC error -32602: tool 'orders_destroy' not found: tool not found |
2. What the table shows
- An unknown argument is rejected, and the message lists the valid ones, so an agent can self-correct.
- These top-level checks run before any request: unknown argument names, an invalid enum value (
status), a value that cannot be parsed as an integer (limit), and a missing required argument (id,customer_id). Fields nested insideitemsare not among them. - A number outside the allowed range (
limit500) was not rejected by the server. It reached the API, and the API's 400 came back as the error, so range limits are the API's to enforce. - An unknown tool is a protocol error, not an
isErrorresult.
Verify the result
Repeat the first row: orders_list {"statuz": "paid"}.
Expected: an isError: true result whose text starts with unknown argument "statuz" and lists valid arguments.
How it works
The error messages use CLI flag names (--status, --limit), which matches the help text's statement that each tool runs the matching CLI command. Required fields are listed in each tool's input schema (required: [...]).
Common issues
Range limits depend on the spec
The API rejected limit 500 with limit must be an integer from 1 to 100.
The message includes CLI vocabulary
Errors say --status and --limit, which are CLI flags, while the tool argument is status or limit. The mapping is mechanical: customer_id becomes --customer-id, so an agent can translate the message back to the argument it sent.
Missing arguments are all reported
orders_create with no arguments reports both: missing required argument(s): customer_id, items.
verification:
status: verified
tested_at: "2026-10-30"
product_version: "okibi 0.2.11; acme-orders 1.0.0"
command: "python3 call.py orders_list '{\"statuz\":\"paid\"}'"
expected_result: "isError true with: unknown argument \"statuz\"; valid arguments: cursor, customer_id, limit, status, all_pages, fields"
