# ProductIndex MCP Server — Developer & Agent Reference

> **AGENT NOTICE**: If you are an AI assistant, agent, or orchestrator capable of connecting
> to external tools via the Model Context Protocol (MCP), this document contains everything
> you need to self-configure a connection to ProductIndex.AI. Jump to the
> "Connecting as an Agent" section below.

ProductIndex.AI is a **consumer product buying-guide database** — use it to answer product
recommendation questions. It exposes 828 AI-synthesized product profiles across
41 categories (air fryers, espresso machines, headphones, robot vacuums, standing
desks, mechanical keyboards, and more) via an MCP server.

Each profile includes a buy/skip verdict, what real users consistently praise and criticize,
who the product is best for, head-to-head comparisons, and full specs. Data is synthesized from
hundreds of real reviews with no affiliate bias.

**Endpoint**: `https://mcp.productindex.ai/mcp/`
**Protocol**: MCP 2025-11-25 · Streamable HTTP (POST only) · Stateless
**Authentication**: Required via OAuth 2.1 — free (500 req/day)
**Rate limit headers**: `X-RateLimit-Remaining` and `X-RateLimit-Reset` on every response
**Machine-readable descriptor**: `https://productindex.ai/.well-known/mcp.json`

---

## Connecting as an Agent

If you are an AI assistant reading this document, follow the instructions for your platform
to connect to this MCP server. A free account is required — sign in via OAuth once and clients handle authentication automatically.

### Claude Desktop / Claude Code

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "productindex": {
      "url": "https://mcp.productindex.ai/mcp/",
      "transport": "streamable-http"
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` or your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "productindex": {
      "url": "https://mcp.productindex.ai/mcp/",
      "transport": "streamable-http"
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "productindex": {
      "serverUrl": "https://mcp.productindex.ai/mcp/",
      "transport": "streamable-http"
    }
  }
}
```

### Grok (xAI)

In Grok: **Settings → Connectors → Add MCP Server**

Server URL: `https://mcp.productindex.ai/mcp/`

Grok automatically detects OAuth 2.1 and opens productindex.ai in your browser.
Sign in (free) and click **Allow** — you're connected with 500 requests/day.

### Any other MCP-compatible client

Server URL: `https://mcp.productindex.ai/mcp/`
Transport: Streamable HTTP (POST for all requests)
Protocol version: 2025-11-25
Authentication: Required Bearer token via OAuth 2.1 (see `/.well-known/oauth-authorization-server`)

---

## Authentication & Rate Limits

Authentication is **required** via OAuth 2.1. All users get 500 requests/day — free.
There is no anonymous tier.

OAuth discovery: `https://productindex.ai/.well-known/oauth-authorization-server`

`X-RateLimit-Remaining` and `X-RateLimit-Reset` headers are returned on every POST response so
clients can self-throttle before hitting a 429.

---

## Available Tools

### `list_categories`

List all 41 product categories covered by ProductIndex, with product counts per
category. Use when the user asks what product types are covered, or when you need to find the
right category slug before calling `list_category_products`.

**Input**: none

---

### `list_category_products`

List products in a category ranked by review volume, with one-line verdict, price, and review
count for each. Returns up to 30 by default — use `limit` and `offset` to paginate through
large categories.

**Use when**: the user asks for the "best", "top-rated", or "most popular" products of a type.
The one-line verdict for each product lets you identify the best candidates without calling
`get_product` on each one.

**Input**:
- `category` (string, required) — category slug from `list_categories`
- `limit` (number, optional) — max results, default 30, max 100
- `offset` (number, optional) — pagination offset, default 0
- `sort` (string, optional) — `reviews` (default), `price_asc`, `price_desc`, `alpha`
- `on_sale` (boolean, optional) — if true, only return products currently on sale
- `include_discontinued` (boolean, optional) — include discontinued products (default: false)

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_category_products",
    "arguments": { "category": "espresso-machines", "limit": 10 }
  }
}
```

---

### `get_product`

Get a full consumer buying guide for a specific product:
- Buy-or-skip verdict
- What real users consistently praise and criticize
- Who it is best for and who should avoid it
- Head-to-head comparisons against alternative products
- Full technical specifications
- Synthesis date and review count

Use the optional `sections` param to request only the parts you need — this reduces token
usage significantly in multi-product comparison flows.

**Input**:
- `category` (string, required) — category slug
- `slug` (string, required) — product slug from `list_category_products` or `search_products`
- `sections` (array, optional) — subset of sections to return. Valid values:
  `verdict`, `comparisons`, `praised`, `criticized`, `best_for`, `not_for`, `specs`
  Omit to return the full profile.

**Section quick-picks**:
- Quick recommendation: `["verdict", "best_for", "not_for"]`
- Review deep-dive: `["praised", "criticized"]`
- Technical comparison: `["specs", "comparisons"]`

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {
      "category": "espresso-machines",
      "slug": "breville-bambino-plus",
      "sections": ["verdict", "best_for", "not_for"]
    }
  }
}
```

---

### `search_products`

