> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP client setup

> Connect Codex, Claude Code, Claude, ChatGPT or another MCP host to Semicola's account-resolved endpoint.

Every client connects to the same endpoint:

```text theme={null}
https://api.semicola.com/mcp/v3
```

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](/v3/quickstart).

## Host setup

<AccordionGroup>
  <Accordion title="Codex" icon="terminal">
    ```bash theme={null}
    codex mcp add semicola --url https://api.semicola.com/mcp/v3
    codex mcp login semicola
    ```

    `codex mcp login` runs the OAuth flow in your browser and stores the tokens with Codex.
  </Accordion>

  <Accordion title="Claude Code" icon="terminal">
    ```bash theme={null}
    claude mcp add --transport http semicola https://api.semicola.com/mcp/v3
    ```

    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`.
  </Accordion>

  <Accordion title="Claude and ChatGPT" icon="comments">
    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.
  </Accordion>

  <Accordion title="Any other MCP client" icon="plug">
    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>`.
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>

## 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.

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/v3/authentication">
    OAuth resource binding, API keys and tokens.
  </Card>

  <Card title="Limits" icon="gauge" href="/v3/limits">
    Call duration, payload size and proposal fan-out bounds.
  </Card>
</CardGroup>