> ## 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.

# Built for Agents

> AI-first advertising API designed for seamless agent integration via MCP and REST API

The Interchange API is built from the ground up for AI agents. Both humans and agents share the same surface: a REST API and a generic MCP wrapper that exposes the *entire* surface through three tools — no per-domain tool sprawl, no SDK, no glue code.

## Why agent-first

<CardGroup cols={2}>
  <Card title="Same surface for humans and agents" icon="layer-group">
    REST and MCP expose an identical featureset against the same OpenAPI — no
    parallel "AI surface" to drift out of sync. See
    [Philosophy](/v2/concepts/philosophy) for the SESOFI pattern (Single
    Endpoint, Single Object, Full Intent) that keeps composite intents legible.
  </Card>

  <Card title="Generic MCP wrapper" icon="wand-magic-sparkles">
    Three tools (`health`, `ask_about_capability`, `api_call`) cover every
    endpoint. Adding a new REST endpoint instantly makes it agent-callable — no
    new MCP tool to write, register, or deploy.
  </Card>

  <Card title="Declarative tool surface" icon="book">
    A single [`skill.md`](/v2/skill) URL teaches an agent the entire API.
    `ask_about_capability` queries it on demand, so agents discover endpoints
    instead of memorizing them.
  </Card>

  <Card title="Role-aware" icon="user-tag">
    Buyer and storefront roles each get their own skill file and OpenAPI spec,
    so agents see only the surface relevant to the caller.
  </Card>
</CardGroup>

## Supported AI agents

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

Per-agent setup details are below; the [Quickstart](/v2/quickstart) is a one-page index that links here.

## Connection Methods

### REST API

Standard HTTP REST API for traditional integrations:

| Environment | Buyer Base URL                            | Storefront Base URL                            |
| ----------- | ----------------------------------------- | ---------------------------------------------- |
| Production  | `https://api.interchange.io/api/v2/buyer` | `https://api.interchange.io/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.interchange.io/mcp/buyer` | `https://api.interchange.io/mcp/storefront` | `https://interchange.io`       |

