> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect in five minutes

> Connect a coding agent to Apostra, complete OAuth, and verify the account with a read-only call.

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. Connect MCP directly

Add Apostra's remote Streamable HTTP MCP connection to your coding agent, then
complete browser sign-in and consent. The connection uses your existing account
permissions. Apostra's API and sign-in URLs currently use `interchange.io`.

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
    for client configuration and OAuth controls.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Other MCP clients">
    Add a remote Streamable HTTP server with this URL:

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

    Choose OAuth and complete browser sign-in. See
    [MCP client setup](/v3/client-setup) for the existing host guides.
  </Tab>
</Tabs>

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

<Note>
  The native `apostra-developer` plugin, Build with Apostra skill, and TypeScript
  and Python starters are pending publication and fresh-client verification.
  Installation instructions and starter links will be added after those checks
  pass. Use the direct MCP connection above to get started today.
</Note>

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](/v3/authentication) for supported credential types.

## 2. Prove account access

Ask your agent:

```text theme={null}
Use the 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](/v3/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:

<Tabs>
  <Tab title="Buyer account">
    ```json theme={null}
    { "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.
  </Tab>

  <Tab title="Seller account">
    ```json theme={null}
    { "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.
  </Tab>
</Tabs>

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:

```text theme={null}
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](/v3/build-an-agent) to add durable buying steps,
or [Build a reporting pipeline](/v3/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.        |