Skip to main content
By the end of this guide, your coding agent can identify your Apostra account and read its first objects. You need an Apostra account and an MCP client that supports remote Streamable HTTP. Account creation, missing permissions, or seller onboarding may take longer than this connection step.
Coming from the v2 storefront API? It is retired for API callers: calls to /mcp/v2/storefront and /api/v2/storefront from an API key or an OAuth client are refused with a 410 Gone (REST) or a GONE tool error (MCP) that points here. Connect to https://api.apostra.com/mcp/v3 (MCP) or call https://api.apostra.com/api/v3 (HTTP) instead. The partner-agent OAuth callback at /api/v2/storefront/oauth/callback is unchanged.
Using regular Claude or Cowork to manage advertising? Connect the hosted MCP connector. The commands below are for Codex and Claude Code.

​
1. Install the Apostra package

If you are building software on Apostra, install the Build with Apostra package. It adds the Build with Apostra skill and Apostra’s MCP connection together, so your coding agent follows Apostra’s recommended patterns, such as the official SDK and the right delivery reads, instead of working them out from scratch. The connection uses your existing account permissions and grants nothing new. This developer guide pins /mcp/v3 because its examples use V3 tools. For a permanent connection URL that follows your account’s feature-profile rollout, use https://api.apostra.com/mcp. See MCP client setup for version selection and ChatGPT setup.
Open a Codex session in your project and complete OAuth when prompted.
Use an existing connection if it already supplies this endpoint. The coding agent should not ask you to paste credentials into chat.

​
Only working in your account? Connect directly

If you want your coding agent to work in your Apostra account rather than build software, you need no package, no Agents account and no API key. Add the MCP server and sign in:
Complete OAuth in the browser, then open a Codex session in your project. See Codex MCP setup for client configuration and OAuth controls.
Interactive OAuth represents you in the coding session. It does not create a runtime identity for finished software. When your own agent or deployed software needs its own identity, set it up in an Agents account, where you manage its credentials, webhooks, and certification. See Developer quickstart. Reuse an existing Apostra Agent when one exists, or prototype safely in the available sandbox.
For a headless application, use an appropriately scoped API credential from a secret manager. Do not put it in a prompt or committed client configuration. See Authentication for supported credential types.

​
2. Prove account access

Ask your agent:
If your client reports that the connection needs authentication, open its MCP controls and complete OAuth before retrying. Adding a server is not by itself proof that sign-in has completed. get_status is a read-only check. A successful result proves that the connection can reach the account. It does not prove that every advertiser, seller, or write operation is authorized. Every later call names its account with the accountId the status result returned. If the wrong account came back, name the right one on the next call; nothing needs switching. An Organisation or unclassified account may offer navigation without buying or selling tools. See Name the account on every call and Account access.

​
3. Make a first read

Ask the agent to inspect tools/list, then call search with the input that matches the account you named:
This lists seller targets and their buyer-specific connection and readiness information. It does not contact sellers with a campaign brief. An empty result is a valid read, not proof that the connection failed.
You now have a verified MCP connection and a first account-scoped read. MCP tools/list output schemas identify each response variant and its required fields; they do not repeat every nested type. They are also open, so a connection opened before an Apostra update keeps accepting the answers that follow it: objects accept fields they do not list, a field with a known set of values lists them as examples instead of a closed enum, and each set of response variants also accepts a variant it does not list yet. Input schemas stay exact. If you validate structuredContent, use that variant-level schema for MCP and use the OpenAPI specification or the TypeScript and Python SDKs for complete typed responses. Tools can differ by permissions and feature availability.

​
4. Build a small prototype

Start with a read-only seller-discovery prototype in a Buyer Account:
Keep the two checks separate: a fixture test proves local code handles the expected responses; the live get_status and search calls prove account access. Neither proves that a campaign can launch. Continue with Build an agent to add durable buying steps, or Build a reporting pipeline to read existing data.

​
If the first call fails