Skip to main content
The Model Context Protocol (MCP) is the standard by which AI agents (Claude and others) connect to external tools and data. Vellaro exposes two MCP servers, so an agent can both browse the store like a shopper and manage it — using the same API and the same security rules as the rest of the platform.

Storefront MCP

Conversational commerce: search products, browse the catalog, payment methods, and store details, track orders. Auth with a publishable key.

Admin MCP

Management via natural language: catalog, prices, stock, orders. Auth with a staff token + permissions, with confirmations on sensitive actions.

Storefront MCP

Designed for public clients and agents that help the user choose and follow a purchase. Available tools: Auth: the store’s publishable key (cx_pk_live_...) — it identifies the store and cannot touch the admin.

Admin MCP

Designed for operators and integrations: “raise electronics prices by 5% and set the stock of discontinued items to zero”. Available tools:
update_order_status with status: "refunded" on a paid order really refunds the remaining amount to the customer through the payment gateway: it’s not a label, it moves money, like a refund from the admin panel. It needs a role that can refund (admin, manager, sales_manager), otherwise the API answers 403 order.refund_forbidden. On an order that was never collected, use cancelled.
Security — inherits the Admin API model:
  • Auth with a staff token + granular permissions; every action is scoped to its store.
  • Mutations require confirm=true (the agent first sees what it would do, then confirms) and are audit-logged.
  • The staff token must never go into a public client.
A staff access token expires after 30 minutes. For an agent connected for a long time, use a store API token with the minimum role it needs: it’s generated with POST /admin/api-tokens and can be revoked instantly. See Manage your store via API.

How to connect

An MCP client (e.g. Claude Desktop) is configured with the server endpoint and credentials:
With the claude.ai custom connector (which supports OAuth only, not custom headers), pass the publishable key in the URL for the storefront — leave the OAuth fields empty:
The MCP servers are a thin layer over the same REST API documented here: anything a tool does, you can also do via HTTP. The API Reference remains the source of truth. Auth details and caveats in MCP Servers.