Updated documentation is now at okcapsule.com/mcp

MCP Integration Overview

OKCapsule MCP —
Current integration overview.

How to integrate with OKCapsule's MCP as it stands right now. A deliberate snapshot, not a finished spec — some of the surface is still deploying or under active development.

The MCP is the integration surface OKCapsule supports. One connector lets any AI assistant securely browse the catalog, build packs, and manage orders on behalf of a signed-in staff user — without us building a custom integration for every AI product.

endpointhttps://storefront.okcapsule.app/mcp

discovery/.well-known/oauth-authorization-server

Overview

MCP tools behind OAuth 2.1 — a set of MCP tools sit behind an OAuth 2.1 authorization layer in front of a single /mcp endpoint.
Staff-only, email-OTP login. No passwords, no self-serve signup — OKCapsule provisions staff accounts by email.
MCP tools are the supported contract. The underlying REST endpoints exist but are reference-only and can change without notice.
Consumer-facing access does not exist yet. Only staff accounts can authenticate — see Roles and Known gaps.

Current architecture

The MCP is the integration. It gives you everything the platform offers — catalog, consumers, orders, fulfillments — as ready-made, AI-native tools, with authentication, discovery, and permissions built in. No API to study, no endpoints to wire up, no client library to maintain: any MCP-capable client connects and is working in minutes.

Zero configuration, by design. Everything is discovered at runtime from <base-url>/.well-known/oauth-authorization-server; the MCP endpoint is <base-url>/mcp. Because nothing is hardcoded, your integration continues to work as the platform grows.

The underlying Platform API (v2) endpoints are listed alongside each tool for transparency — useful for tracing what a tool does, but nothing you need to build or maintain. The MCP tools are the supported, stable contract.

Authentication & authorization

The service implements OAuth 2.1 authorization-code + PKCE, with email-OTP login instead of a password. Access is granted to staff of an OKCapsule platform account.

OAuth flow

#	Step	Endpoint	What happens
0	Discovery	GET /.well-known/oauth-authorization-server (+ /.well-known/oauth-protected-resource, /.well-known/jwks.json)	Client learns endpoints, supported scopes, and the public signing key.
1	Register	POST /oauth/register	Dynamic client registration (RFC 7591). Returns a client_id. Public client only — no secret.
2	Authorize	GET /oauth/authorize	Validates client_id, redirect_uri, state, code_challenge (PKCE, S256 required). Renders the email login page.
3	Login → OTP	POST /oauth/login	User enters email; a one-time code is emailed.
4	Verify OTP	POST /oauth/verify-otp	Code is checked. Recognized staff email → consent page. Otherwise sign-in is refused (403).
5	Consent	POST /oauth/consent	User approves scopes and picks a workspace/tenant (if they belong to several). An auth code is minted and redirected back to redirect_uri with state.
6	Token	POST /oauth/token (grant_type=authorization_code)	Exchanges code + PKCE code_verifier for an access token + refresh token.
7	Refresh	POST /oauth/token (grant_type=refresh_token)	Rotating refresh: each use issues a new refresh token and invalidates the old one.
8	Revoke	POST /oauth/revoke	Revokes a refresh token.

Client requirements

PKCE with S256 is mandatory (plain is rejected).
Public clients only — token_endpoint_auth_method must be none; no client secret is issued.
redirect_uri must be https, except localhost / 127.0.0.1 / [::1] loopback over http (for native clients like Claude Code / MCP Inspector).
Grant types limited to authorization_code and refresh_token; response type code only.
Optional RFC 8707 resource parameter, if sent, must equal this server's MCP audience.

Tokens issued

Token	Type	Lifetime	Notes
client_id	Public identifier	Persistent	No secret. From dynamic registration.
Authorization code	One-time	Short-lived	PKCE-bound, single-use.
Access token	RS256-signed JWT	1 hour	Carries persona claims. Verified against JWKS.
Refresh token	Opaque, rotating	30 days	Single-use; each refresh mints a new one and invalidates the prior.
Email verification code	One-time code	Short-lived	Rate-limited.

Access-token JWT claims: sub (platform user id), role, email, tenant_id, tenant_slug, scope, plus iss / aud / jti / iat / exp. One token is bound to exactly one tenant/workspace.