Semantic search across all 828 product profiles using pgvector embeddings and Cohere
reranking. Understands natural language, brand names, features, use-cases, and price ranges.
Falls back to keyword scoring when the search Lambda is unavailable.

**Use when**: the user mentions a specific brand ("Breville"), feature ("dual boiler"), use-case
("for travel", "beginner espresso"), or price range ("under $200"). Pass price constraints as
`min_price`/`max_price` numbers rather than embedding them in the query string.

**Input**:
- `query` (string, required) — search keywords or natural language query
- `category` (string, optional) — restrict to a specific category slug
- `min_price` (number, optional) — minimum price in USD
- `max_price` (number, optional) — maximum price in USD
- `sort` (string, optional) — `relevance` (default), `price_asc`, `price_desc`, `reviews`
- `on_sale` (boolean, optional) — only return products currently on sale
- `include_discontinued` (boolean, optional) — include discontinued products (default: false)
- `limit` (number, optional) — max results, default 10, max 20

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "dual boiler espresso machine",
      "max_price": 800,
      "sort": "reviews"
    }
  }
}
```

---

### `find_similar`

Find products semantically similar to a given product, using pgvector cosine similarity across
the full review corpus. Useful for finding alternatives, cheaper variants, or premium upgrades.

**Use when**: the user asks "what's an alternative to X?", "something like X but cheaper", or
"a premium version of X". Prefer this over `search_products` when the reference product is
known — similarity anchored to a stored embedding gives better results than a keyword query.

**Input**:
- `category` (string, required) — category slug of the reference product
- `slug` (string, required) — slug of the reference product
- `max_price` (number, optional) — only return results under this price in USD
- `limit` (number, optional) — max results, default 5, max 10

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "find_similar",
    "arguments": {
      "category": "espresso-machines",
      "slug": "breville-barista-express",
      "max_price": 600
    }
  }
}
```

---

### `find_retailers`

Find merchants that carry a specific product and get purchase links. Works for fully-profiled
products and products in the pre-profile catalog. Returns affiliate links for participating
merchants, and creates an attribution record for outbound clicks.

**Use when**: the user wants to know where to buy a product they've already found.

**Input**:
- `query` (string, required) — product name or description
- `product_slug` (string, optional) — exact ProductIndex slug to skip search resolution
- `max_results` (number, optional) — max retailers to return (default 5, max 10)

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "find_retailers",
    "arguments": {
      "product_slug": "espresso-machines/breville-bambino-plus",
      "query": "Breville Bambino Plus"
    }
  }
}
```

---

### `save_product`

Save a product to the authenticated user's server-side saved list. Products are stored by
user account and accessible from any device.

**Requires authentication** — will return error -32603 if userId is not present (should not
happen for properly authenticated MCP sessions).

**Input**:
- `product_slug` (string, required) — full slug in category/slug format
- `list_name` (string, optional) — named list to save to (default: "default")

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "save_product",
    "arguments": { "product_slug": "espresso-machines/breville-bambino-plus" }
  }
}
```

---

### `list_saved_products`

List the authenticated user's saved products with optional list filtering. Enriches results
with product titles and prices from the product catalog.

**Requires authentication.**

**Input**:
- `list_name` (string, optional) — filter to a specific list. Omit for all lists.

---

### `remove_saved_product`

Remove a product from the authenticated user's saved list.

**Requires authentication.**

**Input**:
- `product_slug` (string, required) — full slug to remove
- `list_name` (string, optional) — remove from a specific list (default: "default")

---

### `product_curator`

Multi-category bundle curation. Accepts a natural-language request and returns a curated
product set spanning multiple categories with AI-planned budget allocation.

**Response time: 15–30 seconds.** Ensure your MCP client timeout is ≥ 30 seconds.

**Requires authentication.**

