> ## 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`), 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](/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 access →
  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`.

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

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