MCP

Every other guide on this site documents a backend-to-backend integration: a service you write, running unattended, calling this API on its own schedule. This guide is different. It points an AI agent - Claude Code, Gemini CLI, an agent framework you operate, or anything else that speaks MCP - at the same API, so a person can ask for the work in natural language instead of writing a client for it. Nothing new is granted by doing this: an agent authenticates through the same authorization model every other credential on this site uses, and resolves to the identical partner identity, granted sites and scopes. See Authentication for that model in full; this guide covers only what is specific to driving it from an agent.

The endpoint

MCP is served at:

https://api.partners.collaterate.com/v1/mcp

on the bearer host - the same host client_credentials tokens are minted from and sent to for every other call on this site, and the host both client-authentication paths this guide covers (interactive sign-in and a bearer token) use. That is the endpoint to configure for either one. The same path also answers on the mTLS host, mtls.partners.collaterate.com/v1/mcp, for a client certificate credential - if you already authenticate this API’s other endpoints with mTLS, present the same certificate here rather than switching credential kinds just for MCP.

Every URL in this guide is the production one. For the sandbox, substitute collaterail.com for collaterate.com throughout - see Environments.

Sign in interactively

For a person at a terminal, this is the path to reach for first. The server implements OAuth Dynamic Client Registration: it advertises its own configuration at /.well-known/oauth-authorization-server, and a conformant MCP client reads authorization_endpoint, token_endpoint and registration_endpoint from that document and registers itself automatically, without a client id or secret issued ahead of time. For most clients that means the entire configuration is the one URL above - nothing to paste in, no credential to request from Partner Integrations, no secret to rotate later.

Point a client at the endpoint - the exact steps differ by client, covered below - and your first tool call opens a browser to sign in with your own Collaterate staff account. Once you have signed in, the client holds a refresh token and silently renews your session for about 24 hours before it needs you to sign in again.

Signing in as yourself grants nothing extra

Interactive sign-in resolves to the same partner identity, the same granted sites and the same capabilities as any other credential your organization holds. It is a different door into one authorization model, not a second set of permissions.

Claude Code

claude mcp add --transport http partner-api https://api.partners.collaterate.com/v1/mcp

Your first tool call opens a browser to sign in.

Claude Desktop

Claude Desktop will not connect to a remote server listed in claude_desktop_config.json — that file is for local servers only. Use a custom connector instead:

1. Settings → Connectors → Add custom connector
2. Paste https://api.partners.collaterate.com/v1/mcp
3. Save, then sign in when prompted

Leave Advanced settings empty. It accepts an OAuth client ID and secret for servers that need one; this server registers your client automatically.

Gemini CLI

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "partner-api": {
      "httpUrl": "https://api.partners.collaterate.com/v1/mcp",
      "oauth": { "enabled": true }
    }
  }
}

Then, at the Gemini CLI prompt, authenticate:

/mcp auth partner-api

The field is httpUrl for a remote server, not url.

Kiro

Add the server to .kiro/settings/mcp.json for one workspace, or ~/.kiro/settings/mcp.json for every workspace:

{
  "mcpServers": {
    "partner-api": {
      "url": "https://api.partners.collaterate.com/v1/mcp"
    }
  }
}

Kiro registers itself and opens a browser on first use. Note the field is url here, where Gemini CLI wants httpUrl.

VS Code and GitHub Copilot

Requires VS Code 1.101 or later. Add the server to .vscode/mcp.json:

{
  "servers": {
    "partner-api": {
      "type": "http",
      "url": "https://api.partners.collaterate.com/v1/mcp"
    }
  }
}

Then click Auth on the CodeLens above the server entry to sign in.

Any other MCP client

Any client that implements the MCP authorization specification - the same discovery-plus-PKCE flow described above - works against this server without needing a named section here. Point it at https://api.partners.collaterate.com/v1/mcp; a conformant client discovers /.well-known/oauth-authorization-server on its own and registers itself, so there is nothing to request from Partner Integrations before it can connect.

The server registers itself as a public OAuth client: its metadata document lists token_endpoint_auth_methods_supported: ["none"], and authorization runs Authorization Code with PKCE rather than a client secret. If your client’s configuration insists on a client secret before it will proceed, configure it as a public client instead - a secret is not something this server issues or expects, and there is none to give it.

Machine access with a bearer token

The path above is for a person signing in. If you are wiring your own agent framework or a headless process to this API instead, use the same machine credential every backend-to-backend integration on this site uses: mint a token with client_credentials exactly as Authentication documents, and send it as a normal Authorization: Bearer header on POST /v1/mcp, the same as on every other path this API serves.

Some clients cannot do interactive sign-in

Copilot in Visual Studio, JetBrains IDEs, Xcode and Eclipse authenticate with a token rather than a browser flow. For those, the bearer token below is the only option, not a fallback.

curl -s -X POST https://api.partners.collaterate.com/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Access tokens expire in about an hour - the same token lifetime as any other bearer credential on this site. A long-running agent needs to mint a fresh token before the old one lapses rather than caching one indefinitely; it is the same refresh-before-you-need-it approach the SDK guide documents for keeping a token current across an npm install.

