MCP Servers

Beyond the REST API, Vellaro exposes two Model Context Protocol (MCP) servers on mcp.vellaro.io. An AI agent can query and operate the store with the same auth, permissions, and tenant isolation as the HTTP endpoints documented here.

Endpoints

Server	Endpoint	Auth
Storefront	`https://mcp.vellaro.io/storefront`	`X-Vellaro-Key: cx_pk_live_...` header — or `?key=` in the URL (see Connecting)
Admin	`https://mcp.vellaro.io/admin`	`Authorization: Bearer <staff_token>` header

Transport is streamable-HTTP (stateless). No secret is stored: the credential travels in the MCP request headers and is forwarded verbatim to the REST API.

Storefront MCP

Authenticated with the store’s publishable key (cx_pk_live_...) — it identifies the store and cannot touch the /admin/* endpoints.

Tool	What it does
`search_products`	full-text search across the catalog
`list_products` / `get_product`	catalog and variant details
`list_categories`	category tree
`store_info`	store data and appearance
`payment_methods`	available payment methods
`track_order`	status of an order

Admin MCP

Authenticated with a staff token + granular permissions; every action is scoped to its store. Mutations require confirm=true and are audit-logged.

Tool	What it does
`list_products` / `get_product`	catalog (including inactive)
`create_product`	create a product
`set_price` / `set_stock`	a variant’s price/stock (absolute)
`adjust_stock`	relative stock change
`list_orders` / `get_order`	orders
`update_order_status`	order progression/fulfillment, with optional `tracking_number` and `shipping_carrier`

update_order_status with status: "refunded" on a paid or partially_refunded order performs a real refund of the remaining amount through the payment gateway, like PATCH /admin/orders/{id} and POST /admin/orders/{id}/refunds: it doesn’t just change the label. Without confirm=true the tool answers with the warning and applies nothing. It needs the roles that can refund (admin, manager, sales_manager), otherwise 403 order.refund_forbidden; if the gateway fails, 502 order.refund_gateway_error and the order stays as it was.

The Admin MCP Bearer can be a staff user’s access token (it expires after 30 minutes) or a store API token, recommended for agents connected for a long time: chosen role, mandatory expiry, instant revocation. See Manage your store via API.

Connecting

Header-based clients (Claude Desktop, Claude Code)

The recommended way: the server endpoint plus the credential in the headers.

{
  "mcpServers": {
    "vellaro-storefront": {
      "url": "https://mcp.vellaro.io/storefront",
      "headers": { "X-Vellaro-Key": "cx_pk_live_<slug>_..." }
    },
    "vellaro-admin": {
      "url": "https://mcp.vellaro.io/admin",
      "headers": { "Authorization": "Bearer <staff_token>" }
    }
  }
}

claude.ai connector (key in the URL — storefront only)

The claude.ai “custom connector” dialog supports OAuth only, not custom headers. For the storefront you can pass the publishable key directly in the URL:

https://mcp.vellaro.io/storefront/?key=cx_pk_live_<slug>_...

Leave the OAuth fields (Client ID / Secret) empty. The header still takes precedence: if the client sends X-Vellaro-Key, the query string is ignored.

Storefront only. The publishable key is read-only (like a Stripe pk_) and is acceptable in a URL, but it will appear in the server access logs. Admin stays header-only: a staff token must never travel in a URL.

The MCP servers are a thin layer over this same REST API: anything a tool does, you can do over HTTP. The endpoints listed in this section remain the source of truth. See also Authentication.

Model Context Protocol

Storefront API

Admin API

Endpoints

Storefront MCP

Admin MCP

Connecting

Header-based clients (Claude Desktop, Claude Code)

claude.ai connector (key in the URL — storefront only)