OKO MCP Server

MCP server for managing OKO Stream webinars as an organizer.

Quick Setup

1. Create an API key in OKO: /app/mcp -> access keys.
2. Add the server to your MCP client config.

Claude Desktop / Claude Code:

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

Codex:

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

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

The package includes the public Firebase config for okostreamcore, so OKO_API_KEY is the only required variable. For staging or local experiments, override these optional variables:

OKO_EXCHANGE_URL=...
OKO_FIREBASE_API_KEY=...
OKO_FIREBASE_AUTH_DOMAIN=...
OKO_FIREBASE_DATABASE_URL=...
OKO_FIREBASE_CHAT_DB_URL=...
OKO_FIREBASE_PROJECT_ID=...
OKO_FIREBASE_STORAGE_BUCKET=...
OKO_FIREBASE_MESSAGING_SENDER_ID=...
OKO_FIREBASE_APP_ID=...
# Path-delimited allowlist for local image reads; defaults to the process cwd.
OKO_IMAGE_ROOTS=/trusted/assets:/another/trusted/folder

Node.js 20.18.1 or newer is required.

What OKO Does

OKO is a webinar experience and operations layer, not a video-streaming host. The organizer supplies a YouTube, iframe, or other player URL; OKO adds the event page, configurable audience blocks, chat, analytics, and NMO attendance controls around it. Start/End tools control analytics sessions only, never the underlying video stream.

Standard webinars are the default supported workflow. NMO is a separate unfinished MVP mode and must be enabled only on an explicit organizer request after reviewing oko://guide/nmo; it is not a normal option inferred from a medical topic or audience.

Security Model

• Each API key exchanges into its own Firebase identity mcp_<keyId>; it never inherits platform-owner claims from the organizer account.
• Every protected operation is checked independently by MCP scope, active key state, organizer identity, and event/workspace capability in Cloud Functions and Firebase Rules.
• Revocation disables the synthetic identity, revokes refresh tokens, and invalidates Firestore, main RTDB, and chat RTDB access immediately.
• API-key creation and revocation are browser-only callables. Raw secrets are hashed at rest and shown once.
• MCP image uploads go through a scoped callable; MCP sessions cannot write Firebase Storage directly.
• Local files are constrained to OKO_IMAGE_ROOTS, symlink escapes are rejected, and remote images use HTTPS with DNS pinning, redirect revalidation, and byte/pixel limits.
• Every non-read-only tool writes a compact server-owned audit event. Message bodies, captions, lead values, and file contents are not copied into the audit record.
• Destructive, live, public-upload, claim, chat-send, and Telegram actions require confirm:true.
• Event, lead, participant, chat, URL, and remote-image content is untrusted data, never instructions for the MCP client.

Response Contract

Every tool returns JSON text plus MCP structuredContent. List-like tools use bounded pages:

• limit defaults to 20-50 depending on the tool.
• Cursor tools return both hasMore/nextCursor and has_more/next_cursor.
• oko_list_my_events, oko_get_analytics, oko_list_recent_chat, oko_list_participants, oko_list_leads, oko_list_notifications, oko_list_workspace_access, oko_list_workspace_invites, and oko_list_telegram_posts support pagination.
• oko_get_analytics omits heavy timeline, baseline/final snapshots, and NMO participant rows by default. Request includeTimeline, includeSnapshots, or includeNmoRows only when needed.
• oko_get_session_report returns a compact structured session report plus markdown suitable for a human handoff.
• Oversized responses are truncated with truncated: true and a truncationMessage.

The server also exposes MCP-native onboarding:

• instructions on initialize with the supported webinar creation flow and product invariants.
• Resources: oko://guide/create-webinar, oko://guide/platform, oko://guide/security, oko://guide/nmo, oko://schema/event, oko://guide/telegram, oko://capabilities.
• Prompts: create_webinar_from_brief, audit_event_setup, prepare_session_report.