What tools you get

tools/list returns exactly the tools your credential’s scopes allow, not the server’s full catalog - two people at the same partner, holding different capabilities, can call tools/list on this same server and see different tools come back. Calling a tool your scopes do not cover returns an error result naming the exact scope that tool needs (for example, partner-api/orders:write), rather than failing with an opaque protocol-level error. This scope-narrowing behavior of tools/list was confirmed against the deployed system.

How the catalog is shaped, and one thing you will look for and not find

Tool names are snake_case, and each one answers a question rather than naming an endpoint. That distinction is deliberate: an agent’s useful unit is a question, so the catalog is written by hand rather than derived from the URL structure of the REST API.

The list_* tools take filters, and there are no nested equivalents. The REST API lets you address a site-scoped collection two ways – GET /v1/sites/222/users and GET /v1/users?siteId=222 are the same request (see Tenancy and grants). Only the filter form becomes a tool. So you will not find list_site_users, and that is not an omission:

• list_users(siteId=222) already answers everything list_site_users(222) could.
• list_users() with no siteId answers a question the nested form cannot – “every user I can see, across all my sites” – which matters when you are reconciling hundreds of thousands of rows across hundreds of sites rather than looking at one site.
• Two tools that answer the same question measurably degrade an agent’s tool selection.

get_* survives beside list_* for the same practical reason: get_user(999) answers 404 user_not_found, while list_users(userId=999) would be an empty array, and an agent reads an empty array as “no permission” as readily as “no such user”. The distinction is worth a separate tool.

Writes name their target in the body. There is no nested create_*; create_order takes the site it is for as a field.

Tool	Required scope	What it does
get_credit_account	credit:read	Get one credit account.
list_credit_account_adjustments	credit:read	List one credit account’s debits and credits.
list_credit_accounts	credit:read	List the credit accounts on your granted sites.
get_division	divisions:read	Get one division.
list_divisions	divisions:read	List the divisions on your granted sites.
create_division	divisions:write	Create a division.
patch_division	divisions:write	Update a division - WARNING, this erases the division’s stored address.
get_order	orders:read	Get a single order by number.
get_order_item_proof	orders:read	Get the print proof for one line.
list_order_item_denial_reasons	orders:read	List the reasons this line’s proof may be declined with.
list_order_items	orders:read	List an order’s line items.
list_order_shipments	orders:read	List an order’s shipments, with tracking.
list_orders	orders:read	List orders across your granted sites.
approve_order_item_proof	orders:write	Approve the print proof for one line.
create_order	orders:write	Submit an order.
decline_order_item_proof	orders:write	Decline the print proof for one line.
get_submission	orders:write	Poll a submission’s status.
list_submissions	orders:write	List your order submissions.
get_product	products:read	Get one product, with every variant.
get_product_template	products:read	Get the Chili template and variable definitions for a templated product.
list_product_images	products:read	List a product’s images and their metadata.
list_products	products:read	List every active product on your granted sites.
list_segments	products:read	List your granted sites’ customer segments.
quote_product	products:read	Get a price quote for a product at a given quantity.
quote_shipping	products:read	Get shipping prices for a destination and weight.
patch_product	products:write	Change a product’s content, visibility and stock bounds.
patch_product_image	products:write	Change an image’s alt text, order, or which image is primary.
patch_product_variant	products:write	Change one variant’s attribute choices, location or weight.
replace_product_segments	products:write	Replace which segments a product is shown to.
get_site	sites:read	Get one site.
list_sites	sites:read	List your granted sites.
get_user	users:read	Get one user, with their segment memberships.
list_user_addresses	users:read	List a user’s saved addresses.
list_users	users:read	List the storefront users on your granted sites.
patch_user	users:write	Change a user’s profile, division, or active state.
replace_user_segments	users:write	Replace a user’s segment memberships.

When it does not work

Three failures cover nearly everything you will actually hit.

A 401 before any tool call succeeds. The credential never resolved to a partner. If you are using a bearer token or interactive sign-in, confirm you are calling the bearer host; if you are using a client certificate, confirm you are calling the mTLS host with that certificate presented. Either way, also confirm your partner record has at least one granted site. See when authentication fails for the full list of what produces one.

A tool call returns an error naming a scope. The credential resolved fine, but the named scope is not in your granted capabilities. This is not something you can self-serve - ask Partner Integrations to grant it.

A session that worked yesterday now prompts you to sign in again. Not a fault: the interactive credential’s refresh window (about 24 hours) lapsed. Sign in again the same way you did the first time.

Next

• Authentication - the full authorization model this guide only summarizes: how scopes resolve, and every condition that produces a 401.
• SDK (TypeScript) - the same Cognito credential the bearer path above uses, wrapped in a typed client, for integrating from Node or TypeScript instead of an MCP client.
• Getting started - the raw-fetch walkthrough behind every tool this server exposes, if you want to see a call at the wire level.