> ## 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.

# MCP Servers

> Vellaro's two Model Context Protocol servers, on top of the same REST API.

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](#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 with filters |
| `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      |

## Connecting

### Header-based clients (Claude Desktop, Claude Code)

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

```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>" }
    }
  }
}
```

### 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.

<Warning>
  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.
</Warning>

<Note>
  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](/en/authentication).
</Note>