Built for Agents

Apostra API is built from the ground up for AI agents. REST and MCP share the authenticated customer context and converge on canonical services; MCP tools reuse REST operation schemas where that contract applies. Each MCP version then presents capabilities in a tool shape suited to its lifecycle: stable V2 persona connectors and an account-resolved V3 preview.

Why agent-first

Shared contracts

REST routes, named operations, and MCP tools converge on canonical services, reusing schemas and authorization checks where their contracts overlap. Automated parity gates catch drift. See Philosophy for the SESOFI pattern (Single Endpoint, Single Object, Full Intent) that keeps composite intents legible.

Versioned agent surfaces

V2 retains broad generic dispatch for compatibility and adds typed tools for high-value work. The V3 preview uses one account-resolved endpoint with noun-shaped reads and typed writes.

Declarative tool surface

V2 skill files and ask_about_capability teach the broad operation surface on demand. V3 uses bounded search and get reads plus explicit noun schemas, so agents do not have to memorize routes.

Role and account aware

V2 buyer and storefront URLs are persona-scoped. V3 resolves its catalog from the authenticated account and keeps navigation available when the account is outside the preview cohort.

Supported AI agents

Claude (Claude.ai Team/Enterprise, Claude Desktop, Claude Code)
ChatGPT (MCP Connectors and Custom GPTs)
Microsoft Copilot Studio
Google Gemini Enterprise
Cursor
Custom agents — anything that speaks MCP or HTTP

Per-agent setup details are below; the Quickstart is a one-page index that links here.

Connection Methods

There are two ways to connect, and they reach the same platform:

Connect an AI assistant (MCP) — use Claude, ChatGPT, another MCP host, or an agent you built. You describe what you want in plain language and the assistant makes the calls for you. Best when you want a helper that decides things and you don’t want to write code.
Call the API directly (REST) — your own code calls our REST endpoints with a user API key or M2M credentials. Best when you want something exact, repeatable, and automated on your own servers.

Both reach the same platform and the same underlying services, but they are not identical surfaces. The MCP tool catalog varies by version, account, and enrollment (see Available MCP Tools), and not every REST operation is exposed as an agent tool. Pick the method that fits how you want to work, then confirm the specific operations you need are available on it.

Buyer-agent credential administration

A directly authenticated WorkOS organization administrator can issue an identity-only WorkOS M2M credential or register an active, organization-owned or issued, never-before-bound API key or M2M client as a distinct buyer-agent identity. An issued credential authenticates the automation but carries no advertiser, account, spend, payment, Terms, or other action permissions. Keep its one-time client secret secure: it is never shown again. An API key that has already lazily resolved to the organization operator cannot be reclassified; use a distinct eligible credential. A WorkOS M2M client-secret rotation keeps the same client subject and identity and does not use this API. An API-key replacement preserves an agent identity only when the service verifies the same customer workload lineage and direct predecessor. Replacing an issued M2M client is similarly limited to the issuer’s server-recorded workload lineage; organization ownership or an administrator assertion cannot move an identity. A registered credential cannot move to another principal or be replayed after retirement. Revocation permanently disables and archives that credential for Apostra authentication, stops every integration using it, and cannot be undone by re-registration. The principal is suspended only after its final active binding is revoked. These administration endpoints use the shared API v2 base URL https://api.apostra.com/api/v2, rather than the Buyer Base URL in the table below. Domain-signed Agents stay on their protocol-native verification and materialization path rather than using this administration API.

REST API

Standard HTTP REST API for traditional integrations:

Environment	Buyer Base URL	Storefront Base URL
Production	`https://api.apostra.com/api/v2/buyer`	`https://api.apostra.com/api/v2/storefront`

MCP (Model Context Protocol)

For AI agent integrations using JSON-RPC 2.0:

Environment	Buyer MCP Endpoint	Storefront management MCP	Canonical Storefront Agent URL
Production	`https://api.apostra.com/mcp/buyer`	`https://api.apostra.com/mcp/storefront`	`https://interchange.io`

The REST URLs are pinned to v2 and will keep serving v2 even after a future major version ships. The buyer and storefront-management MCP URLs are unversioned aliases that auto-redirect to whatever is currently stable (today: v2). The canonical storefront agent URL is an identity publishers list in adagents.json; it is not the operator’s management connector. See Versioning for when to use each.

The limited V3 Agent Surface preview uses https://api.apostra.com/mcp/v3. It is account-resolved and does not replace the stable V2 connectors.

Connection lifetime

