Commerce Match MCP

Overview

Commerce Match MCP is a resolution-only MCP tool. Give find_product_matches a single product phrase and it returns up to three matching product listings, best pick first - title, image, brand, category, and a product page URL you can link straight to. Every match resolves against the catalog of a merchant you already work with, and the url comes back untagged, so you append your own affiliate tag or link as-is - there is no new affiliate account to sign up for and no ChatAds tag in the response. It’s the inverse of Commerce Signals: Signals finds the product mentions inside a block of text, Match turns one of those phrases into something shoppable. Both tools live on the same server behind the same cak_ access key, so connecting once gives you both.

Amazon US is the catalog live today. The resolution engine is catalog-agnostic, but Amazon US is currently the only catalog wired up, so every match returns merchant: "amazon" with a US url. There is no country or marketplace parameter.

This is a different server from the MCP Data Connector. That one is read-only access to your own widget data with a uk_ user key. This one takes a cak_ team access key and matches text you send it.

Get Your Access Key

Commerce Match MCP authenticates with a team access key (cak_...) in the x-api-key header - the same key type Commerce Signals uses. If you already hold one, reuse it.

Log into app.getchatads.com
Open Commerce Match
In the Access Keys card, click Create Key

You can hold as many access keys as you have clients - one per MCP client is a good default, so you can revoke them independently. Widget keys (cwk_...) and user keys (uk_...) do not work here.

Connect

Commerce Match runs on the same MCP server as Commerce Signals. If you’ve already connected it, find_product_matches is there too - skip this section. Add the server once, under whatever name you like; one entry serves both tools. In Claude Code it’s one command. Most other clients (Claude Desktop, Cursor, Windsurf, etc.) take the JSON block - drop the transport field if your client rejects it:

claude mcp add --transport http chatads-commerce https://api.getchatads.com/tools/mcp/mcp --header "x-api-key: cak_your_access_key"

{
  "mcpServers": {
    "chatads-commerce": {
      "url": "https://api.getchatads.com/tools/mcp/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": "cak_your_access_key"
      }
    }
  }
}

It’s a Streamable HTTP MCP server, so there’s nothing to install locally and no Node or Python dependency - one URL in a config file. Restart your client and find_product_matches is available.

Tool

Tool	Params	What it returns
`find_product_matches`	`term` (required) - a product name or phrase to match; `context` (optional) - surrounding text containing that term, to disambiguate it	Up to 3 product matches in a `matches` array, plus a `count`

Param	Type	Description
`term`	string (required)	The product name or phrase to match, e.g. “Bose QuietComfort Ultra earbuds”. Brand specificity belongs here - a term naming its brand matches far better than a bare category noun. Capped at 100 characters; a longer term is truncated at a word boundary, not rejected
`context`	string (optional)	The surrounding text the term came from, used to disambiguate its category and vertical. It must contain `term` verbatim - it’s the passage the term was pulled from, not background you write yourself. If you have no surrounding text, omit it. Only the 500 characters either side of the term are used; the rest is ignored, not rejected

If term appears more than once in context, only the first occurrence is used. The words immediately around that occurrence are what drive the category and vertical signals, so a context where the same phrase appears twice under different brands or in two unrelated topics resolves against the first one and ignores the rest. When that matters, trim context down to the passage you actually mean. The response carries no offsets, so there’s no way to tell after the fact which occurrence was used. Everything outside 500 characters either side of that occurrence is dropped before matching, so trimming a long context yourself is optional - it changes which passage is used, not whether the call succeeds. Each match:

Field	Type	Description
`title`	string	The merchant’s product title
`image`	string	Product image URL
`brand_name`	string	The product’s brand
`url`	string	Merchant product page URL. Untagged - no affiliate account required
`category`	string	Catalog main/department category for this product
`merchant`	string	Which merchant the match came from. Branch on this field rather than assuming

The response is a matches array of 0 to 3 items plus a count. matches[0] is the best pick. An empty matches array is a success, not an error - it means we found no confident match for that term, and retrying won’t change that.

Example

Calling the tool with:

{
  "term": "Bose QuietComfort Ultra earbuds",
  "context": "The Bose QuietComfort Ultra earbuds are great for commuting."
}

returns:

