How to integrate the catalog attribute normalizer MCP server

This guide covers the mechanical integration steps for the catalog-attribute-normalizer MCP server: client configuration, authentication, and tool usage, so you can normalize product catalogs against Google, Shopify, or Amazon taxonomies without reading the source.

Q: How do I install / add this MCP server?

Add it as a remote HTTP transport pointing at the live endpoint:

claude mcp add --transport http catalog-normalizer \
  https://catalog-normalizer.acjlabs.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Any MCP client that supports remote HTTP connections with custom headers — Cursor, Cline, VS Code — works the same way.

https://acjlabs-catalog-normalizer.acjlabs.workers.dev/mcp is an alternate address for the same deployment. If that is what you already have configured, it keeps working — there is nothing to migrate.

Q: How do I authenticate — where does the API key go?

Pass your key via Authorization: Bearer YOUR_API_KEY on every tool call (a raw key value without the Bearer prefix is also accepted). Discovery endpoints (initialize, tools/list) don’t require authentication; only normalize_catalog enforces it.

Q: What’s the input — what do I pass to the tool?

Call normalize_catalog with a products array and a target_taxonomies string array. Each product needs title, description, and optional raw_attributes. target_taxonomies accepts "google", "shopify", or "amazon".

Q: What’s the output schema?

A JSON array of NormalizedProduct objects in your input order. Each result carries schema_version (2.0), source_title, category_paths (path, leaf_id, confidence per requested taxonomy), and attributes. Attribute keys are restricted to a controlled vocabulary (size, color, material, gender, sleeve_length) and always return { value, provenance } — provenance is "canonicalized" for input-mapped values, "extracted" for model-inferred ones.

Q: How does it handle the cases it can’t resolve?

A null leaf_id means the server couldn’t independently verify a category node against the live Google/Shopify taxonomy files. Amazon classification stays best-effort recall — no comprehensive public reference file exists to ground candidates against. If a single product’s classification fails, the batch loop isolates it and returns { error, source_title } for that item — one failure never voids the rest of the batch.

Q: Are there rate limits or quotas?

Usage is metered per billing tier: 500 products/month on Free, 5,000 on Pro, or pay-as-you-go at $0.01/product. Request throughput: 10 requests/minute on Free, 120 requests/minute on Pro. Exceeding the product quota returns 402; exceeding the rate limit returns 429; a missing or invalid key returns 401. Individual item failures inside a successful batch surface as { error, source_title } — they don’t throw.

Q: Is there a client library?

Yes — @acjlabs/catalog-attribute-normalizer-client on npm, wrapping the MCP JSON-RPC transport:

npm install @acjlabs/catalog-attribute-normalizer-client

const results = await client.normalizeCatalog(products, targetTaxonomies);

A minimal end-to-end example

{
  "tool": "normalize_catalog",
  "input": {
    "products": [
      { "title": "...", "description": "...", "raw_attributes": { "size": "Lrg", "Color": "Navy Blue" } }
    ],
    "target_taxonomies": ["google", "shopify"]
  }
}

Size/color canonicalization runs deterministically; category paths are grounded against the live taxonomy files, not recalled from memory.

Q: How do keys and metering work?

Free-tier keys self-serve via POST /v1/signup with an email payload — the key is returned once (store it immediately). Keys are bound to their plan’s monthly product quota, enforced server-side. Paid tiers aren’t self-serve yet (billing isn’t live pre-revenue) — the advertised Pro and pay-as-you-go pricing is published but not yet purchasable.

See the FAQ for pricing and accuracy details, or Products for the quick-start.