<Info>
  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](/v2/authentication#versioning) for when to use each.
</Info>

### Available MCP Tools

Each MCP endpoint exposes three core tools that cover the entire API surface:

| Tool                   | Purpose                                                               |
| ---------------------- | --------------------------------------------------------------------- |
| `health`               | Check API health and verify connectivity                              |
| `ask_about_capability` | Query the skill documentation to discover endpoints and their schemas |
| `api_call`             | Make authenticated REST API calls to any endpoint                     |

**Workflow:** an agent first uses `ask_about_capability` to learn what endpoints exist, then uses `api_call` to execute them.

### Automating storefront setup

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

```
https://api.interchange.io/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 Interchange.

For Codex, register the HTTP connector and complete its OAuth login:

```bash theme={null}
codex mcp add interchange-storefront --url https://api.interchange.io/mcp/storefront
codex mcp login interchange-storefront
```

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://api.interchange.io/storefront/{platformId}/mcp`. A hosted storefront exposes that endpoint when
it is configured to advertise as an agent. An external buyer agent authenticates
with entitled Interchange buyer credentials; there is no separate seller-side
connection handshake. Submitted media buys follow the storefront's media-buy
approval mode and acceptance policy, including any configured per-buyer
auto-approval. See [Approvals](/v2/storefront/approvals/overview).

Both endpoints also expose a conversational assistant tool when it is enabled for your account:

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

<Note>
  `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 Interchange support to enable it. Use `ask_murph` for
  guidance and support, and the three core tools (`api_call` et al.) for actual
  reads and mutations.
</Note>

## Connecting AI Agents

### Claude Connector (Claude.ai Team / Enterprise)

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

**Admin Setup (one-time):**

1. Go to [claude.ai](https://claude.ai) → **Admin Settings** → **Integrations** → **MCP Connectors**
2. Click **Add Connector**
3. Enter the MCP endpoint URL: `https://api.interchange.io/mcp/buyer`
4. Name it (e.g., "Interchange API")
5. Save the connector — it is now available to all members in your organization

**User Setup:**

1. Go to [claude.ai](https://claude.ai) → **Settings** → **Integrations** → **MCP Connectors**
2. Find the Scope3 connector and click **Connect**
3. Log in with your Scope3 credentials when prompted (OAuth)
4. Start chatting! Ask Claude: *"List my advertisers"* or *"Create a performance campaign"*

<Tip>
  Once connected via the connector, it works in both Claude.ai (browser) and
  Claude Desktop. No separate configuration needed.
</Tip>

### 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`

```json theme={null}
{
  "mcpServers": {
    "scope3-buyer": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.interchange.io/mcp/buyer"]
    }
  }
}
```

Restart Claude Desktop. The first call opens a browser for you to sign in to Interchange — `mcp-remote` caches the OAuth token afterward.

If you need to use an API key instead (CI, headless environments), pass it as a header:

```json theme={null}
{
  "mcpServers": {
    "scope3-buyer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.interchange.io/mcp/buyer",
        "--header",
        "Authorization: Bearer scope3_your_api_key_here"
      ]
    }
  }
}
```

### Claude Code (CLI)

OAuth (recommended — no key to manage):

```bash theme={null}
claude mcp add --transport http scope3-buyer https://api.interchange.io/mcp/buyer
claude
```

The first call to the server opens a browser to sign in to Interchange. 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.

```bash theme={null}
claude mcp add --transport http scope3-buyer https://api.interchange.io/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 **Murph** directly through the same server — no extra setup. Just ask a question in plain English and Claude Code will call the `ask_murph` tool:

```text theme={null}
Ask Murph why my campaign is still in PENDING
```

```text theme={null}
Ask Murph how to register credentials for a sales agent
```

Murph 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

<Warning>
  **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.
</Warning>

<Tabs>
  <Tab title="MCP Connector">
    **Connect ChatGPT to Scope3 via MCP:**

    1. Go to ChatGPT → **Settings** → **MCP Connectors**
    2. Click **Add Connector**
    3. Enter MCP Server URL: `https://api.interchange.io/mcp/buyer`
    4. Select **OAuth** as the authentication method
    5. Complete the Scope3 login flow when prompted
    6. 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
    7. Test with: *"Use ask\_about\_capability to learn how to list advertisers"*
  </Tab>

  <Tab title="Custom GPT">
    **Create a Custom GPT with OAuth:**

    1. Go to [ChatGPT](https://chat.openai.com) → **My GPTs** → **Create a GPT**
    2. Go to **Configure** → **Actions** → **Create new action**
    3. Import the OpenAPI spec:
       * Click **Import from URL**
       * Enter: `https://api.interchange.io/api/v2/buyer/openapi.yaml`
    4. 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.interchange.io/authorize`
       * **Token URL**: `https://api.interchange.io/auth/token`
       * **Scope**: `openid profile email`
    5. Save and test with: *"List all my advertisers"*
  </Tab>
</Tabs>

### Custom browser agents

If your agent runs in a browser you control, configure two separate allowlists. They solve different problems and the values are intentionally different:

| Setting            | What to register                                                                            | Why                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| OAuth redirect URI | The full callback URL, including path, for example `https://mcp.example.com/oauth/callback` | OAuth sends the user back here after login. The callback must match exactly.                                               |
| Browser origin     | The exact origin only, for example `https://mcp.example.com`                                | CORS allows browser calls from this origin to MCP/OAuth endpoints. Do not include paths, queries, fragments, or wildcards. |

#### 1. Register the OAuth redirect URI

Register OAuth redirect URIs with dynamic client registration:

```bash theme={null}
curl -X POST https://api.interchange.io/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.
* 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.
* Registering a redirect URI does not by itself authorize a browser agent for an account. For self-serve clients, Interchange issues an authorization code only when the redirect origin has also been approved for the authenticated account.

#### 2. Add the browser origin for CORS

<Note>
  If your custom agent shows *"An account admin must add this browser origin
  before authorizing this MCP client,"* an account admin needs to register
  that origin here first.
</Note>

Account admins can add, view, and remove browser origins from **Interchange →
API Keys → Browser origins**, or manage them programmatically.

Through the shared v2 API:

```bash theme={null}
curl -X POST https://api.interchange.io/api/v2/browser-origins \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://mcp.example.com",
    "label": "Example Agent"
  }'
```

You can also manage these origins through MCP by asking an authenticated agent to call `list_browser_origins`, `create_browser_origin`, or `delete_browser_origin`. Only account admins can list, create, or delete origins.

Browser origin rules:

* Register only the origin: `scheme://host[:port]`.
* Origins must use `https://`.
* Do not include paths, query strings, fragments, or wildcards.
* Register each environment separately, for example production and staging agent hosts.

#### Security posture

Account-managed browser origins are exact-match and only apply to these browser MCP/OAuth paths: `/authorize`, `/auth/register`, `/auth/token`, `/auth/mcp/authorize`, `/.well-known/*`, `/mcp`, and `/mcp/*`. They do **not** open the full REST API to that origin.

Dynamic client registration is public so MCP clients can discover and register themselves, but account access is still gated by login, PKCE, exact redirect URI matching, and the account-approved browser origin check.

Account-managed origins also do **not** receive credentialed cookie CORS. Interchange returns `Access-Control-Allow-Origin` for allowed MCP/OAuth browser calls, but it does not return `Access-Control-Allow-Credentials` for account-managed origins. Browser agents should use OAuth access tokens or explicit bearer tokens, not Interchange UI cookies. First-party Interchange UI origins continue to use credentialed CORS.

If a browser request is blocked:

1. Confirm the OAuth redirect URI is the full callback URL and was registered through `/auth/register`.
2. Confirm the browser origin is only the origin and was added by an account admin.
3. Confirm the request is going to one of the supported browser MCP/OAuth paths, not an arbitrary REST endpoint.
4. Confirm the browser request does not require cookies or `credentials: "include"`.

### Cursor

**Configure Cursor with the Scope3 MCP server:**

1. Open Cursor Settings → **MCP** tab
2. Add a new MCP server:
   * **Name**: `scope3`
   * **URL**: `https://api.interchange.io/mcp/buyer`
   * **Headers**: `Authorization: Bearer your-api-key`
3. Restart Cursor
4. In chat, ask: *"Use Scope3 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 Murph.** "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. Murph 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 Murph or the published documentation, or read live state
via `open_property_roster` — see [Identity
documents](/v2/concepts/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](/v2/authentication) for full details.

## Notifications

The API surfaces unread notifications inline in `ask_about_capability` responses, so agents can proactively flag campaign or creative issues to users. See the [Notifications guide](/v2/guides/notifications) for setup and the REST endpoints.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="/v2/quickstart" icon="rocket">
    Connect Claude, ChatGPT, Cursor, or a custom agent in minutes.
  </Card>

  <Card title="Buyer Onboarding" href="/v2/setup/buyer-onboarding" icon="user-plus">
    The end-to-end campaign-launch journey for buyer integrations.
  </Card>

  <Card title="Skill" href="/v2/skill" icon="book">
    What `skill.md` is and how agents use it for capability discovery.
  </Card>

  <Card title="Authentication" href="/v2/authentication" icon="key">
    API keys, OAuth, and SSO configuration.
  </Card>
</CardGroup>