v3 Quickstart

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.

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 for credential types and permissions.

Add the endpoint

The v3 endpoint is:

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

Codex
Claude Code
Claude Desktop
Other MCP clients

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.

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.

Add a remote MCP server to the Claude Desktop configuration:

{
  "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.

Add a remote streamable HTTP server with the v3 URL. Use OAuth when the client supports it, or send the organisation API key as:

Authorization: Bearer YOUR_API_KEY

The broader Built for 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:

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.

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.

Switch accounts

Use an accountId returned by get_status:

{ "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:

{}

Make a first read

Choose a noun that belongs to the active account:

Buyer account
Seller account

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

Then read one returned campaign:

{ "kind": "campaign", "id": "CAMPAIGN_ID" }

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

Then read one returned source:

{ "kind": "inventory_source", "id": "SOURCE_ID" }

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:

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

Continue with a buyer workflow, a seller workflow, or the tool catalog.

Start building

Understand v3

Build workflows

Shared reference

Before you connect

Add the endpoint

Verify the connection

Switch accounts

Make a first read

Safe first-write checklist

​Before you connect

​Add the endpoint

​Verify the connection

​Switch accounts

​Make a first read

​Safe first-write checklist

Before you connect

Add the endpoint

Verify the connection

Switch accounts

Make a first read

Safe first-write checklist