v3 Quickstart

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.

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 for credential types and permissions.

Add the endpoint

The v3 endpoint is:

https://api.interchange.io/mcp/v3

Codex
Claude Code
Claude Desktop
Other MCP clients

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.

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.

Add a remote MCP server to the Claude Desktop configuration:

{
  "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.

Add a remote streamable HTTP server with the v3 URL. Use OAuth when the client supports it, or send the user API key as:

Authorization: Bearer YOUR_API_KEY

The broader Built for 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:

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.

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.

For commercial operator domains, advertiser branding and supported human verification, follow Identity and brands. 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:

{ "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:

{}

Make a first read

Choose a noun that belongs to the active account:

Buyer account
Seller account

{ "kind": "campaign", "limit": 10 }

Then read one returned campaign:

{ "kind": "campaign", "id": "CAMPAIGN_ID" }

{ "kind": "inventory_source", "limit": 10 }

Then read one returned source:

{ "kind": "inventory_source", "id": "SOURCE_ID" }

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:

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

Continue with a buyer workflow, a seller workflow, or the tool catalog.

Start building

Build your integration

Workflow recipes

MCP reference

Shared reference

Before you connect

Add the endpoint

Verify the connection

Hosts without a widget surface

Switch accounts

Make a first read

Safe first-write checklist

​Before you connect

​Add the endpoint

​Verify the connection

​Hosts without a widget surface

​Switch accounts

​Make a first read

​Safe first-write checklist

Before you connect

Add the endpoint

Verify the connection

Hosts without a widget surface

Switch accounts

Make a first read

Safe first-write checklist