{
  "data": {
    "matches": [
      {
        "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
        "image": "https://m.media-amazon.com/images/I/51example.jpg",
        "brand_name": "Bose",
        "url": "https://www.amazon.com/dp/B0CD2FSRDD",
        "category": "Electronics",
        "merchant": "amazon"
      }
    ],
    "count": 1
  },
  "error": null,
  "meta": {
    "request_id": "60556e82-ec0b-425b-8289-b95395db8943",
    "timestamp": "2026-07-23T14:42:01Z",
    "version": "1.0.0"
  }
}

The JSON above is the text response. Clients that support MCP structured tool output also receive the data payload directly as structured content - the bare {"matches": [...], "count": n} object, matching the tool’s declared output schema. Same envelope shape as Commerce Signals.

Limits

Input length: term is capped at 100 characters and context at 500 characters either side of the term’s first occurrence. Over-cap input is truncated or windowed, not rejected - the call still succeeds. Near-miss copies (smart quotes, extra whitespace, invisible characters, markdown wrapping) are normalized before the containment check, so they match rather than erroring.
Requests: the free tier includes 500 requests per month. Every call counts, including ones that return zero matches. Get in touch to raise your cap - tell us roughly what volume you’re expecting.
Commerce Match shares one usage pool with Commerce Signals and the rest of your team’s API usage, and the same per-minute burst limit. Your current month’s usage is shown at the top of both the Commerce Match and Commerce Signals tabs - same team-wide figure either way.
Your team’s blocked-keyword and language content rules still apply. Text that trips one returns an empty matches array rather than an error.

Troubleshooting

”This tool requires a cak_ API key”

You connected with a user key (uk_...). Commerce Match MCP takes a team access key (cak_...) - create one on the Commerce Match or Commerce Signals tab.

”term is required”

The term argument was missing, empty, or whitespace only. An empty term is a client error, not an empty-matches success.

”term must appear in context”

The context you sent doesn’t contain term verbatim. context is the passage the term was pulled from, not a slot for background you write separately. Near-miss copies - smart quotes, extra whitespace, invisible characters, markdown wrapping - are normalized on both fields first, so this error means the term genuinely isn’t there. Fix the input or drop context and send term alone; it’s an INVALID_INPUT client error, so retrying the same call won’t help.

”Extraction backend temporarily unavailable - please retry”

A SERVICE_UNAVAILABLE error means the matching service didn’t respond. It’s deliberately surfaced as an error rather than silently returning zero matches, so a retry is safe and correct here.

”Daily request limit exceeded” / “Monthly request limit exceeded”

You’ve used your plan’s allowance. See Limits.

An obvious product returns `"count": 0`

We had no confident match for that phrase in the catalog. In order of what usually fixes it:

Put the brand in term. “Bose QuietComfort Ultra earbuds” matches far better than “earbuds”.
Check the casing. The same scoring engine backs both tools, and capitalization is a real signal - see Casing Is a Signal.
Trim context to the passage the term actually came from, so the category signals around it are the right ones.

Some products legitimately aren’t in the catalog. An empty matches array is a success - treat it as “no link for this one” and move on rather than retrying.

Tool not appearing in your MCP client

Verify the URL is exactly: https://api.getchatads.com/tools/mcp/mcp
If your client’s config uses a transport field, it should be "http"
Confirm the key in x-api-key starts with cak_
Restart your MCP client completely
Ask: “What tools do you have access to?”

Getting Started

Integrations

Configuration

Monetization

Analytics & Data

MCP Tools

Trust & Performance

Account

Troubleshooting

Commerce Match MCP

Overview

Get Your Access Key

Connect

Tool

Example

Limits

Troubleshooting

”This tool requires a cak_ API key”

”term is required”

”term must appear in context”

”Extraction backend temporarily unavailable - please retry”

”Daily request limit exceeded” / “Monthly request limit exceeded”

An obvious product returns `"count": 0`

Tool not appearing in your MCP client

​Overview

​Get Your Access Key

​Connect

​Tool

​Example

​Limits

​Troubleshooting

​”This tool requires a cak_ API key”

​”term is required”

​”term must appear in context”

​”Extraction backend temporarily unavailable - please retry”

​”Daily request limit exceeded” / “Monthly request limit exceeded”

​An obvious product returns "count": 0

​Tool not appearing in your MCP client

Overview

Get Your Access Key

Connect

Tool

Example

Limits

Troubleshooting

”This tool requires a cak_ API key”

”term is required”

”term must appear in context”

”Extraction backend temporarily unavailable - please retry”

”Daily request limit exceeded” / “Monthly request limit exceeded”

An obvious product returns `"count": 0`

Tool not appearing in your MCP client