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

# Connect in five minutes

> Add Semicola to Codex, Claude Code or any MCP client, sign in with OAuth, and verify the account with a read-only call.

By the end of this page your coding agent will know which Semicola account it is connected to and
will have read its first objects. You need a Semicola account and an MCP client that supports remote
servers over Streamable HTTP. Creating an account or finishing seller onboarding can take longer than
the connection itself.

## 1. Add the connection

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

    The login command opens a browser. Sign in to Semicola, pick the account to use, and approve the
    connection. Then start a Codex session in your project.
  </Tab>

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

    Inside Claude Code, run `/mcp`, choose `semicola`, and complete sign-in in the browser.
  </Tab>

  <Tab title="Other MCP clients">
    Add a remote server that uses **Streamable HTTP** with this URL:

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

    Choose OAuth as the authentication method. The client discovers everything else from the server's
    first `401` response. See [MCP client setup](/v3/client-setup) for host-specific notes.
  </Tab>
</Tabs>

If your client already has a Semicola connection that points at this URL, reuse it. Your agent should
never ask you to paste a password or key into the chat.

<Note>
  OAuth connects the coding session as you. It is not an identity for software you deploy later. For
  a headless service, create an API key and keep it in a secret manager; see
  [Authentication](/v3/authentication).
</Note>

<Tip>
  Running the Semicola stack locally? Use `http://localhost:4000/mcp/v3` instead. The local server
  plays the sign-in role itself, with the same discovery documents.
</Tip>

## 2. Prove account access

Ask your agent:

```text theme={null}
Use the semicola connection to call get_status. Tell me the active account, whether it is a buyer
or a seller, any readiness blockers, and which other accounts I can reach. Do not create or change
anything.
```

If the client reports that the connection still needs authentication, finish OAuth in its MCP
controls and try again. Adding a server is not the same as signing in.

A successful `get_status` proves the connection reaches your account. It does not prove that every
advertiser, seller or write is allowed.

If the wrong account is active, call `switch_account` with a `customerId` from the status result's
`reachableAccounts`, then call `get_status` again. The table at the end of this page covers what to
check when a tool you expected is missing.

## 3. Make a first read

Ask the agent to look at `tools/list`, then call `search` with the input that suits your account:

<Tabs>
  <Tab title="Buyer account">
    ```json theme={null}
    { "kind": "seller", "limit": 10 }
    ```

    This lists sellers and their connection and readiness status for your account. It does not send
    anyone a brief. An empty list is a valid answer, not a broken connection.
  </Tab>

  <Tab title="Seller account">
    ```json theme={null}
    { "kind": "inventory_source", "limit": 10 }
    ```

    This lists the inventory sources connected to your storefront. A new storefront may have none yet.
  </Tab>
</Tabs>

You now have a verified connection and one account-scoped read. The schemas in `tools/list` are the
contract for this session; they can differ by account, role and feature availability.

## 4. Build a small prototype

A good first project is a read-only seller browser for a buyer account:

```text theme={null}
Build a small seller-discovery prototype in this repository using the semicola MCP connection.
Check the account with get_status and read the current tool schemas. List sellers and show their
readiness and connection status. Keep credentials out of the repository. Add a fixture test for a
populated result and one for an empty result. Do not request proposals or create a campaign yet.
Explain how to run it and what the tests prove.
```

The fixture tests prove your code handles the shapes; the live `get_status` and `search` calls prove
account access. Neither proves a campaign can launch. When you are ready to write, read the
[Campaign object guide](/buy/campaign) and the [v3 Tool Catalog](/v3/tool-catalog).

## If the first call fails

| What you see                                    | What to do                                                                                              |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Authentication required                         | Finish OAuth in the client's MCP controls, then retry.                                                  |
| Wrong account, or buyer or seller tools missing | Read `reachableAccounts` from `get_status`, switch to the right account, and refresh the tool list.     |
| Permission denied                               | The credential's account or role lacks access. Reinstalling the connection does not change permissions. |
| A readiness blocker                             | Follow the next action `get_status` returns. A working connection does not finish commercial setup.     |
| The client cannot show a widget                 | Use the structured result or text summary, or switch to a host that supports MCP Apps.                  |