okibi.ai

Command Palette

Search for a command to run...

Serve a Generated CLI as an MCP Server with the Okibi CLI

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.

Serve a Generated CLI as an MCP Server with the Okibi CLI

Every CLI that Okibi generates includes an mcp command that serves its commands as MCP tools, and Okibi also hosts an MCP endpoint for each CLI. The tools run the same code as the CLI commands, so behavior and errors match.

What you will build

A local stdio MCP server from the acme-orders CLI generated from the example spec, queried with raw JSON-RPC, plus the hosted MCP URLs for the same CLI.

acme-orders mcp (stdio)  <-  initialize / tools/list / tools/call  <-  MCP client
okibi clis mcp setup     ->  hosted URLs: compact, full, readonly

AI Prompt

Using the Okibi CLI and a generated CLI named acme-orders, expose the CLI to agents over MCP.

Requirements:
- The generated CLI serves MCP with `acme-orders mcp`. The default transport is stdio.
- The server reads `ACME_ORDERS_API_KEY` from its environment, so export it before starting it. The API address is stored in the CLI. Set `ACME_ORDERS_BASE_URL_OVERRIDE` only to override it.
- `--tools` selects the surface: `compact` (default), `full` (one tool per operation) or `readonly` (no writes). `--read-only` is the same as `--tools readonly`.
- The supported `--transport` values are `stdio` (default), `http` and `lambda`. `lambda` runs only inside AWS Lambda. Over HTTP, a non-loopback `--addr` requires the `ACME_ORDERS_MCP_AUTH_TOKEN` environment variable.
- Read tool names from `tools/list`. Do not assume them from the CLI command names.
- `okibi clis mcp setup acme-orders --json` lists the hosted URLs and client configuration snippets.
- A failing tool call returns a result with `isError: true` and the error text.
- 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 binary at ./acme-orders, and the Acme Orders example API running on http://127.0.0.1:8099 (ACME_API_KEY=demo-key python3 server.py --port 8099). The example API is two files, openapi.json and server.py.

  • This variable exported in the shell that starts the server:

    export ACME_ORDERS_API_KEY=demo-key
    
  • Okibi CLI 0.2.11, logged in.

  • Python 3 for the JSON-RPC example. Any MCP client works in its place.

Note: Tool descriptions and responses are trimmed, and the okibi clis mcp setup output has more fields than shown (runId, mcpServer, brandedUrl, connections).

1. See what the server offers

./acme-orders mcp --help

The help text lists three surfaces (compact, full, readonly) and four transports: stdio (default), http, handle and lambda. handle and lambda are labelled as hosting transports. The --transport flag accepts stdio, http and lambda. handle is rejected (see Common issues). lambda exits with an error outside AWS Lambda, and http serves until stopped.

2. Call the server over stdio

Save this script as mcp_demo.py in the folder that contains ./acme-orders (the path is relative), export ACME_ORDERS_API_KEY=demo-key, and run it with python3 mcp_demo.py. It starts the server (./acme-orders mcp, stdio is the default), initializes it, lists the tools and calls two of them.

import subprocess, json, select, atexit
p = subprocess.Popen(["./acme-orders", "mcp"], stdin=subprocess.PIPE,
                     stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)
atexit.register(p.terminate)
def send(m): p.stdin.write(json.dumps(m) + "\n"); p.stdin.flush()
def recv():
    if not select.select([p.stdout], [], [], 10)[0]: raise SystemExit("no reply within 10 seconds")
    return json.loads(p.stdout.readline())

send({"jsonrpc": "2.0", "id": 1, "method": "initialize",
      "params": {"protocolVersion": "2025-03-26", "capabilities": {},
                 "clientInfo": {"name": "example", "version": "0"}}})