Environments

There is no self-serve sandbox. Two environments exist:

Environment	Base URL	Access
Production	https://storefront.okcapsule.app	Standard integrator access
Staging	https://storefront-stage.okcapsule.app	By arrangement only

Staging requires a staff account provisioned by OKCapsule, and staging data is periodically reset — do not rely on accounts or data persisting there.

Roles & permissions

Tokens are issued to staff of an OKCapsule client (brand) account. Consumer sign-in is not available.
Every token is bound to exactly one client workspace. Nothing crosses workspaces — a token for one client can never read or write another client's data.
What a token can do is exactly its granted scopes. The platform also enforces its own authorization on every call, so a granted scope is necessary but not automatically sufficient for a given operation.

Scopes

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

Scopes are requested at authorization and confirmed by the user at consent; the granted set is echoed in the token response and embedded in the access token. The authoritative list is scopes_supported in the discovery document.

What is read-only

Read-only by design (no write scope exists): catalog, recommendations, fulfillments, status metadata.
Read-only by default: orders. Default grant is orders:read only; create/update/cancel require explicitly requesting orders:write / orders:cancel.
Writable in the default grant: consumer profiles (consumers:write) and document generation (documents:write). Deleting consumers is opt-in (consumers:delete).

Current capabilities

27 MCP tools, each gated by the OAuth scope shown. Tools marked — are session/infra utilities available to any authenticated token.

Category	Tool	Scope	Purpose
Session / infra	okc_authenticate	—	Establish/refresh the session
Session / infra	okc_debug_ping	—	Connectivity and latency check
Session / infra	okc_confirm_pending_action	—	Explicit confirmation step for destructive actions
Catalog	okc_list_brands	catalog:read	List brands (product lines)
Catalog	okc_list_products	catalog:read	List products
Catalog	okc_get_catalog	catalog:read	Full catalog view
Catalog	okc_get_product_intelligence	catalog:read	Ingredient/product intelligence for a product
Catalog	okc_render_pack_builder	catalog:read	Interactive pack-builder UI card
Catalog	okc_pack_builder_url	catalog:read	Create a shareable pack-builder link
Recommendations & documents	okc_validate_recommendation	recommendations:read	Validate a supplement recommendation
Recommendations & documents	okc_generate_supplement_facts_pdf	documents:write	Generate a supplement-facts PDF
Recommendations & documents	okc_list_statuses	meta:read	List order/fulfillment status values
Consumers	okc_get_consumer	consumers:read	Fetch one consumer
Consumers	okc_list_consumers	consumers:read	List/search consumers
Consumers	okc_upsert_consumer	consumers:write	Create or update a consumer
Consumers	okc_delete_consumer	consumers:delete	Delete a consumer (opt-in scope)
Orders	okc_list_orders	orders:read	List orders
Orders	okc_get_order	orders:read	Fetch one order
Orders	okc_get_order_by_client_id	orders:read	Fetch an order by your own order id
Orders	okc_list_order_transaction_logs	orders:read	Order event/transaction history
Orders	okc_render_order_status	orders:read	Order-status UI card
Orders	okc_create_order	orders:write	Create an order (opt-in scope)
Orders	okc_update_order	orders:write	Update an order (opt-in scope)
Orders	okc_cancel_order	orders:cancel	Cancel an order (opt-in scope)
Fulfillments	okc_list_fulfillments	fulfillments:read	List fulfillments/shipments
Fulfillments	okc_get_fulfillment	fulfillments:read	Fetch one fulfillment
Fulfillments	okc_get_shipping_label	fulfillments:read	Retrieve a shipping label

Interactive UI cards

Pack building and order status (okc_render_pack_builder, okc_render_order_status) in MCP clients that support embedded UI.

Destructive-action confirmation

Cancel order and delete consumer require an explicit okc_confirm_pending_action step in addition to their scope.

Server-side catalog mode

A limited read-only, server-side catalog mode (no user sign-in) exists for specific embedding arrangements — ask OKCapsule if that fits better.

Adjacent work in progress

Production rollout of the OAuth flow. The flow described here is fully live on staging; production availability should be confirmed with OKCapsule before scheduling integration work against production.

Mentioned but not partner-ready

