A deliberate snapshot, not a finished spec. Everything below is live in production; where something is missing or moving, we say so.
Step zero
The self-serve wizard creates your workspace, and team members are added as staff users by email. Nothing below works without a workspace — every token is a signed-in staff token scoped to exactly one workspace.
Questions mid-integration? Use our custom OK Capsule AI assistant — available anytime.
Endpoints
MCP endpoint
https://storefront.okcapsule.app/mcpOAuth discovery
https://storefront.okcapsule.app/.well-known/oauth-authorization-serverUsing an MCP-capable editor? These add the OK Capsule server in one click — your editor handles the OAuth sign-in in the browser.
Cursor
Opens Cursor and pre-fills the OK Capsule server.
no Cursor protocol handler? Use the web variant.
VS Code
Opens VS Code with the server pre-filled.
Requires VS Code 1.101 or newer with MCP enabled.
Claude Code
claude mcp add --transport http okcapsule https://storefront.okcapsule.app/mcpthen /mcp inside Claude Code to sign in.
Deep-link formats are controlled by each editor and can change — if a button doesn't respond, the endpoint above plus your editor's "add MCP server" flow always works.
OK Capsule is being submitted to the Claude connectors directory and the ChatGPT apps directory — once listed, connecting becomes a single click there too. This page will update.
Auth
Any conformant MCP host completes this on its own. You only implement it yourself if you're writing the client.
| Stage | Call | Notes |
|---|---|---|
| Discovery | GET /.well-known/oauth-authorization-server | Endpoints, supported grants, PKCE methods |
| Dynamic registration | POST /oauth/register | Public client, no pre-shared secret |
| Authorize | GET /oauth/authorize | code_challenge (S256) required |
| Login | Email one-time code | Staff email on the workspace |
| Verify | OTP submitted | Persona and workspace resolved |
| Consent | Scope approval screen | User approves exactly what the client asked for |
| Token | POST /oauth/token | 1-hour RS256 access JWT + 30-day refresh token |
| Refresh | grant_type=refresh_token | Single-use, rotating — always persist the newest |
| Revoke | POST /oauth/revoke | Immediate; revoke anytime |
Access-token claims: sub, role, email, tenant_id, tenant_slug, scope, plus standard iss / aud / jti / iat / exp. One token is bound to exactly one workspace.
| Environment | Status | Notes |
|---|---|---|
| Production | Live | storefront.okcapsule.app — the only self-serve environment |
| Staging | By arrangement only | Periodically reset; no self-serve sandbox today |
Roles & scopes
Nothing crosses workspaces. Read access is the default grant; anything destructive is opt-in at consent.
| Scope | Covers | Default grant? |
|---|---|---|
| catalog:read | brands, products, catalog, product intelligence, pack builder | Default |
| recommendations:read | recommendation validation | Default |
| orders:read | list/get orders, transaction logs, order status | Default |
| orders:write | create/update orders | Opt-in |
| orders:cancel | cancel orders | Opt-in |
| consumers:read | get/list consumers | Default |
| consumers:write | create/update consumers | Default |
| consumers:delete | delete consumers | Opt-in |
| fulfillments:read | fulfillments, shipping labels | Default |
| meta:read | status lists | Default |
| documents:write | supplement-facts PDF generation | Default |
The authoritative list is scopes_supported in the discovery document — read it at runtime; scopes may be added or split.
Read-only by design (no write scope exists)
Catalog, recommendations, fulfillments, and status metadata.
Read-only by default
Orders — orders:read is in the default grant; write and cancel are opt-in.
Writable in the default grant
Consumer profiles (consumers:write) and document generation (documents:write). Deleting consumers is opt-in.
The tool surface
Discover them at runtime with tools/list — don't hardcode schemas. Destructive tools require a second confirmation via okc_confirm_pending_action, and some clients render our embedded UI cards while others fall back to text.
| Tool | Scope | Purpose |
|---|---|---|
okc_authenticate | — | Establish/refresh the session |
okc_debug_ping | — | Connectivity and latency check |
okc_confirm_pending_action | — | Explicit confirmation step for destructive actions |
| Tool | Scope | Purpose |
|---|---|---|
okc_list_brands | catalog:read | List brands (product lines) |
okc_list_products | catalog:read | List products |
okc_get_catalog | catalog:read | Full catalog view |
okc_get_product_intelligence | catalog:read | Ingredient/product intelligence for a product |
okc_render_pack_builder | catalog:read | Interactive pack-builder UI card |
okc_pack_builder_url | catalog:read | Create a shareable pack-builder link |
| Tool | Scope | Purpose |
|---|---|---|
okc_validate_recommendation | recommendations:read | Validate a supplement recommendation |
okc_generate_supplement_facts_pdf | documents:write | Generate a supplement-facts PDF |
okc_list_statuses | meta:read | List order/fulfillment status values |
| Tool | Scope | Purpose |
|---|---|---|
okc_get_consumer | consumers:read | Fetch one consumer |
okc_list_consumers | consumers:read | List/search consumers |
okc_upsert_consumer | consumers:write | Create or update a consumer |
okc_delete_consumer | consumers:delete | Delete a consumer (opt-in scope) |
| Tool | Scope | Purpose |
|---|---|---|
okc_list_orders | orders:read | List orders |
okc_get_order | orders:read | Fetch one order |
okc_get_order_by_client_id | orders:read | Fetch an order by your own order id |
okc_list_order_transaction_logs | orders:read | Order event/transaction history |
okc_render_order_status | orders:read | Order-status UI card |
okc_create_order | orders:write | Create an order (opt-in scope) |
okc_update_order | orders:write | Update an order (opt-in scope) |
okc_cancel_order | orders:cancel | Cancel an order (opt-in scope) |
| Tool | Scope | Purpose |
|---|---|---|
okc_list_fulfillments | fulfillments:read | List fulfillments/shipments |
okc_get_fulfillment | fulfillments:read | Fetch one fulfillment |
okc_get_shipping_label | fulfillments:read | Retrieve a shipping label |
Orders can carry your own order id and be retrieved later via okc_get_order_by_client_id.
okc_render_pack_builder and okc_render_order_status return embedded UI cards. Some MCP clients render them; others fall back to text — both paths carry the same data.
Canceling an order (okc_cancel_order) and deleting a consumer (okc_delete_consumer) require an explicit confirmation via okc_confirm_pending_action.
Call tools/list rather than hardcoding schemas — the surface grows and argument shapes can be extended.
Commerce paths
Live and fastest. Build the pack with the catalog and pack tools, then send the customer to the Shopify checkout URL. No order-write scopes needed.
Six steps to go liveokc_create_order and friends, behind the opt-in orders:write and orders:cancel scopes. Switching paths later is low-lift.
Integration model
Join the open beta — the wizard creates your workspace and staff users.
Connect: point your MCP host at the endpoint. The first request returns a 401 whose challenge links the discovery documents — conformant MCP clients take it from there automatically: dynamic registration, then browser sign-in.
Sign in: email one-time code, then consent to scopes.
Use the tools: discover with tools/list, then call them.
Stay signed in: refresh rotates automatically for 30 days.
Yes — Streamable HTTP JSON-RPC with an Authorization: Bearer header. Any conformant MCP host speaks it, including the OAuth handshake, so most teams don't write transport code at all.
| Requirement | What we expect |
|---|---|
| MCP client | Any conformant host that speaks Streamable HTTP and the OAuth handshake |
| Staff emails | On the workspace, added via the wizard or an admin |
| Redirect URI | https, or localhost loopback for local development |
| Scope choice | Decided up front — read-only, or opt into order writes |
| Token storage | Server-side, secure, newest refresh token persisted |
| Re-auth handling | Route an admin through sign-in on 401 or after 30 days |
Known gaps & limitations
Trust is the product. Here's the honest list.
Quick check
curl -s https://storefront.okcapsule.app/.well-known/oauth-authorization-server | jq '{issuer, authorization_endpoint, token_endpoint, registration_endpoint, code_challenge_methods_supported}'Reference docs are consolidating under api2-docs.okcapsule.app .