Connect in five minutes

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.

1. Install the Apostra package

The native package installs the Build with Apostra skill and Apostra’s remote MCP connection together. The connection uses your existing account permissions. Apostra’s API and sign-in URLs currently use apostra.com.

Codex
Claude Code
Other MCP clients

codex plugin marketplace add https://github.com/apostra-public/apostra.git
codex plugin add apostra-developer@apostra

Open a Codex session in your project and complete OAuth when prompted.

Enter these commands inside a Claude Code session:

/plugin marketplace add https://github.com/apostra-public/apostra.git
/plugin install apostra-developer@apostra

Complete OAuth when prompted.

Add a remote Streamable HTTP server with this URL:

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

Choose OAuth and complete browser sign-in. See MCP client setup for the existing host guides.

Use an existing connection if it already supplies this endpoint. The coding agent should not ask you to paste credentials into chat.

Interactive OAuth represents you in the coding session. It does not create a runtime identity for finished software. Reuse an existing Apostra Agent when one exists, create one when deployed software needs its own identity and credential, or prototype safely in the available sandbox.

If a coding tool does not support the native package, connect MCP directly:

Codex
Claude Code

codex mcp add apostra --url https://api.interchange.io/mcp/v3
codex mcp login apostra

Complete OAuth in the browser, then open a Codex session in your project. See Codex MCP setup for client configuration and OAuth controls.

claude mcp add --transport http apostra https://api.interchange.io/mcp/v3
claude

Open Claude Code’s MCP controls and complete OAuth in the browser.

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:

Use Apostra connection to call get_status. Tell me the active account,
whether it is a buyer or seller, its readiness blockers, and which accounts
I can reach. Do not create or change anything.

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. If the wrong account is selected, call switch_account with an accountId returned by the status result, then call get_status again. An Organisation or unclassified account may offer navigation without buying or selling tools. See Account access.

3. Make a first read

Ask the agent to inspect tools/list, then call search with the input that matches your active account:

Buyer account
Seller account

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

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.

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

This lists inventory sources available to the selected seller. A new account may return an empty list until a source is configured.

You now have a verified MCP connection and a first account-scoped read. The schema returned by tools/list is the contract for your session; 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:

Build a seller-discovery prototype in this repository using Apostra.
Verify the account with get_status and inspect the current tool schemas.
List sellers and display their returned readiness and connection information.
Keep credentials outside the repository. Add a deterministic fixture test
for a populated result and an empty result. Do not request proposals or
create a campaign yet. Explain how to run it and what the test proves.

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

Result	Next step
Authentication required	Complete OAuth in the MCP client’s connection controls and retry.
Wrong account or missing domain tools	Read reachable accounts, switch to the intended Buyer or Seller Account, and refresh the tool catalog.
Permission denied	Check the credential’s account and resource permissions. Reinstalling instructions does not grant access.
Account or seller readiness blocker	Follow the action returned by `get_status`; a working connection does not complete commercial setup.
Client cannot show an interactive Page	Follow a returned browser link where supplied, or use an MCP Apps-capable host for that operation.

Start building

Build your integration

Workflow recipes

MCP reference

Shared reference

Connect in five minutes

1. Install the Apostra package

2. Prove account access

3. Make a first read

4. Build a small prototype

If the first call fails

​1. Install the Apostra package

​2. Prove account access

​3. Make a first read

​4. Build a small prototype

​If the first call fails

1. Install the Apostra package

2. Prove account access

3. Make a first read

4. Build a small prototype

If the first call fails