Commerce MCP

Authentication and access

Three ways in: a directory endpoint with no credential, an API key, or optional OAuth 2.1 sign-in. Your scopes decide which tools and fields you get.

Ways to connect#

Method	Endpoint	For	Notes
Directory endpoint	`https://app.aiptimise.com/api/mcp/p/{platform}`	Directory apps that cannot send a key (ChatGPT, Claude).	No credential. Aiptimise enables one per platform. Never returns exact inventory.
API key	`https://app.aiptimise.com/api/mcp`	Your servers, agents and SDKs.	`Authorization: Bearer aip_live_…`. Keys are server-side secrets. A key sent to a directory endpoint must belong to that platform's consumer, or the call is refused with `consumer_mismatch`.
OAuth 2.1 (optional)	Either endpoint	Directory apps whose users are your partner or reviewer accounts.	Sign-in adds nothing a shopper needs today: every tool also works anonymously.

Without a key, https://app.aiptimise.com/api/mcp answers HTTP 401 authentication_required unless Aiptimise has opened anonymous access on it.

Scopes#

Generated from the scope registry.

Scope	Unlocks	Meaning	Anonymous callers
`catalog:read`	`search_products`, `get_store_info`, `get_aiptimise_product_data`, `get_product_variants`	Search products and read product details from participating stores	Yes, when the platform has it
`offers:read`	`get_live_price_and_inventory`	Check current prices and availability	Yes, when the platform has it
`inventory:read`	The `inventory_quantity` field in `get_live_price_and_inventory`, `get_product_variants`	See exact stock quantities	Never
`promotions:read`	`get_active_promotions`	Read active promotions	Yes, when the platform has it
`loyalty:read`	`get_loyalty_program`	Read published loyalty program terms	Yes, when the platform has it

A key can be narrowed to fewer scopes than your consumer has. An OAuth token carries the scopes the user consented to, and a call gets the intersection with your consumer's scopes.

Sandbox and production#

Sandbox consumers read the demo store only; production consumers read every store their coverage allows. Scopes and limits are set per consumer by Aiptimise. See Getting started for the tiers and how to move to production.

For directory apps whose users should sign in with an Aiptimise developer account.

Discovery

Each endpoint publishes protected-resource metadata (RFC 9728), which names the authorization server:

https://app.aiptimise.com/.well-known/oauth-protected-resource/api/mcp
https://app.aiptimise.com/.well-known/oauth-protected-resource/api/mcp/p/{platform}
https://app.aiptimise.com/.well-known/oauth-authorization-server
https://app.aiptimise.com/.well-known/openid-configuration

Flow

Authorization code with PKCE, code_challenge_method=S256 only.
Clients identify themselves with a Client ID Metadata Document: the client_id is the HTTPS URL of that document.
A client Aiptimise has not seen is held as pending and cannot sign anyone in. Aiptimise approves it and assigns it to your consumer.
Send the resource parameter with the exact endpoint URL, for example https://app.aiptimise.com/api/mcp. The token's audience is that URL; a token for one endpoint is refused on another.
Access tokens are JWTs valid for 10 minutes. Refresh tokens (scope offline_access) last 30 days.
Scopes: openid, profile, email, offline_access and the MCP scopes above. A token with no MCP scope lists no tools. Calling a tool whose scope your consumer has but the token lacks gets HTTP 403 insufficient_scope with the scopes to request.

Who can sign in

Developer accounts with a verified email that are current members of the consumer the client belongs to. Merchant and Aiptimise staff accounts are refused. Removing a member, revoking the client or suspending the consumer stops tokens already issued, on their next call.

Not available

Client credentials, password and implicit grants; dynamic client registration; shopper sign-in and shopper account data.