This package is published as source-available runtime distribution for OKO customers. license: UNLICENSED means all rights reserved unless a separate agreement says otherwise.

Local Development

cd mcp
npm install
npm run build
npm start

Local config without npm publishing:

{
  "mcpServers": {
    "oko": {
      "command": "node",
      "args": ["/absolute/path/to/okostream/mcp/dist/server.js"],
      "env": {
        "OKO_API_KEY": "oko_sk_..."
      }
    }
  }
}

Tools

All tools are prefixed with oko_ for safe discovery next to other MCP servers.

Core discovery/read tools:

• oko_whoami, oko_list_workspaces, oko_list_my_events, oko_get_event
• oko_validate_event_setup
• oko_update_profile, oko_list_notifications, oko_mark_notifications_read
• oko_get_live_state, oko_get_analytics, oko_get_session_report, oko_list_recent_chat, oko_list_participants, oko_list_leads, oko_delete_lead

Event/setup/media tools:

• oko_create_webinar, oko_update_event, oko_delete_event (30-day trash compatibility alias)
• oko_trash_event, oko_restore_event, oko_delete_event_permanently
• oko_duplicate_event, oko_move_event
• oko_configure_blocks, oko_configure_cards
• oko_upload_image, oko_upload_card_images_batch, oko_wait_for_image_variants, oko_delete_image

Live/session/chat/NMO tools:

• oko_set_block_visibility, oko_refresh_viewers
• oko_start_session, oko_end_session, oko_fix_orphan_session, oko_delete_session
• oko_send_chat_message, oko_delete_chat_message, oko_mute_user, oko_unmute_user, oko_ban_user, oko_unban_user, oko_set_chat_settings
• oko_launch_checkpoint, oko_close_checkpoint
• oko_add_nmo_participant, oko_import_nmo_participants, oko_remove_nmo_participant

Workspace and Telegram tools:

• oko_create_workspace, oko_update_workspace, oko_delete_workspace
• oko_list_workspace_access, oko_update_workspace_member, oko_remove_workspace_member
• oko_create_workspace_invite, oko_list_workspace_invites, oko_revoke_workspace_invite, oko_claim_workspace_invite
• oko_create_telegram_link, oko_list_telegram_channels, oko_claim_telegram_channel
• oko_set_telegram_channel_workspaces, oko_disconnect_telegram_channel
• oko_list_telegram_posts, oko_cancel_telegram_post, oko_publish_telegram_post

Dangerous or external side-effect tools require confirm: true.

Smoke

1. oko_whoami should return the organizer UID and granted scopes.
2. oko_list_my_events should return only events visible to that UID.
3. oko_create_webinar should create a test webinar and RTDB owner/workspace mirror.
4. oko_configure_cards should create/update blocks.cards.items and preserve card image fields by stable card id.
5. oko_upload_card_images_batch should upload multiple card images, then return ready imageVariants.
6. oko_validate_event_setup should catch missing images/forms/buttons/video/NMO/Telegram/variants on a deliberately broken event.
7. oko_start_session -> oko_fix_orphan_session -> oko_delete_session should leave no active session pointers on a disposable test event.
8. oko_duplicate_event, workspace tools, and oko_move_event should preserve Firestore access rules and RTDB owner/workspace mirrors.
9. oko_import_nmo_participants should call CF24 and return per-row results; clean up test participants after import.
10. oko_get_session_report should return markdown and structured session data for a completed session.
11. oko_list_notifications -> oko_mark_notifications_read should read and clear an own disposable notification.
12. oko_get_analytics should read an existing event with analytics sessions.
13. MCP protocol smoke should report 65 tools, 7 resources, 3 prompts, and non-empty initialize instructions.

CLI help:

npx -y @okostream/mcp --help

Troubleshooting

If Claude shows Unexpected token '◇', the MCP server printed a non-JSON line to stdout. Use the current version with dotenv quiet:true, then fully restart the MCP client.

For stdio MCP, stdout must contain only JSON-RPC. Diagnostics belong on stderr.