Consumer sign-in / consumer-facing persona — planned, no date. Not something to build against today.

Integration model

Happy path

1

Onboarding (with OKCapsule)

The partner becomes an OKCapsule client: OKCapsule provisions the workspace and adds team members as staff users by email. This is the only manual step — everything after is self-serve.
2

Connect

Point any MCP-capable client at https://storefront.okcapsule.app/mcp. 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.
3

Sign in

A team member enters their provisioned email, confirms the emailed one-time code, approves the requested scopes, and (if in several workspaces) picks the partner's workspace.
4

Use the tools

Browse catalog, build packs, upsert consumers, create orders (with orders:write), track fulfillments. Orders can be tagged with your own order id and retrieved later via okc_get_order_by_client_id.
5

Stay signed in

Access tokens last 1 hour and refresh automatically; the rolling refresh window is 30 days, after which the user signs in again.

Do you call the MCP directly?

Yes. The MCP endpoint is the integration surface — POST MCP JSON-RPC over Streamable HTTP to /mcp with Authorization: Bearer <token>. No proprietary SDK, API key, or shared secret. In practice most partners won't hand-roll the protocol: any MCP-capable host (Claude, other AI assistants, or an agent on the open MCP SDKs) speaks it out of the box, including the OAuth handshake. Calling the underlying REST API directly is not part of this contract.

Assumptions about your system

An MCP-capable client supporting Streamable HTTP, OAuth 2.1 authorization-code + PKCE, and dynamic client registration (RFC 7591).
A human signs in. The flow is user-interactive (email code + consent screen). There is no machine-to-machine client-credentials grant today — a person completes the first sign-in, then tokens refresh unattended for up to 30 days.
Your users have OKCapsule staff accounts. Sign-in only works for provisioned emails.
Token handling. Refresh tokens are single-use and rotate on every refresh — always persist the newest one. (MCP hosts handle this; only matters if you build your own client.)
One workspace per token. Acting for several workspaces needs a sign-in per workspace.

What's required on your side

Requirement	Detail
MCP client	Any conformant host or MCP-SDK-based agent — the only technical requirement.
Staff emails	Provide the team-member list to OKCapsule for provisioning.
Redirect URI	https (or localhost loopback for native apps) — supplied automatically by standard MCP hosts during registration.
Scope choice	Decide up front whether you need the opt-in write scopes (orders:write, orders:cancel, consumers:delete).
Secure token storage	Standard OAuth hygiene; persist the rotated refresh token.
Re-auth handling	On a 401 after the 30-day window, send the user through sign-in again.

No IP allowlisting, certificates, webhook endpoints, or server-side infrastructure are required for the standard integration.

Known gaps & current limitations

Consumer sign-in does not exist.

Only staff accounts authenticate; a consumer email at login is refused (403). Consumer-facing flows are planned but have no date.
No machine-to-machine credentials.

No client-credentials grant or API-key mode. Every integration starts with a human signing in; unattended operation is bounded by the 30-day rolling refresh window.
No self-serve sandbox.

Staging exists but is by arrangement only, with manually provisioned accounts and periodic data resets.
Production OAuth rollout is in progress.

The flow is live on staging; confirm production availability before scheduling work against production.
Do not depend on the underlying REST endpoints.

MCP tools are the contract; endpoint paths are informational and can change without notice.
Do not hardcode tool input/output schemas.

Discover tools and schemas at runtime via MCP tools/list — the tool set and schemas are still being refined.
The scope list is not final.

Read scopes_supported from discovery; scopes may be added or split.
Staging accounts/data are not durable.

Reset periodically.
No unattended sessions beyond 30 days.

Plan for periodic human re-auth.
Embedded UI cards don't render everywhere.

Pack-builder and order-status cards depend on the host supporting embedded UI; always handle the plain-data response path.

What is stable: the protocol (OAuth 2.1 + PKCE, Streamable HTTP, MCP), the discovery URLs, and the production base URL. Anything built on runtime discovery should survive as the surface evolves.

Quick discovery check

Fetch the discovery document to confirm connectivity and inspect the live scope list before writing any integration code.

bash

curl -sS https://storefront.okcapsule.app/.well-known/oauth-authorization-server | jq .

OKCapsule MCP —Current integration overview.