Skip to main content
Every client connects to the same endpoint:
The transport is Streamable HTTP (POST with Accept: application/json, text/event-stream), and the server also works in stateless mode. Authentication is OAuth 2.1 with PKCE for people, or an API key for headless software. The account you sign in to decides whether you get buyer tools, seller tools, or both; the URL never changes. For the fastest path, follow Connect in five minutes.

​
Host setup

codex mcp login runs the OAuth flow in your browser and stores the tokens with Codex.
Start claude, run /mcp, select semicola and sign in. Add --scope project to share the server entry (never the tokens) with your team through .mcp.json.
Add a custom connector (Claude) or a connector in developer mode (ChatGPT) with the endpoint URL above, and choose OAuth. Both hosts support MCP Apps, so Semicola widgets such as Sellers, Proposals and AI Business Rules render inside the conversation.
Add a remote server with the endpoint URL and OAuth. A compliant client needs no other settings: the first unauthenticated request returns 401 with a WWW-Authenticate header whose resource_metadata points to the discovery document. Clients that cannot do OAuth can send an API key as Authorization: Bearer <key>.
Browser-based MCP clients must have their exact origin registered under Settings → API access → Browser origins in the Semicola app, or CORS will block them.

​
What a healthy connection looks like

  1. initialize succeeds and the server reports its name and version.
  2. tools/list returns the shared tools plus buyer or seller tools for your account.
  3. get_status names the active account and role.
If step 2 shows only shared tools, the active account is an organization or has no role that can buy or sell. Switch accounts with switch_account.

​
Connection lifetime

  • The server may close a connection after 30 minutes or during a deploy. Reconnect and carry on; do not design work around one long-lived call.
  • If a call is interrupted, the operation may still have happened even though you lost the answer. Read the object again, then retry with the same idempotencyKey if it did not.
  • When you switch accounts, the server sends notifications/tools/list_changed. Fetch tools/list again before planning.

​
Local development

When you run the Semicola stack on your machine, point the client at http://localhost:4000/mcp/v3. The local API acts as its own authorization server and publishes the same discovery documents, so the OAuth flow is identical.

Authentication

OAuth resource binding, API keys and tokens.

Limits

Call duration, payload size and proposal fan-out bounds.