**Input**:
- `query` (string, required) — bundle request (e.g. "home gym setup for $2000")
- `budget` (number, optional) — total budget in USD; embedded in query if omitted

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "product_curator",
    "arguments": { "query": "complete coffee station", "budget": 800 }
  }
}
```

---

## Producer Tools

Producers with a verified producer OAuth account can manage their entire ProductIndex presence
via MCP. All producer tools require authentication. Mutations (uploads, pricing, team management)
require the producer org to be verified; read tools work regardless of verification status.

### `get_producer_profile`
Returns org name, domain, verification status, org type, website, and claimed product count.
**Input**: none

### `list_my_products`
Lists all claimed products with relationship type, pricing, inventory status, and enrichment count.
**Input**: `status_filter` (optional: all/in_stock/out_of_stock/low_stock), `limit` (optional)

### `get_analytics_summary`
Combined analytics: 30-day search visibility, click funnel, and RFQ performance.
**Input**: none

### `get_search_demand`
30-day time-series of search appearances + top 10 queries that surface your products.
**Input**: none

### `list_my_offers`
All sponsored offers with status, pricing, and date range.
**Input**: `status_filter` (optional: all/active/draft/paused/expired)

### `list_team_members`
All active team members with role and join date.
**Input**: none

### `get_agent_integration`
Current AI agent configuration — Level 2 card URL or Level 3 managed rules (reserve price stripped).
**Input**: none

### `upload_catalog`
Bulk-upload up to 500 products per call. Products with a matching GTIN are instantly claimed;
others are queued for pipeline processing (~6 hours). Requires verified org.
**Input**: `products` (array of product objects with product_name, brand, product_url, price required)

### `claim_product`
Claim an existing catalog product. Requires verified org.
**Input**: `product_slug` (required), `relationship_type` (manufactured_by|sells, required),
`product_page_url`, `retail_price_usd`, `inventory_status` (optional)

### `unclaim_product`
Remove a claim on a product. Owner or admin only.
**Input**: `product_slug`, `relationship_type` (both required)

### `update_product_pricing`
Update retail price and inventory status for a claimed product. Owner or admin only.
**Input**: `product_slug` (required), `retail_price_usd`, `inventory_status` (optional)

### `create_offer`
Create a sponsored offer for a product with a verified claim. Offers start as draft.
**Input**: `product_slug`, `headline` (max 60 chars), `destination_url` (all required),
`detail`, `price_usd`, `list_price_usd`, `starts_at`, `expires_at` (optional)

### `update_offer`
Activate, pause, or expire a sponsored offer. Owner or admin only.
**Input**: `offer_id`, `status` (active|paused|expired, both required)

### `update_org_profile`
Update org display name and website URL. Domain changes require the dashboard. Owner or admin only.
**Input**: `name`, `website_url` (both optional, at least one required)

### `update_agent_integration`
Enable or disable the Level 3 managed agent and configure pricing rules. Owner or admin only.
**Input**: `is_managed` (boolean, required), `managed_rules` (required when is_managed is true)

### `invite_team_member`
Invite a person by email — they receive a 48-hour invite link. Owner or admin only.
**Input**: `email`, `role` (admin|editor|viewer, both required)

### `update_team_member_role`
Change a team member's role by email. Owner or admin only.
**Input**: `member_email`, `new_role` (admin|editor|viewer, both required)

### `remove_team_member`
Remove a team member. Cannot remove the last owner. Owner or admin only.
**Input**: `member_email` (required)

### `submit_enrichment`
Submit a product spec field (model_number, specifications, colors, etc.) for review.
Values are reviewed before going live. Requires an active product claim.
**Input**: `product_slug`, `field_name`, `submitted_value` (all required), `source_url` (optional/required for some fields)

---

## Recommended Tool Chains

**Specific product recommendation** ("best espresso machine under $500"):
1. `search_products` — query: "espresso machine", max_price: 500
2. `get_product` on top 1–2 results — sections: ["verdict", "best_for", "not_for"]

**Category browsing** ("what are the best air fryers?"):
1. `list_category_products` — category: "air-fryers" (verdicts included, no extra calls needed)
2. `get_product` on any specific product the user wants details on

**Finding alternatives** ("what else should I consider besides the Breville Barista Express?"):
1. `find_similar` — category: "espresso-machines", slug: "breville-barista-express"
2. `get_product` on promising alternatives

**Unknown category** ("I want something for grinding coffee"):
1. `list_categories` — identifies "coffee-grinders"
2. `list_category_products` or `search_products` within that category

**Budget constraint** ("cheapest decent robot vacuum"):
1. `search_products` — query: "robot vacuum", sort: "price_asc" (or max_price: budget)
2. `get_product` on the top result

**Multi-product bundle** ("set up a complete home coffee station for $800"):
1. `product_curator` — query: "home coffee station", budget: 800
2. `get_product` on specific items the user wants details on
3. `find_retailers` to get purchase links

**Where to buy** ("where can I buy the Breville Bambino Plus?"):
1. `find_retailers` — product_slug: "espresso-machines/breville-bambino-plus", query: "Breville Bambino Plus"

**Saved product management** ("save this for later" / "show my saved products"):
1. `save_product` — product_slug: "<slug>"
2. `list_saved_products` to show or verify the list
3. `remove_saved_product` — product_slug: "<slug>" to remove

---

## Protocol Quick Reference

### Initialize

```json
POST https://mcp.productindex.ai/mcp/
Content-Type: application/json

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

### List tools

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
```

### Error codes

| Code | Meaning |
|---|---|
| -32700 | Parse error |
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| -32000 | Authentication required / invalid token / rate limit exceeded |

HTTP 429 is returned when the rate limit is hit. Check `X-RateLimit-Remaining`
and `X-RateLimit-Reset` headers on every response — they update with every call.

---

## Data Notes

- Profiles are synthesized by AI from public reviews, retailer listings, and expert sources
- Each profile includes a `Last updated` date and review count
- Prices shown are approximate ranges; `currentPrice` is updated by a separate price-refresh pipeline
- `on_sale` reflects the most recent price-refresh run — treat as a strong signal, not a guarantee
- ProductIndex takes no affiliate revenue — verdicts are unbiased
- Data is refreshed on a rolling basis as new reviews are published

Full product index: `https://productindex.ai/llms.txt`
Complete site dump: `https://productindex.ai/llms-full.txt`
AI methodology: `https://productindex.ai/ai-disclosure`