Commerce MCP

Calling the server

The commerce MCP speaks the Model Context Protocol over streamable HTTP. Any MCP client works; so does plain curl.

Transport#

POST one JSON-RPC 2.0 message per request to the endpoint, with content-type: application/json.
Send accept: application/json, text/event-stream. Without both, the server answers HTTP 406.
Responses are plain JSON, not event streams. The server is stateless: there is no session ID, and each request stands alone.
Because it is stateless, tools/list and tools/call work without a prior initialize. MCP clients send it anyway, which is fine.
Every response carries X-Request-Id. Quote it when you contact support.

Raw JSON-RPC#

With an API key on /api/mcp. For a directory endpoint, drop the Authorization line.

1. initialize

curl https://app.aiptimise.com/api/mcp \
  -H "Authorization: Bearer $AIPTIMISE_MCP_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}'

Response

{
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "aiptimise-commerce",
      "version": "2.0.0"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

2. tools/list

curl https://app.aiptimise.com/api/mcp \
  -H "Authorization: Bearer $AIPTIMISE_MCP_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

The result lists the tools your scopes allow, each with name, title, description, inputSchema, outputSchema, annotations and securitySchemes. See the tools reference.

3. tools/call

curl https://app.aiptimise.com/api/mcp \
  -H "Authorization: Bearer $AIPTIMISE_MCP_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_store_info","arguments":{"store_id":"edab46c9-76c6-4eb5-92dd-f593ed4bd9ad"}}}'

A successful result has structuredContent (the JSON the output schema describes) and the same JSON as text in content, for clients that only read text. A full response, from get_loyalty_program:

Response

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"store_id\":\"edab46c9-76c6-4eb5-92dd-f593ed4bd9ad\",\"product_id\":\"demo-trekker-45-backpack\",\"program\":{\"name\":\"Trail Rewards\",\"tiers\":[{\"name\":\"Explorer\",\"perks\":[\"Birthday bonus of 50 points\"],\"threshold_points\":0},{\"name\":\"Summit\",\"perks\":[\"Free express shipping\",\"Early access to new gear\"],\"threshold_points\":1000}],\"terms_url\":\"https://demo.aiptimise.com/pages/trail-rewards\",\"description\":\"Earn 1 point per dollar spent. Every 100 points is worth $5 off a future order.\"},\"points\":{\"basis\":\"1 point per $1 spent\",\"program\":\"Trail Rewards\",\"points_earned\":199},\"programs\":[]}"
      }
    ],
    "structuredContent": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-trekker-45-backpack",
      "program": {
        "name": "Trail Rewards",
        "tiers": [
          {
            "name": "Explorer",
            "perks": [
              "Birthday bonus of 50 points"
            ],
            "threshold_points": 0
          },
          {
            "name": "Summit",
            "perks": [
              "Free express shipping",
              "Early access to new gear"
            ],
            "threshold_points": 1000
          }
        ],
        "terms_url": "https://demo.aiptimise.com/pages/trail-rewards",
        "description": "Earn 1 point per dollar spent. Every 100 points is worth $5 off a future order."
      },
      "points": {
        "basis": "1 point per $1 spent",
        "program": "Trail Rewards",
        "points_earned": 199
      },
      "programs": []
    }
  },
  "jsonrpc": "2.0",
  "id": 9
}

Directory apps: ChatGPT and Claude#

These connect without an API key, to a directory endpoint such as https://app.aiptimise.com/api/mcp/p/openai.

ChatGPT (apps / developer mode)

Settings → Apps & Connectors → Create. MCP server URL: the directory endpoint; Authentication: none. ChatGPT does not send API keys.

Claude (custom connector)

Settings → Connectors → Add custom connector, with the directory endpoint as the URL. Claude.ai connectors authenticate with OAuth or not at all, not with API keys.

Anthropic Messages API (MCP connector)#

Anthropic connects to the MCP server for you; pass your key as the authorization token.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  betas: ["mcp-client-2025-11-20"],
  mcp_servers: [
    {
      type: "url",
      url: "https://app.aiptimise.com/api/mcp",
      name: "aiptimise",
      authorization_token: process.env.AIPTIMISE_MCP_KEY,
    },
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "aiptimise" }],
  messages: [
    { role: "user", content: "Find a waterproof hiking jacket under 200 USD" },
  ],
});

OpenAI Responses API (remote MCP tool)#

OpenAI connects to the MCP server for you; pass your key in authorization.

JavaScript

import OpenAI from "openai";

const openai = new OpenAI();

const response = await openai.responses.create({
  model: "<your model>",
  tools: [
    {
      type: "mcp",
      server_label: "aiptimise",
      server_description: "Product search and store information for participating merchants.",
      server_url: "https://app.aiptimise.com/api/mcp",
      authorization: process.env.AIPTIMISE_MCP_KEY,
      require_approval: "never",
    },
  ],
  input: "Find a waterproof hiking jacket under 200 USD",
});

Any MCP client or plain HTTP#

Any client that speaks streamable HTTP and can send a header works (Gemini and agent SDKs, MCP Inspector).

curl https://app.aiptimise.com/api/mcp \
  -H "Authorization: Bearer $AIPTIMISE_MCP_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Request metadata and links#

Clients may send _meta with a call. The service reads ChatGPT's openai/locale, openai/userLocation and openai/session for usage reporting only; the session is stored as a keyed hash. Nothing in _meta grants access.

Link shoppers with the product_url a tool returns, unchanged. It carries the UTM parameters that credit your platform, and checkout always happens on the merchant's site.

API snippets checked against the providers' docs on 2026-09-27.