For Developers

Six tools over Streamable HTTP (MCP 2025-11-25). All requests are POST to https://mcp.productindex.ai/sse/ with a JSON-RPC 2.0 body. OAuth 2.1 Bearer token required on every request.

MCP Tools

Request / Response Example

Every call is a POST to the same endpoint. Send initialize first, then any tool call.

// 1. Initialize
POST https://mcp.productindex.ai/sse/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}

// 200 OK
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"ProductIndex","version":"1.0.0"}}}

// 2. Tool call
POST https://mcp.productindex.ai/sse/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"espresso machine under $500","limit":5}}}

// 200 OK
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"..."}]}}

Full setup instructions for Grok, Claude Desktop, Cursor, and Windsurf: MCP Server documentation →

Every product and category is available in machine-readable formats for direct RAG ingestion, structured data pipelines, and LLM agents that prefer URL-based retrieval over the MCP server. No authentication required.

ProductIndex publishes a Google Agent-to-Agent (A2A) compatible agent card describing its skills and capabilities in machine-readable JSON. Read automatically by A2A-compatible orchestrators.

If you operate a retailer or manufacturer and want to receive live Request-for-Quote (RFQ) calls from consumer agents via ProductIndex, register your agent endpoint in the Producer Dashboard → Settings → Agent Integration. ProductIndex will fan out to your endpoint when a consumer agent submits an RFQ for a product you carry.

RFQ Request — What Your Agent Receives

ProductIndex calls your registered offer endpoint with a JSON-RPC 2.0 POST request:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "<rfq_session_uuid>",
  "params": {
    "message": {
      "messageId": "<uuid>",
      "role": "user",
      "parts": [{ "kind": "text", "text": "Request for quote: Baratza Encore ESP, qty 1, ship to CA 94103" }],
      "metadata": {
        "skill": "respond-to-rfq",
        "rfq_id": "<rfq_session_uuid>",
        "product_slug": "coffee-grinders/baratza-encore-esp",
        "quantity": 1,
        "delivery_region": "CA-US",
        "deadline_iso": "2026-06-01T12:00:00Z",
        "requestor": "https://productindex.ai/.well-known/agent.json"
      }
    }
  }
}

RFQ Response — What You Must Return

Respond with a JSON object (not JSON-RPC envelope — bare object only) within 4 seconds:

{
  "price_usd": 169.99,
  "list_price_usd": 189.99,
  "in_stock": true,
  "estimated_shipping_days": 3,
  "shipping_cost_usd": 0,
  "offer_id": "<uuid>",
  "offer_expires_at": "2026-06-01T12:00:00Z",
  "claim_url": "https://yourstore.com/cart?offer=<uuid>",
  "terms": "Free returns within 30 days"
}

Offers are ranked by total cost (price_usd + shipping_cost_usd). Out-of-stock offers are demoted regardless of price. Responses that arrive after 4 seconds are dropped.

Authentication

Every RFQ call from ProductIndex carries authentication headers so your server can verify the request is genuine. Choose a scheme, generate your own secret, and register it in the Producer Dashboard → Settings → Agent Integration. ProductIndex encrypts and stores the secret — it is never returned after registration.

Generating a secret

// Node.js — generate a cryptographically random secret
import { randomBytes } from "crypto";
const secret = randomBytes(32).toString("hex"); // 64-char hex string
console.log(secret); // paste this into the dashboard

Go to Producer Dashboard → Settings → Agent Integration, select your auth type, paste your secret, and save. ProductIndex will use it to sign all outbound RFQ calls to your endpoint from that point forward.

HMAC Verification

Signature is HMAC-SHA256(secret, "${timestamp}.${rawBodyString}") — the Unix timestamp in seconds, a literal period, then the raw request body string exactly as received. Reject requests where |now - timestamp| > 300 seconds (5-minute replay window).

// Node.js verification example
import { createHmac, timingSafeEqual } from "crypto";