A single MCP connection is held open for at most 30 minutes, after which the server closes it. This is a limit on one connection, not on your session: your session id stays valid, and reconnecting with it resumes where you left off. Well-behaved MCP clients — Claude, ChatGPT, Cursor — reconnect on their own, so in normal use you will not notice this.

The same 30-minute limit applies to a single tool call. A call that has not returned within 30 minutes is cut off and its result is lost — reconnecting cannot recover it, because the result was never produced. Long-running work such as product discovery against a slow sales agent should be issued as an asynchronous operation and polled, rather than awaited on one open call.

Connections also close when we deploy. That is routine, it happens several times a day, and it is handled the same way: reconnect with your existing session id. A deploy does wait for in-flight tool calls to finish before closing them — but only for about three and a half minutes. A call still running when that window closes is cut off and loses its result, exactly as if it had hit the 30-minute limit. Because deploys happen several times a day, a call you expect to take minutes is materially more likely to be interrupted than a fast one. That is the strongest reason to run long work as an asynchronous operation and poll it, rather than holding one call open and hoping.

Available MCP Tools

The exact catalog comes from tools/list and can vary by version, account, and enrollment. Use this table to choose the contract; do not assume every endpoint always exposes exactly three tools.

Connector	Tool model	Discovery and execution
V2 buyer/storefront	Generic compatibility tools plus registered typed, workflow, and MCP App tools	`ask_about_capability` discovers broad V2 operations; `api_call` covers the compatibility tail; typed tools carry exact schemas for enrolled capabilities
V3 preview	Shared reads/navigation plus typed `save_<noun>` writes and bounded domain verbs	Start with `get_status`; use `search`/`get`, `open_page`, and the account’s typed nouns
V2 buyer/storefront	Includes the conversational `ask_murph` entry point; account enablement gates execution	Use it for guidance and support; use the connector’s operational tools for deterministic reads and writes

V2 generic dispatch remains supported, but a newly published REST route is not implicitly agent-callable: operation registries, schemas, authorization, and surface-sync gates make that decision explicit.

Automating storefront setup

A storefront operator can connect Claude Code, Codex, Cursor, or another MCP client to:

https://api.apostra.com/mcp/storefront

Authenticate as a user or API key on the storefront account. The connector can use ask_about_capability to discover setup and product operations, then api_call to read or change the same storefront resources available over REST. For example, it can inspect inventory, draft and bulk-create products from an attached spreadsheet, configure buyer routing, and check readiness. Mutating operations retain the same authorization and confirmation requirements as the rest of Apostra. For Codex, register the HTTP connector and complete its OAuth login:

codex mcp add interchange-storefront --url https://api.apostra.com/mcp/storefront
codex mcp login interchange-storefront

When an MCP client uses a local callback, Apostra leaves the browser confirmation page open. Select Continue to return to the client. If the client is not listening yet, leave the page open and select Continue again after restarting it. The callback link expires after 10 minutes.

For headless automation, set an API key in an environment variable and register it with --bearer-token-env-var instead of putting the key in shell history. This operator connector is separate from the buyer-facing AdCP endpoint at https://<seller-cname>/adcp/mcp, with https://api.apostra.com/seller/{platformId}/mcp as the shared-host fallback. A hosted Seller exposes that endpoint when it is configured to advertise as an agent. An external buyer agent authenticates with its own Apostra buyer credentials: the same API key it uses for the buyer API, or, on the shared-host endpoint, an OAuth sign-in bound to that one Seller (see OAuth on a Seller endpoint). There is no separate seller-side connection handshake. Calls on that endpoint go through Apostra, not around it: the buyer requests an account with sync_accounts, and a media buy becomes a directed campaign in the buyer’s Apostra account. The Seller decides the account the same way whichever door the buyer uses; see Who decides your account request. Submitted media buys follow the Seller Account’s media-buy approval mode and acceptance policy. See Approvals. Both endpoints also expose a conversational assistant tool when it is enabled for your account:

Tool	Purpose
`ask_murph`	Ask Apostra, your AI guide to Apostra, a plain-English question — “how do I…”, “why is my campaign in this state”, “what changed recently” — or file a support report

ask_murph is available once the assistant is enabled for your account. If it is not yet turned on, the call returns a friendly “not enabled” message instead of an answer — contact Apostra support to enable it. Use ask_murph for guidance and support, and the connector’s operational tools for deterministic reads and mutations.

Connecting AI Agents

Claude Connector (Claude.ai Team / Enterprise)

