> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI assistants (MCP)

> Connect Claude and other AI assistants to your wishlist data with scoped access tokens.

Codebeans Wishlyst runs a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect an AI assistant to it and ask questions about your wishlists in plain language:

* *"Which 10 products are wishlisted most this month?"*
* *"Export my wishlist customers as CSV."*
* *"Which wishlisted products are about to sell out?"*
* *"How much revenue came from wishlists last week?"*

Assistants get **read-only** access. They cannot change wishlists, settings or emails.

> [!NOTE]
>
> Requires a plan that includes **AI / MCP Access**.

## Create an access token

![AI / MCP Access (right) and the Automations page (left)](https://mintcdn.com/codebeans-wishlyst/FOg6WqIIKdNxdSzd/images/admin/mcp-and-automations.jpeg?fit=max\&auto=format\&n=FOg6WqIIKdNxdSzd\&q=85\&s=ca6a4550e5ab42cd79c1b254de6a910e)

AI / MCP Access (right) and the Automations page (left)

**1. Open AI / MCP Access**

Go to **Wishlist Settings → AI / MCP Access**.

**2. Fill in the form**

* **Token name**: something you will recognize, e.g. `Claude Desktop`.
* **Access scopes**: untick anything the assistant does not need (see below).
* **Expiry**: Never expires, 30 days, 90 days or 1 year.

**3. Copy the token**

Tokens start with `wsl_`. You can view and copy a token again later from **Your access tokens**.

### Scopes

| Scope | Label | Gives access to |
| - | - | - |
| `read:customers` | Customers | List and search wishlist customers and their wishlists |
| `read:wishlists` | Wishlists | List wishlists, wishlist items and recent activity |
| `read:analytics` | Analytics | Dashboard stats, top products, low stock and conversion revenue |
| `read:billing` | Plan & usage | Current plan, limits and monthly usage |
| `export` | CSV export | Lets tools return CSV exports |

### Manage tokens

The **Your access tokens** table shows each token's scopes, status (Active, Disabled, Expired, Revoked), when it was last used and when it expires.

* **Disable** pauses a token. **Enable** turns it back on.
* **Revoke** removes a token permanently. Use it if a token may have leaked.

## Connect your assistant

Your MCP endpoint URL is shown under **How to connect** on the same page. Replace `<MCP_URL>` and `<your-token>` below with your values.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http wishlyst <MCP_URL> \
>   --header "Authorization: Bearer <your-token>"
> ```

> [tab] Claude Desktop
>
> Add this to `claude_desktop_config.json` (**Settings → Developer → Edit config**). It uses [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), so you need Node.js installed.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "wishlyst": {
>       "command": "npx",
>       "args": [
>         "mcp-remote",
>         "<MCP_URL>",
>         "--header",
>         "Authorization: Bearer <your-token>"
>       ]
>     }
>   }
> }
> ```

> [tab] Other MCP clients
>
> For Antigravity, Cursor and any client that supports remote HTTP servers:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "wishlyst": {
>       "url": "<MCP_URL>",
>       "headers": {
>         "Authorization": "Bearer <your-token>"
>       }
>     }
>   }
> }
> ```

The server uses the Streamable HTTP transport (`POST` only). Each token can make up to 60 requests per minute. When the limit is reached, the server answers `429` with a `Retry-After` header.

## Tools

The assistant only sees the tools its token has scopes for. Dates use `YYYY-MM-DD`.

> [accordion] list\_customers — read:customers
>
> Paginated wishlist customers, like the **Customers** page.
>
> | Parameter | Default | Notes |
> | - | - | - |
> | `page` | `1` | |
> | `pageSize` | `20` | 1–100 |
> | `search` | — | Name or email, up to 100 characters |
> | `customerType` | `all` | `signon`, `guest` or `all` |
> | `startDate`, `endDate` | — | Filter by wishlist creation date |
> | `format` | `json` | `csv` needs the `export` scope |
> | `includeEmpty` | `false` | Include empty wishlists in CSV |

> [accordion] get\_customer\_wishlists — read:customers
>
> One customer's wishlists with their items. `query` (required) is a name, email or numeric customer ID. Also accepts `format` and `includeEmpty`.

> [accordion] list\_wishlists — read:wishlists
>
> Every wishlist with its customer, product count and total value. Accepts `page`, `pageSize` (20), `search`, `includeGuests` (`true`), `startDate`, `endDate`, `format`, `includeEmpty`.

> [accordion] list\_wishlist\_items — read:wishlists
>
> Items in one wishlist (`wishlistId`) or across the whole store. Accepts `page`, `pageSize` (50), `search`, `startDate`, `endDate`, `format`.

> [accordion] get\_top\_wishlists — read:wishlists
>
> Wishlists with the most items. `limit` 1–50 (default 10). Also accepts `format` and `includeEmpty`.

> [accordion] get\_recent\_wishlists — read:wishlists
>
> Latest products added to wishlists. `limit` 1–50 (default 20).

> [accordion] get\_dashboard\_stats — read:analytics
>
> Signed-in vs guest shoppers, total wishlists, items, unique products and wishlist revenue. Optional `startDate`, `endDate`.

> [accordion] get\_top\_products — read:analytics
>
> Most-wishlisted products with counts. `limit` (default 10).

> [accordion] get\_low\_stock\_products — read:analytics
>
> Wishlisted products below an inventory threshold. `limit` (default 10), `threshold` 1–1000 (default 10).

> [accordion] get\_conversion\_revenue — read:analytics
>
> Orders and revenue per currency from wishlist orders (tagged `cbwishlist-order`), with the 20 most recent orders. Optional `startDate`, `endDate`.

> [accordion] get\_plan\_usage — read:billing
>
> Current plan, feature limits (`-1` means unlimited) and this billing period's usage.

### CSV exports

With the `export` scope, tools that accept `format: "csv"` return CSV with the same columns as the admin Excel export. Output is capped at 10,000 rows. For bigger exports, use **Customers → Export → Share With Email** in the app.

## Security

* The app stores only a hash and an encrypted copy of each token.
* Give each assistant its own token so you can revoke one without affecting the others.
* Pick the fewest scopes the assistant needs, and an expiry when you can.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.