> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vellaro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI & MCP

> Use Vellaro as a connector for AI engines through the Model Context Protocol.

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
**shop** on the store and **manage** the store — using the same API and the same security
rules as the rest of the platform.

<CardGroup cols={2}>
  <Card title="Storefront MCP" icon="cart-shopping">
    Conversational commerce: search products, manage the cart, start checkout,
    track orders. Auth with a **publishable key**.
  </Card>

  <Card title="Admin MCP" icon="gear">
    Management via natural language: catalog, prices, stock, orders. Auth with a **staff
    token** + permissions, with confirmations on sensitive actions.
  </Card>
</CardGroup>

## Storefront MCP

Designed for public clients/agents that buy on the user's behalf. Main tools:

| Tool                        | What it does                  |
| --------------------------- | ----------------------------- |
| `search_products`           | full-text search with filters |
| `get_product`               | product/variant detail        |
| `list_categories`           | category tree                 |
| `add_to_cart` / `view_cart` | cart management               |
| `get_payment_methods`       | available methods             |
| `create_checkout`           | start the order               |
| `track_order`               | status of an order            |

Auth: the store's **publishable key** (`cx_pk_live_...`) — it identifies the store and
cannot touch the admin.

## Admin MCP

Designed for operators/integrations: *"raise electronics prices by 5% and deactivate the
out-of-stock items"*. Main tools:

| Tool                                  | What it does                 |
| ------------------------------------- | ---------------------------- |
| `list_products` / `get_product`       | catalog (including inactive) |
| `create_product` / `update_product`   | create/update                |
| `set_price` / `set_stock`             | price/stock of a variant     |
| `list_orders` / `update_order_status` | orders and fulfillment       |

**Security** — inherits the Admin API model:

* Auth with a **staff token** + granular permissions; every action is scoped to **its store**.
* **Mutations** require explicit confirmation and are **audit-logged**.
* The staff token must never go into a public client.

## How to connect

An MCP client (e.g. Claude Desktop) is configured with the server endpoint and credentials:

```json theme={null}
{
  "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>" }
    }
  }
}
```

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:

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

<Note>
  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](/en/api-reference) remains the
  source of truth. Auth details and caveats in [MCP Servers](/en/api-reference/mcp).
</Note>