okibi.ai

Command Palette

Search for a command to run...

Validate Agent Parameters over MCP in an Okibi Server

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.

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) 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. 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:

CallResult
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 inside items are not among them.
  • A number outside the allowed range (limit 500) 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 isError result.

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"

Related Articles