okibi.ai

Command Palette

Search for a command to run...

Serve an Okibi MCP Server over HTTP with a Bearer Token

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

  • curl and Okibi CLI 0.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"

Related Articles