OKO MCP

Create, operate, and analyze OKO Stream webinars from Claude, Codex, or another stdio MCP client. OKO adds an event page, audience blocks, chat, forms, analytics, and integrations around a video player supplied by the organizer.

Before You Connect

Webinar data and actions require an active OKO organizer account. An active organizer account is required before an API key can be created.

• Already invited: sign in or register.
• Already an organizer: create a scoped key in the authenticated MCP install center.
• No key yet: the server still starts in onboarding-only mode. oko_connection_status explains the connection state and next steps, but the package cannot create or activate an organizer account.

Node.js 20.18.1 or newer is required.

Install

The package ships as one self-contained file (about 4 MB, no dependencies to install). Before wiring it into a client, warm it up once in a terminal and wait for the OKO MCP Server banner:

npx -y @okostream/mcp@latest --help

This keeps the first client start under the 30-second MCP startup timeout; an interrupted first download would otherwise leave a broken copy in the npx cache and the client would report Connection closed.

Claude Desktop and JSON-based clients

{
  "mcpServers": {
    "oko": {
      "command": "npx",
      "args": ["-y", "@okostream/mcp@latest"],
      "env": {
        "OKO_API_KEY": "<OKO_API_KEY>"
      }
    }
  }
}

Claude Code

claude mcp add oko --scope user --env OKO_API_KEY=oko_sk_... -- npx -y @okostream/mcp@latest

Codex

[mcp_servers.oko]
command = "npx"
args = ["-y", "@okostream/mcp@latest"]

[mcp_servers.oko.env]
OKO_API_KEY = "oko_sk_..."

To install before receiving a key, omit the env entry. Restart or reconnect the client, then ask:

Use OKO to check the connection status and explain the next step.

After the connection is active:

Use OKO to show who I am and list my latest webinars.

Updating

With npx -y @okostream/mcp@latest, restarting the client installs the newest published version. The server reports the latest version during the key exchange: oko_whoami and oko_connection_status return update, and the first results of a session carry an UPDATE AVAILABLE block while the client is behind, with the exact update step. Global installs update with npm install -g @okostream/mcp@latest. Claude Desktop is not offered for now (the extension bundle is discontinued; the Desktop path returns when the package ships through a directory).

Publishing and lumens

A new page is a draft: viewers of its public URL see "not published". oko_publish_event publishes it and, like a few other operations, spends lumens, the unit of the OKO wallet. Money is handled in one direction:

• Spending is previewed. oko_publish_event, oko_unpublish_event, oko_start_session, oko_extend_session and oko_publish_telegram_post state the charge (or the refund) when called without confirm, name the wallet that pays, and take nothing until the organizer confirms. The amount in the preview of a charge is the amount charged; the preview of a withdrawal (oko_unpublish_event, the trash) says "up to", because part of the refund may be forfeited and only the answer after confirmation gives the exact figures. The public price list is at okostream.app/pricing and is not copied here.
• oko_wallet reads the plan and the wallet. It returns the plan (tier, status, period end, source), the lumen balance, the grants and the ledger of the organizer behind the key, with the link to the cabinet's Billing page (scope wallet:read, included in the operator and full presets, not in readOnly). It cannot buy, change or cancel anything: a plan or lumens are bought only in that cabinet. Keys created before that scope existed get SCOPE_REQUIRED and need a new key. A page in a shared workspace is paid from the workspace owner's wallet: its balance is told, in the previews and refusals, to whoever may spend from it; its grants and ledger are the owner's to read. oko_workspace_wallet reads just that balance for one workspace, as a single number (the payer, or a member who may spend from the payer's wallet; same scope wallet:read); an unreadable balance is an error, never zero.
• Payment and terms are web-only. Plans and lumens are bought, and terms accepted, only in the OKO web cabinet, and no MCP tool collects a password, card or bank details, or agreement to terms on anyone's behalf.

When a tool refuses

Refusals are explicit and never require guessing:

