Get a CLI and an MCP Server from One Spec with 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.
Get a CLI and an MCP Server from One Spec with Okibi
Maintaining a CLI and an MCP server separately doubles the work. A generated Okibi CLI contains its own MCP server, so one spec produces both, and both call the same code. This guide checks that claim by comparing the two.
What you will build
A comparison of one operation through the CLI and through the MCP tool, showing the same result and the same error.
openapi.json -> okibi generate -> acme-orders (CLI)
acme-orders mcp (MCP, same binary)
AI Prompt
Using the generated acme-orders CLI, show that the CLI and its MCP server are one product. Requirements: - Run `okibi clis products acme-orders --json` and report the products. - Read the same order live and uncached (`--data-source live --no-cache`) through `acme-orders orders get ord_1` and through the MCP tool `orders_get` over stdio, and compare the results as JSON, not as text. - Trigger the same error (a shipped order cancelled) through both and compare the exit code, the `isError` flag and the HTTP status. - Bound every read from the MCP server, and stop it when finished. - 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), withACME_ORDERS_API_KEYexported (export ACME_ORDERS_API_KEY=demo-key; the example server calls the same keyACME_API_KEY) and the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099). -
Python 3 and Okibi CLI
0.2.11, logged in.
1. See what the project ships
okibi clis products acme-orders --json
{ "name": "acme-orders", "products": ["cli", "mcp"] }
One project, two products. The hosted MCP URLs from okibi clis mcp setup acme-orders --json come from the same release.
2. Compare the CLI and the MCP tool on live data
Comparing two cached answers would prove nothing, so this script asks the CLI live and uncached (--data-source live --no-cache) and calls the MCP tool for the same operation, then compares the results as JSON. It does the same for a failure. Save it as parity.py in the folder that contains ./acme-orders:
import atexit, json, os, select, subprocess, sys
os.environ.setdefault("ACME_ORDERS_API_KEY", "demo-key")
# --- the CLI, asked live and uncached
def cli(*args):
p = subprocess.run(["./acme-orders", *args, "--data-source", "live", "--no-cache", "--agent"],
capture_output=True, text=True, timeout=30)
return p.returncode, p.stdout, p.stderr
# --- the MCP server over stdio, with bounded reads
mcp = subprocess.Popen(["./acme-orders", "mcp"], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL, text=True)
atexit.register(mcp.terminate)
def rpc(i, method, params=None):
mcp.stdin.write(json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "params": params or {}}) + "\n")
mcp.stdin.flush()
if not select.select([mcp.stdout], [], [], 10)[0]:
sys.exit("no reply within 10 seconds")
return json.loads(mcp.stdout.readline())
rpc(1, "initialize", {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "parity", "version": "0"}})
mcp.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n")
def tool(name, args):
return rpc(2, "tools/call", {"name": name, "arguments": args})["result"]
# 1. a read: the same order from both, compared as JSON
code, out, _ = cli("orders", "get", "ord_1")
cli_result = json.loads(out)["results"]
mcp_result = json.loads(tool("orders_get", {"id": "ord_1"})["content"][0]["text"])["results"]
print("read parity:", cli_result == mcp_result, "| id", cli_result["id"], "| status", cli_result["status"])
# 2. a failure: the same 409 from both
code, _, err = cli("orders", "cancel", "order", "ord_2")
res = tool("orders_cancel_order", {"id": "ord_2"})
print("failure parity: cli exit", code, "| mcp isError", res.get("isError"),
"| both mention 409:", "409" in err and "409" in res["content"][0]["text"])
python3 parity.py
read parity: True | id ord_1 | status paid failure parity: cli exit 5 | mcp isError True | both mention 409: True
The read compares the whole results object of orders get ord_1 from the CLI with the one the orders_get tool returned, and they are equal. The failure is cancelling the shipped order ord_2: the CLI exits 5 and the MCP tool returns isError: true, and both carry the API's 409. The MCP result is the same JSON as text, plus a structuredContent copy, and on failure it adds a small JSON object with the CLI's exit code ("code":5).
Verify the result
Run python3 parity.py. Expected: read parity: True and failure parity: cli exit 5 | mcp isError True | both mention 409: True. If the first line says False, the two surfaces returned different data for the same order.
How it works
The mcp subcommand is part of every generated CLI. Okibi's help says every tool call runs the matching CLI command, so the tools behave like the commands they mirror.
Common issues
Names differ between the two
The CLI command is orders cancel order, and the MCP tool is orders_cancel_order. Read tool names from tools/list.
The MCP server adds tools the CLI documents separately
context, sql and send_feedback are MCP tools that do not match one operation each. sql has no CLI command.
Hosted and local MCP share the code, not the data
A hosted endpoint cannot reach an API on 127.0.0.1. An unauthenticated call to a hosted endpoint returned 401. After an OAuth sign-in, the hosted endpoints listed 13 tools (7 on /readonly) against the local 18 (9), and a call to orders_get failed with connection refused to 127.0.0.1:8099.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "python3 parity.py" expected_result: "read parity: True, and failure parity: cli exit 5, mcp isError True, both mention 409: True"