This is the recommended way to connect Claude to Apostra. It provides OAuth-based authentication and works across both Claude.ai (browser) and Claude Desktop automatically.

Admin Setup (one-time):

Go to claude.ai → Admin Settings → Integrations → MCP Connectors
Click Add Connector
Enter the MCP endpoint URL: https://api.apostra.com/mcp/buyer
Name it (e.g., “Apostra API”)
Save the connector — it is now available to all members in your organization

User Setup:

Go to claude.ai → Settings → Integrations → MCP Connectors
Find Apostra connector and click Connect
Log in with your Apostra credentials when prompted (OAuth)
Start chatting! Ask Claude: “List my advertisers” or “Create a performance campaign”

Once connected via the connector, it works in both Claude.ai (browser) and Claude Desktop. No separate configuration needed.Claude saves the name chosen when an organization owner adds a custom connector. To replace an older Interchange name, the owner must remove that connector and add the same api.apostra.com endpoint again with an Apostra name.

Claude Desktop (Personal / Manual Setup)

If you don’t have a Claude Team or Enterprise plan, you can connect Claude Desktop directly via OAuth. Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "apostra-buyer": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.apostra.com/mcp/buyer"]
    }
  }
}

Restart Claude Desktop. The first call opens a browser for you to sign in to Apostra — mcp-remote caches the OAuth token afterward. If you need to use an API key instead (CI, headless environments), pass it as a header:

{
  "mcpServers": {
    "apostra-buyer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.apostra.com/mcp/buyer",
        "--header",
        "Authorization: Bearer scope3_your_api_key_here"
      ]
    }
  }
}

Claude Code (CLI)

OAuth (recommended — no key to manage):

claude mcp add --transport http apostra-buyer https://api.apostra.com/mcp/buyer
claude

The first call to the server opens a browser to sign in to Apostra. Claude Code caches the token after that. API key (CI, headless, or if you can’t open a browser): pass the header on registration. Claude Code’s HTTP transport doesn’t read environment variables, so the API key must be set as a header here.

claude mcp add --transport http apostra-buyer https://api.apostra.com/mcp/buyer \
  --header "Authorization: Bearer scope3_your_api_key_here"
claude

Then ask: “Use ask_about_capability to learn how to list advertisers, then use api_call to list them” Once connected, Claude Code can also talk to Apostra directly through the same server — no extra setup. Just ask a question in plain English and Claude Code will call the ask_murph tool:

Ask Apostra why my campaign is still in PENDING

Ask Apostra how to register credentials for a sales agent

Apostra keeps its own conversation thread (returned as conversationUid in the tool result); follow-up questions in the same Claude Code session continue that thread. ask_murph is for guidance and support — for actual reads or mutations, Claude Code uses api_call.

ChatGPT

Important: ChatGPT MCP connectors use OAuth authentication only. Custom headers like x-scope3-api-key are not supported. Authentication is handled automatically through the OAuth login flow.

MCP Connector
Custom GPT

Connect ChatGPT to Apostra via MCP:

Go to ChatGPT → Settings → MCP Connectors
Click Add Connector
Enter MCP Server URL: https://api.apostra.com/mcp/buyer
Select OAuth as the authentication method
Complete Apostra login flow when prompted
Once connected, you’ll have access to 3 tools:
- health - Check API status
- ask_about_capability - Learn about available endpoints
- api_call - Make authenticated API calls
Test with: “Use ask_about_capability to learn how to list advertisers”

Create a Custom GPT with OAuth:

Go to ChatGPT → My GPTs → Create a GPT
Go to Configure → Actions → Create new action
Import the OpenAPI spec:
- Click Import from URL
- Enter: https://api.apostra.com/api/v2/buyer/openapi.yaml
Set up OAuth authentication:
- Authentication type: OAuth
- Client ID: Register the redirect URI ChatGPT shows for your action through /auth/register, then paste the returned client_id.
- Authorization URL: https://api.apostra.com/authorize
- Token URL: https://api.apostra.com/auth/token
- Scope: openid profile email
Save and test with: “List all my advertisers”

Custom browser agents

For the full sign-in walkthrough for an agent you build, including registration options, tokens, and error messages, see Sign in a self-built agent. If your agent runs in a browser you control, register its OAuth redirect URI. MCP SDK clients do this automatically when they first connect; register by hand only if you are writing the OAuth flow yourself. No account admin has to approve your agent first: the person signing in approves it on the consent screen, which shows the domain its redirect URI points to and your agent’s name, labeled as chosen by the agent and not verified. Control, bidirectional-override and zero-width characters are removed from client_name.