• SCOPE_REQUIRED — the API key lacks a scope; the result names the key presets that include it and a workaround when one exists.
• PLATFORM_REJECTED_WRITE — OKO's security rules refused the write. Retrying or rephrasing does not help; the result carries a ready-made report for the OKO team.
• PLATFORM_REJECTED_READ — no access to that resource, or it does not exist.
• ENTITLEMENT_REQUIRED / INSUFFICIENT_TOKENS — the plan that pays lacks the feature, or the wallet that pays is short of lumens. oko_publish_telegram_post costs 5 lumens per post, charged when Telegram confirms delivery; the plan and the balance are checked before the send, and the refusal names the postId left behind as failed (create a new post after fixing the cause, then delete the failed one with oko_cancel_telegram_post).
• CHAT_PAUSED — the event's chat is paused, which closes it for viewers (the event owner and moderators still write into a paused chat); it is the chat's state, not a missing permission. CHAT_MESSAGE_REFUSED — the chat refused a message and the cause could not be established; the result lists what was ruled out and what remains possible.
• EVENT_DATE_LOCKED — the date of a published page moves only inside the show window it bought (the result carries windowStart, windowEnd and the next steps); a date outside the window, a cleared date, or any date on a page whose show is over is refused. oko_update_event may also return warnings (advice, never a refusal).
• WORKSPACE_LIMIT, SEATS_FULL, ENTITLEMENT_REQUIRED — the plan of the workspace owner does not hold another shared workspace, another member, or the capability at all. A refused invitation stays valid. Plans are bought only in the OKO cabinet, never through MCP.
• CONTROL_ROOM_REQUIRED — oko_control_poll was asked to launch a poll for everyone or to reset its count, which use the live control room of the show (a paid option of a published page, bought in the analytics screen, never through MCP). Showing the results, closing, reopening and hiding need no control room. Nothing is changed by the refusal.
• WALLET_VIEW_FORBIDDEN — oko_workspace_wallet tells the balance only to the payer of the workspace and to members who may spend from it.
• WORKSPACE_INACTIVE — oko_publish_event in a shared workspace the plan does not hold open (only a new publication is closed): Core — shared workspaces are not included (Pro); Pro — one active workspace (the owner's choice, or Max); no live subscription — renew.

One install path. Every supported client — Claude Code, Codex, and any MCP client that takes a command with arguments and env — runs the package through npx -y @okostream/mcp@latest (Node.js required): the latest version is installed on each restart, so the server never falls behind. The .mcpb extension bundle for Claude Desktop is no longer distributed — it never updated itself — and the Claude Desktop path is archived until the package ships through a directory. The key exchange refuses versions behind the latest published one and tells the assistant how to update.

Image URLs are fetched by the OKO server first, so a VPN, proxy or captive portal on the organizer's machine is not in the way. If the server cannot reach the URL (a private host, a login wall, a timeout), the MCP client fetches it from the local machine; on a machine where a VPN or proxy intercepts DNS, public hosts resolve to fake addresses (198.18.x.x), such uploads still work, and the result says so. When both roads fail, the error names both reasons and asks for a file from disk (OKO_IMAGE_ROOTS), which always works. The result's sourceVia says who fetched the image.

Capabilities

• Create, duplicate, move, restore, and delete webinars.
• Configure video, forms, polls, calls to action, cards, banners, and images. On an already published page, turning on a banner, CTA, cards, forms or polls costs 10 lumens each for that show: the tool answers with the quote first and writes only after confirm=true; unpublishing later does not return these top-ups. The live control room is a paid option of a published page (50 lumens, Pro and above) bought in the analytics screen, not through MCP.
• Operate live audience controls, chat, moderation, and analytics sessions.
• Run polls: build them, bind them to buttons, close and reopen voting, show or hide the results to viewers, launch one for everyone or reset its count (the last two with the live control room), and read the live count and the per-session results (oko_control_poll, oko_get_live_state, oko_get_session_report).
• Read analytics, session reports, geography, engagement, form submissions and poll results.
• Manage workspaces, invitations, notifications, and Telegram publishing (5 lumens per post, shown in the confirmation preview).
• Read your own plan, lumen balance and ledger (oko_wallet), and the balance of the wallet that pays for a workspace (oko_workspace_wallet).

OKO MCP acts as the organizer represented by the selected access key. It does not inherit platform-owner privileges. Keys are scoped and revocable, and consequential actions require explicit confirmation.

Local image access is disabled unless you explicitly select an allowed folder. The MCP package does not host video, create accounts, issue invitations, expose arbitrary Firebase administration, or inherit platform-owner privileges.