Skip to main content
Every client connects to the same endpoint:
The transport is Streamable HTTP (POST with Accept: application/json, text/event-stream). It supports both the initialize session lifecycle and stateless requests; MCP clients pick one on their own. 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 keys → 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. If you’re a member of both a Buyer and a Seller account, tools/list returns the deduplicated union of both catalogs, so a host that caches the list keeps both workflows after a switch. Tools still run only in the selected account. Calling a buyer tool while a Seller account is selected (or the reverse) returns WRONG_ACCOUNT, naming the account kind the tool needs and, when you have one, details.switchAccount with the switch_account arguments to use before retrying. Buyer agents get no union: they see buyer tools only.

​
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.
  • An authenticated initialize opens a session: keep sending the Mcp-Session-Id header it returns, and DELETE the endpoint with that header to end it. A session is tied to the person or key that opened it. It ends after 60 minutes idle or when the server restarts; then requests with its id get 404 with JSON-RPC error -32001 (“Session not found”), and your client should initialize again. Requests without a session id are served statelessly.
  • 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.