AI agents and MCP

An AI agent can act for a signed-in buyer at a store without anyone pasting a key: the buyer approves the agent once on a branded consent page, the agent receives OAuth tokens scoped to that store, and it calls a Model Context Protocol (MCP) server whose tools run through the same routes as the storefront. Everything on this page is mounted only when the operator has set API_PUBLIC_URL — see Configuration.

Discovery

The platform site and every storefront host publish machine-readable pointers:

URL	What it is
/.well-known/api-catalog	RFC 9727 linkset of the API's documents
/openapi.yaml	The OpenAPI 3.1 contract
/docs/api.md and /auth.md	Markdown guides for agents — tenancy, auth, public endpoints, errors
/.well-known/oauth-protected-resource	RFC 9728 resource metadata, with authorization_servers and, on a storefront host, authorization_parameters.store naming that store
/.well-known/oauth-authorization-server	Authorization-server metadata (also at /.well-known/openid-configuration)
/.well-known/jwks.json	ES256 public keys for access tokens
/.well-known/mcp/server-card.json	The MCP server card
/.well-known/agent-skills/index.json	Skills index; each skill's SKILL.md explains one job (auth, catalog, request a quote, the MCP storefront)

The content policy published in robots.txt and Content-Signal is search=yes, ai-input=yes, ai-train=no: index and cite, do not train. Tenants control their own storefront's signals from Settings → Configuration → Search & AI visibility.

OAuth 2.1

Endpoint	Purpose
POST /oauth/register	Dynamic client registration (RFC 7591) — public clients only
GET/POST /oauth/authorize?store=<storefront host>&…	Branded consent and buyer sign-in for that store
POST /oauth/token	authorization_code (PKCE S256 required) and refresh_token
POST /oauth/revoke	RFC 7009

Rules an agent must follow:

• PKCE S256 is mandatory and there are no client secrets — a secret shipped inside a desktop agent is not a secret.
• Name the store. One API serves every tenant, so /oauth/authorize needs store=<the store's hostname>; read it from the store's /.well-known/oauth-protected-resource.
• Redirect URIs must be https, loopback http, or a private-use scheme, and match the registration exactly.
• Tokens are audience-bound (aud: <issuer>/mcp, RFC 8707) and signed with ES256; a storefront session JWT is not accepted at /mcp and vice versa.
• Authorization codes are single-use with a 60-second life. Refresh tokens rotate on every use.

Scopes: catalog:read, pricing:read, cart:write, orders:read, quotes:read, quotes:write, messages:write, profile:read. The consent page shows them as plain-language permissions and names the tenant, not the platform.

A buyer can see and disconnect every agent they approved: GET /storefront/account/agents and DELETE /storefront/account/agents/{id}.

The MCP server

POST /mcp speaks streamable HTTP JSON-RPC. An initialize without a token receives 401 with a WWW-Authenticate challenge pointing at the resource metadata. tools/list returns only the tools the token's scopes allow, and the scope is re-checked on every call.

Tool	Scope
search_products, get_product, check_availability	catalog:read
get_my_price	pricing:read
view_cart, add_to_cart	cart:write
list_orders, get_order	orders:read
list_quotes, read_quote_thread	quotes:read
request_quote, submit_rfq, counter_quote	quotes:write
post_quote_message	messages:write
whoami	profile:read

Tools do not reimplement business logic: each dispatches through the storefront's own routes with a session synthesised from the token, so pricing resolution, promotions, catalog visibility and live ERP stock are exactly what the buyer would see in a browser. Every token traces to one buyer who approved it and can revoke it; there is no anonymous agent identity.

Related topics

• Authentication
• Configuration
• Admin guide — Ask AI — the operator-side assistant, a different surface
• API reference