MCP Endpoint

POST

/mcp

const url = 'https://api.vviinn.com/mcp';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.vviinn.com/mcp \
  --header 'Authorization: Bearer <token>'

Single JSON-RPC 2.0 endpoint that follows the Model Context Protocol, served over the MCP Streamable HTTP transport. Use it to expose vviinn’s services to agentic clients through one MCP connection instead of integrating each REST endpoint individually.

The server is listed in the MCP Registry as com.vviinn/commerce-context-layer.

Shops can also publish their own registry entry under their domain (e.g. com.acme/shop) that points at this endpoint with their site’s read-only JWT pre-filled and a description tailored to their catalog. Setup uses the same MCP publisher tooling and DNS verification on the shop’s domain.

The shape of the JSON-RPC requests and responses is defined by the MCP specification and is intentionally not described here. Connect with any MCP-capable client and call tools/list to discover the tools available for your site, including their input and output schemas.

Authorization

Authenticate with the same credentials you already use for the REST API by setting one of:

Authorization: Bearer <jwt> — read-only JWT.
Authorization: Basic <…> — site credentials.

The site is determined entirely from the credentials; there is no per-site URL and no path or query parameter.

Some tools require elevated privileges, which are granted by the site’s Basic credentials. They are documented in their respective section.

Tools

The tools below are grouped by what they do. Each tool’s input and output schemas are exposed at runtime via tools/list.

Search and Discovery

Each tool wraps an existing REST endpoint; use the REST documentation to understand the underlying behavior.

Tool	REST equivalent
`text_search`	`POST /text-search`
`similar_products`	`POST /similar-products`
`cross_selling`	`POST /cross-selling`
`visual_search`	`POST /visual-search`

Catalog

Discovery tools that reveal the structure and contents of the catalog an agent is working with.

Tool	What it reveals
`list_relevant_columns`	The product columns worth working with in this catalog, each with its `type` and human-readable `label` — the actionable vocabulary an agent can filter on, build facets from, or use to describe the catalog.
`describe_column`	The catalog-wide values of a single column — its distinct values, the category tree, a numeric range, or a true/false split — the full value space an agent can present, filter on, or validate input against.
`get_item_group`	All variants belonging to an item group, looked up by its `item_group_id` — the complete set, not the possibly incomplete one a search result carries.
`get_item`	The full record for a single product, looked up by its `id`.
`get_items`	The full records for a batch of products, looked up by a list of `id`s — the plural sibling of `get_item`.

Memory

Service-side, append-only conversation memory for agentic clients: append everything that happens during a conversation to a durable per-conversation log and recall it completely and in order.

All memory tools require the site’s Basic credentials; the read-only JWT does not authorize them.

Tool	Purpose
`append_memory`	Append a batch of items to a conversation’s log.
`recall_memory`	Return the last count items of a conversation, in order.
`replay_memory`	Return limit items from a given offset — the positional read used to fully restore a conversation.
`list_conversations`	List the conversation ids of the authenticated site with their created and last-appended timestamps.
`summarize_conversation`	A condensed, up-to-date summary of a conversation so far — the gist instead of the full log.

Authorizations

read-only-token
site-credentials

Responses

200

JSON-RPC 2.0 response. The body shape follows the MCP specification and is not described here.

401

Missing or invalid credentials. The WWW-Authenticate header advertises the accepted schemes (Bearer, Basic).

403

Forbidden.

429

Rate limit exceeded. The Retry-After header indicates when to retry.