Before you start

You need:

An MCP-compatible client that supports Streamable HTTP.
A Colab Commerce API key for the user making the connection.

Treat the API key like a password. Store it only in your MCP client's secure configuration and do not paste it into chat messages or share it with other users.

Connection details

Endpoint	`https://api.colabcommerce.com/mcp`
Transport	Streamable HTTP, stateless mode
Authentication	`X-Api-Key: YOUR_API_KEY`
Content type	`application/json`

No MCP session ID is required. Each request is an independent JSON-RPC 2.0 request and the server returns plain JSON rather than a long-lived event stream.

Quick setup by client

Colab Commerce currently authenticates MCP requests with anX-Api-Key header. Use a client that supports custom headers for remote Streamable HTTP servers.

Gemini CLI

Run the following command, replacingYOUR_API_KEY with your Colab Commerce API key:

Gemini CLI

gemini mcp add \
  --transport http \
  --scope user \
  --header "X-Api-Key: YOUR_API_KEY" \
  colab-commerce \
  https://api.colabcommerce.com/mcp

Start Gemini CLI and run /mcp to confirm that colab-commerce is connected and its tools were discovered.

Claude Code

Add the server at user scope so it is available across your Claude Code projects:

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  --header "X-Api-Key: YOUR_API_KEY" \
  colab-commerce \
  https://api.colabcommerce.com/mcp

Run claude mcp list, or open Claude Code and run /mcp, to verify that the server reports as connected.

ChatGPT

Direct connection is not currently supported. ChatGPT does not accept a customer-provided API key or arbitrary request header for an authenticated remote MCP server. It requires the server to implement the MCP OAuth 2.1 authorization flow.

Colab Commerce currently requiresX-Api-Key, so adding this endpoint in ChatGPT developer mode will fail authentication. ChatGPT support will become available after OAuth is added to the Colab Commerce MCP endpoint.

Configure your client

Open your AI client's MCP server settings.
Add a new remote or Streamable HTTP server.
Enter https://api.colabcommerce.com/mcp as the server URL.
Add the X-Api-Key request header.
Save the configuration and reconnect or restart the client.

Configuration formats differ by client. The equivalent values generally look like this:

Connection values

{
  "name": "Colab Commerce",
  "url": "https://api.colabcommerce.com/mcp",
  "transport": "streamable-http",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  }
}

Use the native Streamable HTTP option when your client provides one. The example is illustrative; preserve the property names required by your specific client.

Verify the connection

After connecting, your client should discover tools such aslist_leads, get_lead,list_products, and list_retailer_locations. You can also verify the endpoint independently with an initialize request:

Initialize

curl https://api.colabcommerce.com/mcp \
  --request POST \
  --header "X-Api-Key: YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "connection-test", "version": "1.0" }
    }
  }'

A successful response identifies the server as cc_api and includes a tools capability.

Available data

The server provides list_* and get_*tools for supported resources, including:

Leads, lead activities, emails, and email templates
Companies, company users, retailers, and retailer users
Products, retailer locations, store types, and location hours
Territories, delivery areas, invoices, and report subscriptions

List tools support limit and offsetpagination. Get tools require the record's UUID asid.

Permissions and safety

Same visibility rules

List tools use the same policy scopes as the application; get tools apply the same record-level view policy.

One user per key

Results are rendered for the user authenticated by the API key. Do not reuse one person's key for another person.

The MCP surface has no write tools. It cannot create, edit, or delete records in Colab Commerce.

Troubleshooting

Response	What to check
`401 Unauthorized`	Confirm the `X-Api-Key` header is present and the key is valid.
`400 Bad Request`	Send one JSON-RPC object, not a batch, and use a supported protocol version.
`406` or `415`	Set both `Accept` and `Content-Type` to `application/json`.
`result.isError: true`	The record may not exist or the authenticated user may not have permission to view it.

A tool-level authorization or not-found error still returns an HTTP 200 response. Read result.isError and the message in result.content[0].text.