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

> Apostra's account-resolved MCP API preview.

<Note>
  **Preview.** v2 remains the stable, default API. Selecting v3 in the
  documentation picker does not change an integration. Every authenticated Buyer
  or Seller Account can connect to v3; the tools returned still depend on that
  account's permissions and resource access.
</Note>

The v3 Agent Surface is one MCP endpoint whose tools follow the account you
authenticated as:

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

v3 is intentionally an agent-facing MCP contract, not a versioned REST
replacement. The narrow exception is authenticated, exact reads of approved
public agreement revisions at `/api/v3/documents`; its [OpenAPI contract](https://api.apostra.com/api/v3/openapi.yaml)
describes the section and full-download resources. Other REST integrations
should continue to use the stable v2 REST APIs; v2 is not deprecated. v3 and
v2 call the same underlying Apostra services and work with the same account
data.

When a bounded section read returns a continuation, repeat the returned
`applicability.asOf` as the `asOf` query parameter with the opaque cursor. It
keeps the resumed read bound to the same server-evaluated account context.

Instead of choosing a buyer or seller URL, connect once and call `get_status`.
It tells you which account you are in, whether that account is ready to work,
what is blocking it, and which other accounts you may switch to.

<CardGroup cols={2}>
  <Card title="Connect to v3" icon="plug" href="/v2/setup/v3/quickstart">
    Configure an MCP client, authenticate, verify the current account, and make
    the first calls.
  </Card>

  <Card title="Understand the model" icon="diagram-project" href="/v2/setup/v3/concepts">
    Learn how accounts, nouns, verbs, Pages, and tool discovery fit together.
  </Card>

  <Card title="Build a buyer workflow" icon="bullhorn" href="/v2/setup/v3/buyer-workflows">
    Create an advertiser and campaign, request proposals, stage media buys, and
    launch explicitly.
  </Card>

  <Card title="Choose an integration architecture" icon="sitemap" href="/v2/setup/v3/integration-architecture">
    Distinguish an interactive MCP client from a registered buyer agent, then
    place creative handoff, workflow state, and human approvals.
  </Card>

  <Card title="Build a seller workflow" icon="store" href="/v2/setup/v3/seller-workflows">
    Read readiness, configure identity and inventory, operate work, and inspect
    delivery.
  </Card>

  <Card title="Use shared workflows" icon="arrows-left-right" href="/v2/setup/v3/shared-workflows">
    Navigate accounts, search public documentation, and file or track asks.
  </Card>

  <Card title="Browse the tool catalog" icon="screwdriver-wrench" href="/v2/setup/v3/tool-reference">
    See which tools belong to every account, buyers, sellers, or MCP Apps.
  </Card>

  <Card title="Review preview limits" icon="triangle-exclamation" href="/v2/setup/v3/limitations">
    Know what remains on v2 and which fields or transitions are not complete.
  </Card>
</CardGroup>

## What changes from v2

| v2 stable                                  | v3 preview                                     |
| ------------------------------------------ | ---------------------------------------------- |
| Separate buyer and storefront MCP URLs     | One account-resolved MCP URL                   |
| Broad compatibility through `api_call`     | Bounded reads and typed writes                 |
| URL selects the persona                    | Authenticated account selects the tool catalog |
| `customer_switch` changes customer context | `switch_account` changes account context       |
| REST and MCP                               | MCP plus narrow immutable-document REST reads  |

v3 uses shared read verbs where the shape is safe to generalize:

* `search` lists or searches a supported `kind`.
* `get` reads one object and optional related detail.
* `save_<noun>` creates or updates one typed noun.
* Domain actions such as `request_proposals` and `get_delivery` remain explicit.
* `open_page` hands sensitive or interactive work to a human-facing Page.

There is no generic v3 dispatcher. The input schema returned by `tools/list` is
the contract for the current account.

## Account kinds

| Account kind | Current role in v3                                                      |
| ------------ | ----------------------------------------------------------------------- |
| Buyer        | Sellers, advertisers, campaigns, creatives, proposals, and media buys   |
| Seller       | Seller identity, inventory, coverage, merchandising, work, and delivery |
| Organisation | Navigation and shared tools; no organisation-specific noun catalog yet  |

In a buyer account, `search({kind: "seller"})` lists exact Storefront
targets with account selection, billing, connection, and advertiser activation
state. Use `search({kind: "connection"})` or `get` for existing grants, and
`save_connection` for selection, billing, authorization, provider-account
selection, advertiser mapping, or removal. Authorization returns a browser URL;
provider credentials are never accepted in an MCP tool call.

When an agent already has exact Storefront ids, it can fetch up to 50 in one
bounded read instead of issuing one `get` call per seller:

```json theme={null}
{
  "kind": "seller",
  "filter": { "ids": ["1731", "1740"] }
}
```

Results preserve the requested order and report unavailable ids in
`objects.missingIds`. `get` remains the singular exact-object read.

For an account that has not yet been classified as a Buyer or Seller Account,
`get_status` and `switch_account` remain available for orientation and account
navigation without exposing an operational tool catalog.

## Current maturity

The Seller surface is the broadest. The Buyer surface supports seller
connections, campaign authoring, proposal requests, media-buy staging, and
explicit campaign launch. Some lifecycle transitions and advanced policy
fields still require v2; the
[preview limitations](/v2/setup/v3/limitations) page is the authoritative list.

v3 is a facade over the same Apostra services and account data as v2. It is
a different agent contract, not a second platform, and no v2 deprecation is
proposed.