MCP server

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

ItemShop runs a Model Context Protocol 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.

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:

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.

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

ItemShop knowledge for your agent.

Connecting agents

Claude Code, Codex, Cursor setup.