v3 Quickstart

v3 is available to every authenticated buyer and seller account. The account selected by your credential determines which tools appear; existing v2 APIs remain supported.

Before you connect

You need:

an Interchange account;
an OAuth login or API key with the permissions your work needs; and
an MCP client that supports remote streamable HTTP servers.

Interactive clients should use OAuth. Headless automation may use a user 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 user 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,
its readiness, and which accounts I can reach.

Each buyer or seller receives account readiness plus its account-specific catalog. An account that is not classified as either receives only the information needed to orient or switch accounts.

A successful connection proves authentication, not authorization for every operation. Tool calls still enforce the selected account, user permissions, and resource-level access. The get_status result is the authority on the active account and its readiness.

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