function verifyProductIndexRequest(secret, req) {
  const timestamp = parseInt(req.headers["x-productindex-timestamp"], 10);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${req.rawBody}`)
    .digest("hex");
  // Use timingSafeEqual to prevent timing attacks
  return timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-productindex-signature"]));
}

Agent Card Requirement

Your agent card (at /.well-known/agent.json on your verified domain) must declare the respond-to-rfq skill. Minimum declaration:

{
  "skills": [{
    "id": "respond-to-rfq",
    "description": "Responds to price quote requests with current pricing, availability, and shipping terms"
  }]
}

ProductIndex fetches and validates this card when you register your agent card URL. The card must be on the same domain as your verified producer organization.

ProductIndex derives your RFQ endpoint from your agent card URL by taking the domain root and appending /message:send. If your card is at https://mystore.com/.well-known/agent.json, ProductIndex will POST RFQ requests to https://mystore.com/message:send. Your server must expose a POST /message:send route at the domain root.

Timeout and Error Handling

Return HTTP 200 with a valid JSON response body within 4 seconds. If you cannot fulfill the RFQ (out of stock, product not carried), return HTTP 200 with {"in_stock": false, "price_usd": 0, "claim_url": "", "offer_expires_at": ""} rather than a non-200 status. Repeated timeouts or errors degrade your integration status and reduce your ranking priority.

Static files formatted for LLM context windows and RAG pipelines, following the llms.txt convention. No authentication required.

Standard .well-known paths for automated discovery by agents and OAuth clients. All public — no authentication required.

ProductIndex supports Client ID Metadata Documents (CIMD) — a stateless alternative to OAuth Dynamic Client Registration (DCR) being standardized in MCP SEP-991 and a companion IETF draft. Instead of pre-registering a client and receiving an opaque client ID, your app hosts a static JSON file at a stable HTTPS URL. That URL is the client ID — no registration step, no database entry on our side.

How it works

Host a JSON file at any stable HTTPS URL on your domain. That URL becomes your client_id. When you send an OAuth authorization request, ProductIndex fetches the document, validates that the client_id field inside it exactly matches the URL it was fetched from, then uses your redirect_uris list to verify the redirect_uri in your request.

{
  "client_id": "https://yourapp.example.com/oauth/client.json",
  "client_name": "Your App Name",
  "client_uri": "https://yourapp.example.com",
  "redirect_uris": [
    "https://yourapp.example.com/oauth/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Then start the OAuth flow using that URL as client_id:

GET https://productindex.ai/oauth/authorize/
  ?client_id=https://yourapp.example.com/oauth/client.json
  &redirect_uri=https://yourapp.example.com/oauth/callback
  &response_type=code
  &code_challenge=<S256 PKCE challenge>
  &code_challenge_method=S256
  &scope=mcp
  &state=<random state>

Requirements

ProductIndex caches valid CIMD documents for 5 minutes and invalid results for 1 minute. Private IP ranges, loopback addresses, and link-local addresses are blocked before fetch (SSRF protection).

Traditional DCR

If your client cannot host a static HTTPS file (e.g., a CLI tool or local app), register via Dynamic Client Registration at POST /api/oauth/register/. DCR issues an opaque UUID as the client_id. CIMD is preferred for web apps and server-side integrations.

Complete flow for obtaining an access token. All clients are public (token_endpoint_auth_method: none) — PKCE is the only security mechanism, no client secret is issued or required.

Step 1 — Generate PKCE pair

// Generate a cryptographically random code_verifier (43–128 URL-safe chars)
const verifier = base64url(crypto.randomBytes(32));

// Derive code_challenge
const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());

Step 2 — Redirect user to authorization endpoint

GET https://productindex.ai/oauth/authorize/
  ?response_type=code
  &client_id=<your-client-id>
  &redirect_uri=<your-registered-redirect-uri>
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &scope=mcp
  &state=<random-csrf-token>

User signs in (or is auto-approved if they previously granted this client). ProductIndex redirects to your redirect_uri with ?code=<auth_code>&state=<state>.

Step 3 — Exchange code for tokens

POST https://productindex.ai/api/oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<auth_code_from_redirect>
&redirect_uri=<same-redirect-uri>
&client_id=<same-client-id>
&code_verifier=<verifier>

// 200 OK
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "<refresh_token>"
}

Step 4 — Call the MCP server

POST https://mcp.productindex.ai/sse/
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Step 5 — Refresh an expired token

POST https://productindex.ai/api/oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<same-client-id>

// 200 OK — new access_token and refresh_token issued; old refresh_token revoked

OAuth 2.1 with PKCE is required for all requests. AI clients like Grok and Claude Desktop handle the sign-in flow automatically — connect once and they manage token refresh.

Remaining quota and reset time are returned on every response as X-RateLimit-Remaining and X-RateLimit-Reset headers.

Questions

For integration questions or to report an issue with the API: hello@productindex.ai