Skip to content

MCP Catalog Server

Exposes the store's public, AI-facing product catalog as a read-only Model Context Protocol (MCP) server. It serves the same projection, compliance filter, and public price source as the /api/ai/products REST surface, so an MCP-connected agent sees exactly what an anonymous shopper sees — nothing more. It is off by default and opt-in per channel.

At a glance
Extension id mcp_catalog
Category ai
Version 0.1.0
Provides HTTP router (MCP endpoint at POST /mcp/catalog)
External account None

What It Provides

  • One HTTP router, contributed through the api_routers() surface and mounted at app creation:
    • POST /mcp/catalog — the MCP endpoint, using the Streamable HTTP transport in plain-JSON mode: single JSON-RPC 2.0 request/response with application/json replies, no SSE streams.
    • GET /mcp/catalog — returns 405; the server offers no server-initiated stream.
  • MCP protocol version 2025-06-18, server name vectis-catalog, with server instructions declaring the read-only anonymous-shopper scope.
  • Three read-only tools over PublicCatalogProjection:
Tool Arguments Behavior
list_products limit (1–200, default 50), offset Paginated public catalog listing
get_product slug (required) One product by URL slug
search_products query (required), limit (1–50, default 20) Name / slug / brand substring search
  • Product records use the same schema.org-aligned shape as /api/ai/products: @type: Product, slug as id, name, url, availability, plus description, brand, category, image, and price when present. Availability is bucketed (in_stock / out_of_stock) — never an exact inventory count.

Setup

  1. Opt the channel in: set the seo.ai_api.enabled setting to true (channel-scoped, with a global fallback). The AI-facing catalog — REST and MCP alike — is off by default; until the channel opts in, POST /mcp/catalog returns 404.
  2. Point an MCP client at https://<your-api-host>/mcp/catalog using the Streamable HTTP transport.
  3. The serving channel is resolved per request: X-Channel-ID header, then X-Channel-Slug; with exactly one channel it is auto-selected, otherwise the request hostname is matched against the channel code, falling back to the first channel.

Configuration Reference

This extension has no config_schema and no settings page of its own. Its only switch is the seo.ai_api.enabled setting it shares with the REST AI product API.

Permissions

The manifest declares no permissions.

Operational Notes

  • The endpoint carries no authentication: it serves only the anonymous public projection, and gated or compliance-hidden products are never returned.
  • Product URLs use the product's canonical URL when one is set; otherwise they are built from the channel's configured site base URL, falling back to the request's own base URL.
  • JSON-RPC notifications (e.g. notifications/initialized) are acknowledged with 202 and no body.
  • JSON-RPC batch requests are rejected with -32600 — batching was removed in the 2025-06-18 MCP revision.
  • Tool failures come back as isError content blocks inside a successful JSON-RPC result (per the MCP spec), so tool bugs never crash the transport. Unknown methods get -32601; malformed JSON gets -32700.

See Building Extensions for the api_routers() contribution surface.