Serve an Okibi MCP Server over HTTP with a Bearer Token
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 an Okibi MCP Server over HTTP with a Bearer Token
Stdio works for one local client. To let other machines connect, a generated Okibi CLI can serve MCP over HTTP, and it refuses to listen on a network address without a bearer token. This guide runs the server on loopback with a token and walks through the whole MCP session: a rejected call, the initialize handshake, the initialized notification, a tool list, a read that succeeds and a write that is refused.
What you will build
A local HTTP MCP server with a token, called with no token, a wrong token and the right token through a full session on the read-only path, and a check that a network bind needs the token.
ACME_ORDERS_MCP_AUTH_TOKEN=... acme-orders mcp --transport http -> /mcp /mcp/full /mcp/readonly
AI Prompt
Using the generated acme-orders CLI, serve MCP over HTTP and prove the token is enforced. Requirements: - Start `acme-orders mcp --transport http --addr 127.0.0.1:7777` with `ACME_ORDERS_MCP_AUTH_TOKEN` set to a test value and `ACME_ORDERS_API_KEY=demo-key`. - POST an `initialize` request to `/mcp` without a token and report the HTTP status. - Repeat with `Authorization: Bearer <token>` and report the server name. - Wait until the server answers before calling it, rather than guessing a delay. - Send a wrong token and report the status. - On `/mcp/readonly` with the token, send `initialize`, the `notifications/initialized` notification, `tools/list`, one successful read (`orders_get`) and one write (`orders_create`) and report each result. - Try to bind `0.0.0.0:7788` without the token and report the error. - Stop the server 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), with the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099). -
curland Okibi CLI0.2.11. The token below is a placeholder test value. Use a real secret in production.
1. Start the server with a token and wait for it
export ACME_ORDERS_API_KEY=demo-key ACME_ORDERS_MCP_AUTH_TOKEN=s3cret-token ./acme-orders mcp --transport http --addr 127.0.0.1:7777 & SERVER_PID=$! for i in $(seq 1 20); do curl -s -o /dev/null http://127.0.0.1:7777/mcp && break; sleep 0.5; done echo "answering after $i check(s)"
The & runs the server in the background so you can use the same terminal for the next steps. (Or run it without & in its own terminal and use another terminal for the curl commands.) The loop waits until the port answers, up to ten seconds. The server's own line is acme-orders serving MCP at http://127.0.0.1:7777/mcp (also /mcp/full and /mcp/readonly).
2. Call it without a token and with a wrong one
INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}'
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:7777/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$INIT"
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:7777/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-H 'authorization: Bearer wrong' -d "$INIT"
401 401
3. Run a full session on the read-only path
An MCP session starts with initialize, then a notifications/initialized notification, and only then the requests. This one uses /mcp/readonly and the right token.
URL=http://127.0.0.1:7777/mcp/readonly
CT='content-type: application/json'; AC='accept: application/json, text/event-stream'; AU='authorization: Bearer s3cret-token'
curl -s -X POST $URL -H "$CT" -H "$AC" -H "$AU" -d "$INIT"
curl -s -o /dev/null -w "%{http_code}\n" -X POST $URL -H "$CT" -H "$AC" -H "$AU" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -s -X POST $URL -H "$CT" -H "$AC" -H "$AU" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| python3 -c "import json,sys;print(len(json.load(sys.stdin)['result']['tools']),'tools')"
curl -s -X POST $URL -H "$CT" -H "$AC" -H "$AU" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"orders_get","arguments":{"id":"ord_1"}}}' \
| python3 -c "import json,sys;r=json.load(sys.stdin)['result'];print('isError',r.get('isError'),'|',json.loads(r['content'][0]['text'])['results']['id'])"
curl -s -X POST $URL -H "$CT" -H "$AC" -H "$AU" \
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"orders_create","arguments":{"customer_id":"cus_1","items":[]}}}'
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{}},"serverInfo":{"name":"acme-orders","version":"1.0.0","title":"Acme Orders"},"instructions":"Tools for the Acme Orders API, backed by the acme-orders CLI. ...
202
9 tools
isError None | ord_1
{"jsonrpc":"2.0","id":4,"error":{"code":-32602,"message":"tool 'orders_create' not found: tool not found"}}
The handshake returns the server name, the notification gets 202, and the read-only path lists 9 tools. The orders_get call succeeds and returns the order. The orders_create call is refused with tool 'orders_create' not found, because the read-only path does not serve write tools. This local server issued no session id. Other MCP servers may, and a client then sends it back in a header.
4. Try a network bind without a token
env -u ACME_ORDERS_MCP_AUTH_TOKEN ./acme-orders mcp --transport http --addr 0.0.0.0:7788
Error: refusing to serve MCP on a non-loopback address without ACME_ORDERS_MCP_AUTH_TOKEN; bind to 127.0.0.1 or set a bearer token
Verify the result
Expected from the commands above: 401 and 401 in step 2, then in step 3 the server name acme-orders, 202, 9 tools, isError None | ord_1, and the tool not found error for orders_create. Then stop the server with kill $SERVER_PID. Avoid pkill -f "mcp --transport http", which would also stop any other MCP HTTP server on the machine.
How it works
The HTTP transport serves three paths (/mcp, /mcp/full, /mcp/readonly) from one process. When the token variable is set, every request needs the matching bearer token. A non-loopback --addr is refused unless the variable is set. --transport accepts stdio, http and lambda. The help text also lists handle, but the flag rejects it.
Common issues
Loopback without a token is open
With ACME_ORDERS_MCP_AUTH_TOKEN unset and --addr 127.0.0.1:7778, an initialize request returned 200 with no credentials. Any process on the machine can call it.
The token travels in clear text over plain HTTP
The server speaks plain HTTP. On loopback that is fine. Before you let other machines connect, put it behind HTTPS (for example a reverse proxy that terminates TLS), or the bearer token crosses the network unencrypted.
One token serves every user
A shared token is a single secret for every client. For per-user access, use Okibi's hosted endpoints, which answer an unauthenticated call with an OAuth challenge. After the OAuth sign-in, the hosted endpoint returned 13 tools on / and /full and 7 on /readonly, fewer than the local server.
The server needs the API key too
The bearer token protects the MCP endpoint. The API key is still read from ACME_ORDERS_API_KEY, and all callers share it.
verification:
status: verified
tested_at: "2026-11-02"
product_version: "okibi 0.2.11; acme-orders 1.0.0"
command: "curl -s -o /dev/null -w \"%{http_code}\n\" -X POST http://127.0.0.1:7777/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d \"$INIT\""
expected_result: "401 without a token; the session in step 3 then succeeds with the token"