Register the OAuth redirect URI

curl -X POST https://api.apostra.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Example Agent",
    "redirect_uris": ["https://mcp.example.com/oauth/callback"]
  }'

The response includes a generated client_id. Use that client_id when starting OAuth. Register every callback URL your agent will use, including the path; https://mcp.example.com/oauth/callback and https://mcp.example.com/callback are different redirect URIs. Redirect URI rules:

Production redirect URIs must use https://.
Local development callbacks may use localhost redirect URIs.
Desktop and mobile apps may use a private-use URI scheme, such as cursor://anysphere.cursor-mcp/oauth/callback or com.example.agent:/oauth/callback. Apostra matches it exactly, so register the full URI your app uses. The scheme must be a valid URI scheme (a letter, then letters, digits, +, - or ., at least two characters). These schemes are refused: http (other than localhost), javascript, data, file, blob, vbscript, about, filesystem, ws, wss and ftp.
Redirect URIs must not include fragments (#...) or embedded usernames/passwords.
Dynamic registration creates a public OAuth client for PKCE (token_endpoint_auth_method: "none"). Do not treat the generated client_id as a secret.

Calling Apostra from the browser

Browser code on any origin may call the MCP, OAuth and discovery paths: /authorize, /auth/register, /auth/token, /auth/revoke, /.well-known/*, /mcp, /mcp/* and per-Seller /seller/{id}/mcp endpoints. These paths do not open the rest of the REST API to your origin. The consent step where a person approves or denies your client runs only on Apostra’s own pages, with that person’s sign-in. Your origin gets CORS without credentials: Apostra returns Access-Control-Allow-Origin but not Access-Control-Allow-Credentials. Send the OAuth access token as a bearer token; never rely on Apostra UI cookies or credentials: "include". A page without a token gets nothing, which is why no origin needs approving. Requests from an opaque null origin (a sandboxed srcdoc frame or a file: page) are refused.

Security posture

Account access is gated by the person signing in, the consent screen, PKCE, and exact redirect URI matching: an authorization code is only ever sent to a redirect URI registered for the client that asked for it. If a browser request is blocked:

Confirm the OAuth redirect URI is the full callback URL and was registered through /auth/register.
Confirm the request is going to one of the browser MCP/OAuth paths above, not an arbitrary REST endpoint.
Confirm the browser request does not require cookies or credentials: "include".

Client ID Metadata Documents

Instead of registering, an agent can identify itself with a URL. Apostra supports OAuth Client ID Metadata Documents, as the MCP specification recommends. The authorization server metadata at /.well-known/oauth-authorization-server advertises client_id_metadata_document_supported: true, so MCP clients that prefer this method use it on their own. Dynamic client registration keeps working. To use it, host a JSON document at an https URL you control and send that URL as the client_id when you start OAuth:

{
  "client_id": "https://agent.example.com/oauth/client.json",
  "client_name": "Example Agent",
  "client_uri": "https://agent.example.com",
  "redirect_uris": ["https://agent.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none"
}

Apostra fetches the document when a person starts authorizing your agent, so there is nothing to register first. The consent screen shows your client_name and the domain of the client_id URL, which is how the person checks who published the agent. Document rules:

The URL must use https, have a path (not just /), and contain no fragment, username, password or ./.. path segments.
client_id in the document must equal the URL exactly, and redirect_uris is required. Each redirect URI follows the redirect URI rules above, and the redirect_uri you send to /authorize must match one of them exactly.
This is a public client. Leave token_endpoint_auth_method out or set it to none; shared secrets (client_secret) and private_key_jwt are not accepted. Use PKCE (S256), as with every Apostra OAuth client.
Serve the document with status 200 and a JSON content type, as no more than 5 KB. Apostra does not follow redirects, only connects to public internet addresses, and gives up after a few seconds.
Apostra caches a valid document for as long as your Cache-Control: max-age says, between 1 minute and 24 hours (5 minutes if you set none). It remembers a failed lookup for about a minute. Changes to redirect_uris take effect once the cached copy expires.

Microsoft Copilot Studio

A maker can add Apostra as a Model Context Protocol tool directly in Copilot Studio — no Microsoft review required. See Connect Apostra to Microsoft Copilot Studio for the full walkthrough, including the OAuth setup and the manual client-registration fallback if Copilot Studio’s wizard doesn’t complete dynamic client registration automatically.

Google Gemini Enterprise

A Gemini Enterprise admin can add Apostra as a Connected App — this is a tenant-admin action with no review from Google. See Connect Apostra to Gemini Enterprise for the admin console fields (server URL, authorization URL, token URL, scopes) and the 100-enabled-actions cap.

Cursor

Configure Cursor with Apostra MCP server:

Open Cursor Settings → MCP tab
Add a new MCP server:
- Name: apostra
- URL: https://api.apostra.com/mcp/buyer
- Headers: Authorization: Bearer your-api-key
Restart Cursor
In chat, ask: “Use Apostra tools to list advertisers”

What the server tells your agent on connect

Every MCP session starts with operating instructions the server sends during the handshake. Your agent receives them automatically — nothing to configure — and they are the same rules our own assistant follows. Knowing what is in them tells you what behaviour to expect, and what to preserve if you wrap our tools in your own harness. For a storefront connection: Orient before acting. Call get_storefront_readiness for the current configuration state and what is blocking the storefront from transacting, rather than reconstructing it from a series of list calls. Look up the operation before calling it. api_call takes a named operation; there is no raw method-and-endpoint mode, and an invented name is rejected. Call ask_about_capability first for the exact operation name and field shapes. Prefer a typed tool where one exists. Route explanation to Apostra. “How do I…”, “why is my X stuck in state Y”, “what changed recently” and “I think this is broken” go to ask_murph, which searches the published documentation, inspects live storefront state, and can file an internal report. Apostra is read-only; mutations stay on api_call or a typed tool. One mutating call per turn. Make one write, present the result, then stop and wait for the user. Verify success before reporting it. A call succeeded only if the status is 2xx and the payload carries the endpoint’s success indicator — a returned id, the updated resource, an empty 204. A 202 means queued, not done: report it as kicked off and surface the operation id. If the indicator is missing or contradicts success, surface the error verbatim and do not say the change was made. Do not answer publisher authorization from memory. Whether a domain needs an adagents.json entry, and what belongs in it, depends on how that inventory is sold. Look it up through Apostra or the published documentation, or read live state via open_property_roster — see Identity documents. State only what the data shows. If a tool returns no results, say so rather than speculating about why. Never claim a connection, authorization, or status exists unless a tool response contains it.

Authentication

Use OAuth for Claude/ChatGPT MCP connectors (handled automatically) or an API key (Authorization: Bearer scope3_...) for CLIs, Cursor, and custom agents. See Authentication for full details. To sign in an agent you build yourself, see Sign in a self-built agent.

Notifications

The API surfaces unread notifications inline in ask_about_capability responses and when an MCP session starts, so agents can proactively flag campaign or creative issues to users. These are the same notifications list_notifications returns for that user: their in_app opt-ins plus always-on operational types, so the count an agent reports always matches the user’s feed. See the Notifications guide for setup and the REST endpoints.

Next Steps

Quickstart

Connect Claude, ChatGPT, Cursor, or a custom agent in minutes.

Buyer Onboarding

The end-to-end campaign-launch journey for buyer integrations.

Skill

What skill.md is and how agents use it for capability discovery.

Authentication

API keys, OAuth, and SSO configuration.

​Why agent-first

Shared contracts

Versioned agent surfaces

Declarative tool surface

Role and account aware

​Supported AI agents

​Connection Methods

​Buyer-agent credential administration

​REST API

​MCP (Model Context Protocol)

​Connection lifetime

​Available MCP Tools

​Automating storefront setup

​Connecting AI Agents

​Claude Connector (Claude.ai Team / Enterprise)

​Claude Desktop (Personal / Manual Setup)

​Claude Code (CLI)

​ChatGPT

​Custom browser agents

​Register the OAuth redirect URI

​Calling Apostra from the browser

​Security posture

​Client ID Metadata Documents

​Microsoft Copilot Studio

​Google Gemini Enterprise

​Cursor

​What the server tells your agent on connect

​Authentication

​Notifications

​Next Steps

Quickstart

Buyer Onboarding

Skill

Authentication

Why agent-first

Supported AI agents

Connection Methods

Buyer-agent credential administration

REST API

MCP (Model Context Protocol)

Connection lifetime

Available MCP Tools

Automating storefront setup

Connecting AI Agents

Claude Connector (Claude.ai Team / Enterprise)

Claude Desktop (Personal / Manual Setup)

Claude Code (CLI)

ChatGPT

Custom browser agents

Register the OAuth redirect URI

Calling Apostra from the browser

Security posture

Client ID Metadata Documents

Microsoft Copilot Studio

Google Gemini Enterprise

Cursor

What the server tells your agent on connect

Authentication

Notifications

Next Steps