Hosted MCP URLs for Every Client 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.
Hosted MCP URLs for Every Client with Okibi
A local MCP server needs each customer to install it. Okibi also hosts an endpoint for every CLI and prints the setup step for each client. This guide lists those URLs and what each client does with them. It checks that each hosted endpoint is protected, then signs in with a short script and calls the endpoint to see what a connected client gets.
What you will build
A list of the hosted URL for each surface and the exact setup instruction for five clients.
okibi clis mcp setup -> /mcp /mcp/full /mcp/readonly -> Claude, Claude Code, ChatGPT, Codex, Cursor / VS Code
AI Prompt
Using the Okibi CLI, list the hosted MCP endpoints for acme-orders and the setup for each client. Requirements: - Run `okibi clis mcp setup acme-orders --json`. - Report `published` and the three URLs. - Report, for each setup, the label, the command or snippet, and the help text. - Send an unauthenticated POST to each path and report the status. Then sign in through OAuth, call `initialize` and `tools/list` on each path, and call one tool. - Use the example API key `demo-key` when the approval page asks for credentials. - Run the verification step below before finishing.
Prerequisites
-
The Acme Orders example spec,
openapi.json(a fictional orders API). Download it into your working directory:curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json
-
A generated CLI named
acme-orders(okibi generate --spec ./openapi.json --name acme-orders --agent). -
Okibi CLI
0.2.11, logged in. -
Use a disposable project: this guide signs in to the hosted endpoint and revokes the token when it finishes. Nothing is written to disk.
1. Read the hosted setup
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"
},
"brandedUrl": null,
"setups": [ ... ]
}
The CLI had "published": true and a null releaseVersion before any release was official.
2. What each client is told to do
| Client | URL used | Setup |
|---|---|---|
| Claude | compact | Settings → Connectors → Add custom connector, paste the URL, approve in the page that opens |
| Claude Code | full | claude mcp add --transport http acme-orders <full URL>, then run /mcp to connect. Okibi's note: Claude Code searches tools, so it gets every operation. |
| ChatGPT | compact | Okibi prints: Settings → Apps & Connectors → Create (developer mode), paste the URL, choose OAuth. OpenAI's current steps for ChatGPT web: open ChatGPT Plugins, select the plus button, then Add custom MCP server, enter a name and description, enter the URL including its /mcp path, set authentication, and select Create as a plugin. |
| Codex | full | Add [mcp_servers.acme-orders] with url = "<full URL>" to ~/.codex/config.toml, then run codex mcp login acme-orders |
| Cursor / VS Code | compact | Add the URL under mcpServers in .cursor/mcp.json. For VS Code use .vscode/mcp.json under servers with a type of http. |
The Okibi rows are what okibi clis mcp setup prints for Okibi 0.2.11. The ChatGPT steps are from OpenAI's "Connect and test your plugin" page (developers.openai.com/plugins/deploy/connect-chatgpt), and the menus match them on 2026-11-02: ChatGPT Plugins, then Add, then Add custom MCP server, with a name, a description, a Server URL or Tunnel, OAuth and a risk acknowledgement, then Create as a plugin. In the ChatGPT desktop app, MCP servers are added under Settings → MCP servers → Add server → Streamable HTTP. That app, the Codex CLI and the IDE extension share ~/.codex/config.toml, where codex mcp login acme-orders starts the OAuth sign-in.
ChatGPT's sign-in request is accepted. ChatGPT identifies itself with a client-ID metadata document (client_id=https://chatgpt.com/oauth/client.json). On 2026-11-02 Okibi's authorize page rejected it with "Unknown MCP client". On 2026-11-17 the same request returns a 302 to https://okibi.ai/mcp-auth/connect?request=..., the page where you enter the credential. The hosted service changed; the Okibi CLI version does not affect it. On 2026-11-17 the full ChatGPT flow completed: Connect, the Okibi page with demo-key, and ChatGPT showed the plugin as connected. okibi clis mcp connections acme-orders --json then listed one connection with clientName ChatGPT and credentialNames ["ACME_ORDERS_API_KEY"]. The script in step 4 uses dynamic registration instead, and that sign-in works too.
3. See what an unauthenticated call returns
You can check that a hosted endpoint is up and protected without signing in:
curl -s -i -X POST https://okibi.ai/mcp/<workspace>/acme-orders \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}'
HTTP/2 401
www-authenticate: Bearer error="invalid_token", resource_metadata="https://okibi.ai/.well-known/oauth-protected-resource/mcp/<workspace>/acme-orders", scope="mcp"
{"error":"invalid_token"}
All three paths (/, /full, /readonly) returned 401. The resource_metadata address is a public document:
{
"resource": "https://okibi.ai/mcp/<workspace>/acme-orders",
"authorization_servers": ["https://okibi.ai/mcp-auth"],
"scopes_supported": ["mcp"],
"bearer_methods_supported": ["header"],
"resource_name": "acme-orders (compact)"
}
A client reads this to find the authorization server and the mcp scope, then asks you to approve.
4. Sign in and call the hosted endpoint
Clients such as Claude Code do this for you (claude mcp add ..., then /mcp). To see it step by step, this script does what a client does:
Save the script below as hosted_mcp.py and run it with python3 hosted_mcp.py. Before you run it, replace <workspace> in the script with the slug in your hosted URLs: it is the part after /mcp/ in the output of okibi clis mcp setup acme-orders --json (for https://okibi.ai/mcp/acme-co/acme-orders it is acme-co). The script opens a browser tab and waits 5 minutes for you to approve, so run it when you are at the screen. It uses the macOS open command. On Linux, change that line to xdg-open.
What it does:
- Read the authorization server's metadata from
https://okibi.ai/.well-known/oauth-authorization-server/mcp-auth. - Register a client (dynamic registration, no client secret).
- Open the authorization URL in your browser with a PKCE challenge, the
mcpscope and the hosted URL asresource. - Catch the redirect on
127.0.0.1. It accepts only/callbackwith thestateit issued, and the listener closes when the wait ends. - Exchange the code for a token. The token stays in memory and is never written to disk.
- On each path, send
initialize, thennotifications/initialized, thentools/list, carrying the session id and protocol version the server returned. - Call the
contexttool andorders_get, then revoke the token.
import base64, hashlib, http.server, json, secrets, subprocess, sys, time
import urllib.error, urllib.parse, urllib.request
BASE = "https://okibi.ai"
WORKSPACE = "<workspace>" # the part after /mcp/ in the output of `okibi clis mcp setup acme-orders --json`
CLI = "acme-orders"
RESOURCE = f"{BASE}/mcp/{WORKSPACE}/{CLI}"
PROTOCOL = "2025-03-26"
WAIT_SECONDS = 300 # how long to wait for you to approve in the browser
def post(url, body, headers=None, form=False):
data = urllib.parse.urlencode(body).encode() if form else json.dumps(body).encode()
ctype = "application/x-www-form-urlencoded" if form else "application/json"
req = urllib.request.Request(url, data=data, headers={"content-type": ctype, **(headers or {})})
try:
with urllib.request.urlopen(req, timeout=30) as r:
raw = r.read()
return r.status, (json.loads(raw) if raw else {}), dict(r.headers)
except urllib.error.HTTPError as e:
raw = e.read().decode()
try:
return e.code, json.loads(raw), dict(e.headers)
except ValueError:
return e.code, {"raw": raw[:200]}, dict(e.headers)
class Callback(http.server.BaseHTTPRequestHandler):
"""Accepts only GET /callback with the state we issued. Anything else gets an error and is ignored."""
expected_state = None
result = None
def do_GET(self):
url = urllib.parse.urlparse(self.path)
if url.path != "/callback":
return self._reply(404, "not found")
q = {k: v[0] for k, v in urllib.parse.parse_qs(url.query).items()}
if q.get("state") != Callback.expected_state:
return self._reply(400, "state mismatch")
Callback.result = q
self._reply(200, "You can close this tab and return to the terminal.")
def _reply(self, code, text):
self.send_response(code)
self.send_header("content-type", "text/plain")
self.end_headers()
self.wfile.write(text.encode())
def log_message(self, *args):
pass
def wait_for_callback(server, state, seconds):
"""Serve requests until the right callback arrives or the time is up. Always closes the server."""
Callback.expected_state, Callback.result = state, None
server.timeout = 1
deadline = time.time() + seconds
try:
while Callback.result is None and time.time() < deadline:
server.handle_request()
finally:
server.server_close()
return Callback.result
def sign_in():
meta = json.load(urllib.request.urlopen(f"{BASE}/.well-known/oauth-authorization-server/mcp-auth", timeout=30))
server = http.server.HTTPServer(("127.0.0.1", 0), Callback)
redirect = f"http://127.0.0.1:{server.server_address[1]}/callback"
status, reg, _ = post(meta["registration_endpoint"], {
"client_name": "my-hosted-mcp-check", "redirect_uris": [redirect],
"grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"],
"token_endpoint_auth_method": "none"})
client_id = reg["client_id"]
verifier = secrets.token_urlsafe(48)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
state = secrets.token_urlsafe(16)
url = meta["authorization_endpoint"] + "?" + urllib.parse.urlencode({
"response_type": "code", "client_id": client_id, "redirect_uri": redirect, "scope": "mcp",
"state": state, "code_challenge": challenge, "code_challenge_method": "S256", "resource": RESOURCE})
print("opening the approval page in your browser...", flush=True)
subprocess.run(["open", url]) # on Linux use "xdg-open"
got = wait_for_callback(server, state, WAIT_SECONDS)
if got is None:
sys.exit(f"no approval within {WAIT_SECONDS} seconds")
if "error" in got:
sys.exit("approval refused: " + got["error"])
status, tok, _ = post(meta["token_endpoint"], {
"grant_type": "authorization_code", "code": got["code"], "redirect_uri": redirect,
"client_id": client_id, "code_verifier": verifier, "resource": RESOURCE}, form=True)
if status != 200:
sys.exit(f"token exchange failed: {status} {tok}")
print("token received. scope:", tok.get("scope"), "| expires_in:", tok.get("expires_in"))
return meta, client_id, tok
def mcp(path, token, method, params=None, rid=None, session=None):
body = {"jsonrpc": "2.0", "method": method}
if rid is not None:
body["id"] = rid
if params:
body["params"] = params
headers = {"accept": "application/json, text/event-stream", "authorization": f"Bearer {token}"}
if session:
headers["mcp-session-id"] = session
headers["mcp-protocol-version"] = PROTOCOL
return post(RESOURCE + path, body, headers)
if __name__ == "__main__":
meta, client_id, tok = sign_in() # the token stays in memory. Nothing is written to disk.
access = tok["access_token"]
try:
for path in ("", "/full", "/readonly"):
status, init, hdrs = mcp(path, access, "initialize", {
"protocolVersion": PROTOCOL, "capabilities": {},
"clientInfo": {"name": "check", "version": "0"}}, rid=1)
session = hdrs.get("mcp-session-id") or hdrs.get("Mcp-Session-Id")
print(f"[{path or '/'}] initialize -> {status}", init["result"]["serverInfo"])
status, _, _ = mcp(path, access, "notifications/initialized", session=session)
status, listing, _ = mcp(path, access, "tools/list", rid=2, session=session)
names = sorted(t["name"] for t in listing["result"]["tools"])
print(f"[{path or '/'}] tools/list -> {status}", len(names), "tools")
status, ctx, _ = mcp("", access, "tools/call", {"name": "context", "arguments": {}}, rid=3, session=session)
res = ctx.get("result", {})
print("[/] tools/call context ->", status, "isError:", res.get("isError"), "|", (res.get("content") or [{}])[0].get("text", "")[:80].replace("\n", " "))
status, got, _ = mcp("", access, "tools/call", {"name": "orders_get", "arguments": {"id": "ord_1"}}, rid=4, session=session)
res = got.get("result", {})
print("[/] tools/call orders_get ->", status, "isError:", res.get("isError"), "|", (res.get("content") or [{}])[0].get("text", "")[:120].replace("\n", " "))
finally:
status, _, _ = post(meta["revocation_endpoint"], {"token": access, "client_id": client_id}, form=True)
print("token revoked ->", status)
Run it, then approve in the browser. The approval page asks for the credential ACME_ORDERS_API_KEY. For the example API it is the fake key demo-key.
opening the approval page in your browser...
token received. scope: mcp | expires_in: 3600
[/] initialize -> 200 {'name': 'acme-orders', 'version': '1.0.4', 'title': 'Acme Orders'}
[/] tools/list -> 200 13 tools
[/full] tools/list -> 200 13 tools
[/readonly] tools/list -> 200 7 tools
[/] tools/call context -> 200 isError: None | { "api": "acme-orders", "archetype": "generic", ...
[/] tools/call orders_get -> 200 isError: True | API error: API unreachable and nothing synced for "orders" ...
token revoked -> 200
The version is your official release. The access token lasts an hour (expires_in 3600) and the script revokes it when it finishes, so nothing is left connected.
What the hosted server lists
| Path | Tools | Compared with the local acme-orders mcp |
|---|---|---|
/ (compact) | 13 | local has 18. Missing: export, import, search, sql, sync |
/full | 13 | the same 13 as / |
/readonly | 7 | local has 9. Missing: search, sql |
The five missing tools all use the local database. The local server's help describes a --hosted mode that isolates each call from the machine's config and cache and drops local-store tools, which matches.
Call a tool
The context tool needs no API and answers from the hosted server, so it succeeds (isError is not set): it returns the CLI's description, including "api": "acme-orders" and the credential names it expects. orders_get calls the API, which is http://127.0.0.1:8099/v1, and Okibi's servers cannot reach your machine, so it returns isError: true with connection refused. A hosted tool that calls an API needs a public API address, and the error text shows the address compiled into the CLI, so do not compile an internal address you want to keep private.
See the connection and the call in Okibi
okibi clis mcp summary acme-orders --json
{ "connections": 1, "readOnlyConnections": 0, "apps": [ { "app": "my-hosted-mcp-check", "connections": 1 } ], ... }
okibi clis mcp connections acme-orders --json lists connections under connections, each with an id, the clientName, credentialNames (here ["ACME_ORDERS_API_KEY"], the credential the approval page collected), lastUsedAt and readOnly. It also repeats the URLs and setups from mcp setup.
<connection-id> is the id of the entry you want to remove from that connections list. okibi clis mcp disconnect <cli> <connection-id> --yes revokes a connection and deletes its saved credentials:
okibi clis mcp disconnect acme-orders <connection-id> --yes --json
{ "ok": true }
After that, mcp summary shows "connections": 0, and the same access token gets 401 invalid_token, so revoking takes effect at once. Revoking the token, as the script does, also leaves 0 connections.
Verify the result
okibi clis mcp setup acme-orders --json | python3 -c " import json,sys d=json.load(sys.stdin) print(d['published'], sorted(d['urls']), [s['label'] for s in d['setups']])"
Expected: True ['compact', 'full', 'readonly'] ['Claude', 'Claude Code', 'ChatGPT', 'Codex', 'Cursor / VS Code']. After signing in, tools/list returns 13, 13 and 7 tools for the three paths.
How it works
Okibi serves the same three surfaces as the local acme-orders mcp --tools ... command, at three paths on okibi.ai. Okibi's setup help says each client is approved through a page that opens in the client (OAuth for ChatGPT, codex mcp login for Codex), and none of the setup instructions put an API key in the client config. Step 4 goes through the approval flow with a script.
Common issues
A 401 does not prove the CLI exists
A made-up name (.../does-not-exist) also returned 401, and its oauth-protected-resource document returned 200. Use okibi clis mcp setup to see whether your CLI has hosted URLs.
The hosted endpoint cannot reach a local API
acme-orders points at http://127.0.0.1:8099/v1, which Okibi's servers cannot reach. A hosted call to an API tool fails until the CLI targets a public API.
Per-client choices differ
Okibi gives Claude Code and Codex the full URL and the others the compact URL. Use readonly for a client that must not write.
Connections show up in mcp summary
Before any client connects, okibi clis mcp summary acme-orders --json returns "connections": 0, "lastUsedAt": null and no apps. While a client is connected it shows "connections": 1 and the app name. After the token is revoked or the connection is disconnected it goes back to 0.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.4" command: "okibi clis mcp setup acme-orders --json" expected_result: "published true, three URLs, five client setups. An unauthenticated POST returns 401 with a Bearer challenge; after OAuth sign-in tools/list returns 13, 13 and 7 tools, and a tool call fails because the hosted server cannot reach 127.0.0.1."
