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

# v3 Quickstart

> Connect an MCP client to the account-resolved v3 API and make the first calls.

<Note>
  v3 is available to every authenticated buyer and seller account. The account
  selected by your credential determines which tools appear; existing v2 APIs
  remain supported.
</Note>

## Before you connect

You need:

* an Apostra account;
* an OAuth login or API key with the permissions your work needs; and
* an MCP client that supports remote streamable HTTP servers.

Interactive clients should use OAuth. Headless automation may use a user API
key stored in an environment variable or secret manager. See
[Authentication](/v2/authentication) for credential types and permissions.

## Add the endpoint

The v3 endpoint is:

```text theme={null}
https://api.interchange.io/mcp/v3
```

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

    For headless automation, use Codex's bearer-token environment-variable
    option instead of placing a key in shell history.
  </Tab>

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

    The first use opens Apostra OAuth flow. For non-interactive use,
    follow Claude Code's HTTP-header configuration and read the key from your
    secret-management environment.
  </Tab>

  <Tab title="Claude Desktop">
    Add a remote MCP server to the Claude Desktop configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "interchange-v3": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.interchange.io/mcp/v3"
          ]
        }
      }
    }
    ```

    Restart Claude Desktop. The first call opens the OAuth sign-in flow.
  </Tab>

  <Tab title="Other MCP clients">
    Add a remote streamable HTTP server with the v3 URL. Use OAuth when the
    client supports it, or send the user API key as:

    ```text theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```
  </Tab>
</Tabs>

The broader [Built for Agents](/v2/setup/built-for-agents#connecting-ai-agents)
guide covers ChatGPT, Cursor, credential handling, and client-specific setup.
Use the v3 URL in place of the stable buyer or seller URL.

## Verify the connection

Ask the client:

```text theme={null}
Call get_status and tell me which Apostra account I am in,
its readiness, and which accounts I can reach.
```

Each buyer or seller receives account readiness plus its account-specific
catalog. An account that is not classified as either receives only the
information needed to orient or switch accounts.

<Warning>
  A successful connection proves authentication, not authorization for every
  operation. Tool calls still enforce the selected account, user permissions,
  and resource-level access. The `get_status` result is the authority on the
  active account and its readiness.
</Warning>

## Hosts without a widget surface

For commercial operator domains, advertiser branding and supported human
verification, follow [Identity and brands](/v2/setup/v3/identity-setup).
That flow returns current state, previews and proof status in text.

Some tools open an interactive page in hosts that support MCP apps. A host
that cannot render them, such as Claude Code or a plain MCP client, still
receives the tool's text result. When a buyer account opens the Creative
Library with `open_creative_library`, or the Campaigns Page for an advertiser
with `open_campaigns_page`, that text includes an `Open in the browser:` link
that opens the same Page in Apostra chat for the account your API key
belongs to, with the chat input below it. The link addresses the advertiser
(and the focused campaign, when there is one), so it stays valid outside the
conversation that produced it. The same URL is available as `openInBrowserUrl`
in the structured result. A seller account that opens the Campaigns Page for
its own-supply or sponsored-buyer scope gets no link: the buyer hosted chat
does not model those scopes.

To open a campaign's Creative composer, call `open_creative_library` with
`lens: "composer"`, `campaignId`, and optionally `sessionId` for an editable
Creative Session to resume. `campaignId` is required for this lens. Its browser
link uses `creativeAction=compose` with the same campaign and optional session
state, so a host without a widget surface opens the Composer Task in
Apostra chat instead of losing the draft. The buyer-only composer lens
creates a durable draft when no session is supplied, using the campaign's
configured Creative Engine. If the campaign does not declare exactly one
composer-supported format, the draft starts as Snap Story and the Task directs
the buyer to change the format in chat.

## Switch accounts

Use an `accountId` returned by `get_status`:

```json theme={null}
{ "accountId": 624 }
```

After `switch_account`, call `get_status` again. A principal who can reach both
Buyer and Seller Accounts already receives both tool families at connection
time, but the status read confirms which selected account can authorize each
account-specific tool. v3 also emits `notifications/tools/list_changed`, though
clients do not all refresh the same way.

Omit `accountId` only when you intend to return to the credential's home
account:

```json theme={null}
{}
```

## Make a first read

Choose a noun that belongs to the active account:

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

    Then read one returned campaign:

    ```json theme={null}
    { "kind": "campaign", "id": "CAMPAIGN_ID" }
    ```
  </Tab>

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

    Then read one returned source:

    ```json theme={null}
    { "kind": "inventory_source", "id": "SOURCE_ID" }
    ```
  </Tab>
</Tabs>

Kinds differ by account. Use the current `search` and `get` input schemas from
`tools/list`; do not copy a kind from a different account's stale catalog.

## Safe first-write checklist

Before a write:

1. Read the object and retain its current ID and revision when provided.
2. Use the typed `save_<noun>` tool shown in the current catalog.
3. Send only fields you intend to change.
4. Supply `expectedRevision` when the schema offers it.
5. Reuse an idempotency key only for the same logical attempt.
6. Read the object again and confirm the reported outcome.

Continue with a [buyer workflow](/v2/setup/v3/buyer-workflows), a
[seller workflow](/v2/setup/v3/seller-workflows), or the
[tool catalog](/v2/setup/v3/tool-reference).