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

# v3 Quickstart

> Connect an MCP client to the enrolled v3 preview and make the first calls.

<Note>
  v3 is an enrolled preview. If Interchange has not enrolled the account, the
  connection intentionally exposes navigation only. Use the stable v2 API for
  production integrations that are not part of the preview.
</Note>

## Before you connect

You need:

* an Interchange account;
* an OAuth login or organisation API key with the permissions your work needs;
* confirmation that at least one account you can reach is enrolled in v3; and
* an MCP client that supports remote streamable HTTP servers.

Interactive clients should use OAuth. Headless automation may use an
organisation API key stored in an environment variable or secret manager. See
[Authentication](/v2/authentication) for credential types and permissions.

## Add the endpoint

The v3 endpoint is:

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

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add interchange-v3 --url https://api.interchange.io/mcp/v3
    codex mcp login interchange-v3
    ```

    For headless automation, use Codex's bearer-token environment-variable
    option instead of placing a key in shell history.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http interchange-v3 \
      https://api.interchange.io/mcp/v3
    claude
    ```

    The first use opens the Interchange OAuth flow. For non-interactive use,
    follow Claude Code's HTTP-header configuration and read the key from your
    secret-management environment.
  </Tab>

  <Tab title="Claude Desktop">
    Add a remote MCP server to the Claude Desktop configuration:

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

    Restart Claude Desktop. The first call opens the OAuth sign-in flow.
  </Tab>

  <Tab title="Other MCP clients">
    Add a remote streamable HTTP server with the v3 URL. Use OAuth when the
    client supports it, or send the organisation API key as:

    ```text theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```
  </Tab>
</Tabs>

The broader [Built for Agents](/v2/setup/built-for-agents#connecting-ai-agents)
guide covers ChatGPT, Cursor, credential handling, and client-specific setup.
Use the v3 URL in place of the stable buyer or seller URL.

## Verify the connection

Ask the client:

```text theme={null}
Call get_status and tell me which Interchange account I am in,
whether it is enrolled in v3, and which accounts I can reach.
```

An enrolled buyer or seller receives account readiness plus its account-specific
catalog. An account outside the cohort receives `state: "not_enrolled"` and only
the information needed to orient or switch accounts.

<Warning>
  Do not treat a successful MCP connection as proof of enrollment. Navigation
  tools deliberately work outside the cohort. The `get_status` result is the
  authority.
</Warning>

## Switch accounts

Use an `accountId` returned by `get_status`:

```json theme={null}
{ "accountId": 624 }
```

After `switch_account`, call `get_status` again. v3 emits
`notifications/tools/list_changed`, but clients do not all refresh the same
way; the second status read confirms the active account and its capabilities.

Omit `accountId` only when you intend to return to the credential's home
account:

```json theme={null}
{}
```

## Make a first read

Choose a noun that belongs to the active account:

<Tabs>
  <Tab title="Buyer account">
    ```json theme={null}
    { "kind": "campaign", "limit": 10 }
    ```

    Then read one returned campaign:

    ```json theme={null}
    { "kind": "campaign", "id": "CAMPAIGN_ID" }
    ```
  </Tab>

  <Tab title="Seller account">
    ```json theme={null}
    { "kind": "inventory_source", "limit": 10 }
    ```

    Then read one returned source:

    ```json theme={null}
    { "kind": "inventory_source", "id": "SOURCE_ID" }
    ```
  </Tab>
</Tabs>

Kinds differ by account. Use the current `search` and `get` input schemas from
`tools/list`; do not copy a kind from a different account's stale catalog.

## Safe first-write checklist

Before a write:

1. Read the object and retain its current ID and revision when provided.
2. Use the typed `save_<noun>` tool shown in the current catalog.
3. Send only fields you intend to change.
4. Supply `expectedRevision` when the schema offers it.
5. Reuse an idempotency key only for the same logical attempt.
6. Read the object again and confirm the reported outcome.

Continue with a [buyer workflow](/v2/setup/v3/buyer-workflows), a
[seller workflow](/v2/setup/v3/seller-workflows), or the
[tool catalog](/v2/setup/v3/tool-reference).