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

# MCP server

> The hosted ItemShop MCP server: tools for the site, catalog, orders and discounts for AI agents.

ItemShop runs a [Model Context Protocol](https://modelcontextprotocol.io) server so an AI agent (Claude Code, Codex, OpenCode, Cursor, Gemini CLI…) can work on your shop: edit site files, build and publish previews, manage products and discounts.

| | |
| - | - |
| URL | `https://itemshop.dev/api/v2/mcp` |
| Transport | streamable HTTP, stateless (`GET` returns 405) |
| Authentication | `Authorization: Bearer iswt_…` (workspace token) |
| stdio bridge | `npx -y @itemshop/mcp` (`ITEMSHOP_TOKEN` variable) |

Per-agent setup is in [Connecting agents](https://andcze.mintlify.site/en/site/agents.md).

## Workspace token

In the panel: **Workspace → MCP → New token**. Pick only the scopes the agent needs. The token (prefix `iswt_`) is shown **once** — keep it in an environment variable, not in a committed file:

```bash theme={null}
export ITEMSHOP_TOKEN=iswt_...
```

| Scope | Allows |
| - | - |
| `site:read` | Read files, revisions, builds and `src/site.config.ts` |
| `site:write` | Edit the draft, commit/discard it, run builds, previews and publishing (includes `site:read`) |
| `catalog:read` | Read products and servers |
| `catalog:write` | Create and update products (includes `catalog:read`) |
| `orders:read` | Read orders (no e-mails, IPs or payment details) |
| `discounts:write` | Discounts and vouchers — read and write |
| `stats:read` | Read sales stats |

A token can never exceed what its creator has in the shop team — if the creator loses access, the token stops working.

## Tool groups

The owner sets each group to off / read / write in **Workspace → MCP**, for every token. A call's effective access is the **lower** of the group setting and the token scopes.

| Group | Tools | Read / write scope | Default |
| - | - | - | - |
| Context | `get_shop_context` | any token | always |
| Site files | `get_site`, `list_files`, `read_file`, `search_files`, `list_revisions`, `write_file`, `apply_patch`, `delete_file`, `commit_draft`, `discard_draft` | `site:read` / `site:write` | write |
| Builds & publishing | `get_build`, `start_build`, `create_preview`, `promote_deployment` | `site:read` / `site:write` | write |
| Appearance | `get_site_config`, `update_site_config` | `site:read` / `site:write` | write |
| Product catalog | `list_products`, `get_product`, `create_product`, `update_product` | `catalog:read` / `catalog:write` | read |
| Orders | `list_orders` | `orders:read` / — | **off** |
| Discounts & vouchers | `list_discounts`, `create_discount`, `update_discount`, `list_vouchers`, `create_vouchers` | `discounts:write` / `discounts:write` | **off** |
| Stats | `get_stats` | `stats:read` / — | read |

Orders and stats have no write mode. Orders are off by default because they contain buyer data — you enable them deliberately.

The server also exposes the resources `itemshop://shop` and `itemshop://site/files/{path}` (the draft) and two prompts: `change_look` and `add_product`.

## Safety

* File edits go to the **draft** — nothing changes in production until a build is promoted.
* `promote_deployment` and `discard_draft` need an explicit `confirm: true`. You can reserve production publishing for the panel (**Workspace → Publishing**) — the agent then only shares a preview link. With the policy on (the default), `promote_deployment` returns `403 WORKSPACE_PRODUCTION_REQUIRES_APPROVAL`.
* Product changes go through the same validation as the panel.
* Every call is recorded in the Workspace activity log (source `mcp`).
* Per-token limits: 240 requests per minute, of which 60 writes per minute. Failed authentications are rate-limited per IP.
* Suspect a leak? Revoke the token in the panel — it takes effect immediately.

## stdio bridge

If your agent only runs local stdio servers, use `@itemshop/mcp`. It forwards every MCP message to the hosted server, so it has the same tools, scopes and limits.

```bash theme={null}
npx -y @itemshop/mcp [--url <url>] [--api-base <url>] [--profile <name>] [--token <iswt_…>]
```

| Setting | Order of precedence |
| - | - |
| Server URL | `--url` › `ITEMSHOP_MCP_URL` › `<api base>/mcp` |
| API base | `--api-base` › `ITEMSHOP_API_BASE` › `itemshop login` profile › `https://itemshop.dev/api/v2` |
| Token | `--token` › `ITEMSHOP_TOKEN` › `ITEMSHOP_MCP_TOKEN` › `ITEMSHOP_API_KEY` › `itemshop login` profile |

The bridge accepts only workspace tokens (`iswt_…`) and refuses to send the token over plain HTTP except to `localhost`. Diagnostics go to stderr; stdout carries only MCP messages.

> **“ItemShop rejected the workspace token”**
>
> The token was revoked, expired, or its creator lost access to the shop. Create a new one.

> **“No workspace token”**
>
> Set `ITEMSHOP_TOKEN` in the environment the agent starts the bridge with.

> **The agent sees fewer tools than expected**
>
> Check the token scopes and the group modes in **Workspace → MCP**. **Test connection** shows what is actually available.

> **[Agent skills](https://andcze.mintlify.site/en/developers/agent-skills.md)**
>
> ItemShop knowledge for your agent.

> **[Connecting agents](https://andcze.mintlify.site/en/site/agents.md)**
>
> Claude Code, Codex, Cursor setup.


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