print(recv()["result"]["serverInfo"])
send({"jsonrpc": "2.0", "method": "notifications/initialized"})
send({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
tools = recv()["result"]["tools"]
print(len(tools), sorted(t["name"] for t in tools))
for i, (name, args) in enumerate([("orders_list", {"status": "bogus"}),
                                  ("orders_cancel_order", {"id": "ord_2"})], start=3):
    send({"jsonrpc": "2.0", "id": i, "method": "tools/call",
          "params": {"name": name, "arguments": args}})
    print(recv()["result"])
p.terminate()
{'name': 'acme-orders', 'version': '1.0.0', 'title': 'Acme Orders'}
18 ['context', 'customers_create', 'customers_get', 'customers_list', 'export', 'import', 'orders_cancel_order', 'orders_create', 'orders_get', 'orders_list', 'orders_update', 'products_list', 'search', 'send_feedback', 'sql', 'sync', 'workflow_archive', 'workflow_status']
{'content': [{'type': 'text', 'text': 'invalid value "bogus" for --status: must be one of [pending paid shipped cancelled]'}], 'isError': True}
{'content': [{'type': 'text', 'text': 'API error: POST /orders/ord_2/cancel returned HTTP 409: {"error": {"type": "conflict", "message": "shipped orders cannot be cancelled"}}\n{"code":5,"error":"POST /orders/ord_2/cancel returned HTTP 409: ...'}], 'isError': True}

orders_cancel_order on a shipped order returns the API's 409 as an error result, so an agent sees why the call failed. The error text also repeats the failure as a small JSON object with the CLI's exit code ("code":5).

3. Compare the three surfaces

Repeat the initialize and tools/list part of the step 2 script with the server command changed to ["./acme-orders", "mcp", "--tools", "<surface>"], and count the tools:

SurfaceTools listedIncludes orders_cancel_order and orders_create
compact18yes
readonly9no
full18yes

These counts belong to this CLI as it was generated: one tool per API operation plus the built-in tools. A different spec or a regenerated CLI gives different counts and can name tools differently, so list them with tools/list instead of relying on the numbers.

For an API this small, compact already lists every operation, so it matches full.

4. Get the hosted MCP URLs

okibi clis mcp setup acme-orders --json
{
  "published": true,
  "urls": {
    "compact": "https://okibi.ai/mcp/<workspace>/acme-orders",
    "full": "https://okibi.ai/mcp/<workspace>/acme-orders/full",
    "readonly": "https://okibi.ai/mcp/<workspace>/acme-orders/readonly"
  },
  "setups": [{ "label": "Claude Code", "command": "claude mcp add --transport http acme-orders https://okibi.ai/mcp/<workspace>/acme-orders/full" }]
}

The full output lists setups for Claude, Claude Code, ChatGPT, Codex and Cursor / VS Code. The hosted endpoints authorize through an approval page in the client. An unauthenticated call returned 401. After an OAuth sign-in, the hosted / and /full paths listed 13 tools and /readonly listed 7, fewer than the local server, because the local-database tools are not served. A tool call failed because Okibi's servers cannot reach an API on 127.0.0.1.

Verify the result

Take the readonly row of step 3 and list its tool names.

Expected: 9 tools (context, customers_get, customers_list, orders_get, orders_list, products_list, search, sql, workflow_status), and none that write, such as orders_cancel_order, orders_create, orders_update or customers_create.

How it works

The mcp command registers one tool per CLI operation and runs the matching CLI command for each call. Tool annotations mark which tools read and which write, and the readonly surface filters on that.

Common issues

Tool names are not the CLI command names

The CLI command is orders cancel order <id>, and the MCP tool is orders_cancel_order. In an earlier generation of this same API the tool was orders_cancel. Names come from the generator, so list them with tools/list instead of guessing.

Results can report "source": "cache"

Repeating a read can return "source": "cache" from both the CLI and the MCP server. Check meta.source before treating a result as current.

The help text lists a handle transport that the flag rejects

acme-orders mcp --help describes a handle transport, but acme-orders mcp --transport handle exits 1 with Error: unknown --transport "handle" (supported: stdio, http, lambda). Use one of the three supported values.

The MCP server reads the base-URL override too

ACME_ORDERS_BASE_URL_OVERRIDE works for ./acme-orders mcp as well. With it pointed at a closed port (http://127.0.0.1:9/v1), the orders_list tool answered from local data with "source": "local" and "reason": "api_unreachable".

send_feedback is not covered by the local-only switches

The server has a send_feedback tool that posts the agent's message to the CLI's publisher. The local-only controls (--local-only, ACME_ORDERS_FEEDBACK_LOCAL_ONLY=true) apply to the acme-orders feedback command only. The tool posts upstream even when the variable is set. The readonly surface does not include send_feedback.

The server needs the API key in its environment

The server uses the CLI's own settings. Without ACME_ORDERS_API_KEY set in the environment that launches it, tool calls return an error result that starts with authentication failed: GET /orders/ord_1 returned HTTP 401, followed by a hint to run acme-orders doctor. The CLI reports the same condition with exit code 4.

Hosted URLs can already be published

okibi clis mcp setup acme-orders --json returned "published": true with no official release yet and "releaseVersion": null. The endpoints exist at that point.


verification:
  status: verified
  tested_at: "2026-11-02"
  product_version: "okibi 0.2.11; acme-orders 1.0.0"
  command: "python3 mcp_demo.py"
  expected_result: "18 tools listed, then an isError result for the bogus status and the API 409 for cancelling a shipped order. With --tools readonly in the script, 9 tools."

Related Articles