Claude Code

Connect Claude Code to your shop through the hosted MCP server: token, configuration, instructions file and your first change.

Claude Code connects to ItemShop through the MCP server (Streamable HTTP, Authorization: Bearer header). It gets tools for site files, builds, the catalogue and — if you enable them — orders and discounts. All its changes land in the draft in Workspace.

Step by step

1. Create a workspace token

   In Workspace → MCP → New token pick the smallest sensible set of scopes — usually site:write and catalog:read. You see the token (iswt_…) only once. Scopes are described on the AI Workspace page.

2. Set the environment variable

   The configuration never contains the token — it refers to the ITEMSHOP_TOKEN variable.

   export ITEMSHOP_TOKEN=iswt_...
   
3. Pull the site project

   In an empty folder download the current draft (CLI):

   npx itemshop login --shop <shop-id>
   npx itemshop pull
   
4. Add the MCP server

   With one command:

   claude mcp add --transport http --scope project itemshop https://itemshop.dev/api/v2/mcp --header 'Authorization: Bearer ${ITEMSHOP_TOKEN}'
   

   or save the file from the next section.

5. Start the agent

   claude
   

MCP configuration file

.mcp.json

{
  "mcpServers": {
    "itemshop": {
      "type": "http",
      "url": "https://itemshop.dev/api/v2/mcp",
      "headers": { "Authorization": "Bearer ${ITEMSHOP_TOKEN}" }
    }
  }
}

type: "http" is required. Claude Code expands ${ITEMSHOP_TOKEN} at start-up — the token never lands in the file, so you can commit .mcp.json.

In Workspace → Agent choose the same agent and the panel shows ready commands, files and a zip bundle for your shop. Offline you can generate them with:

npx itemshop mcp config --agent claude-code

Instructions file

The panel also generates CLAUDE.md — the file Claude Code reads at start-up. It holds your shop’s context (name, id, API and panel addresses), the list of enabled MCP tool groups and the project rules: keep itemshop.site.json, data only through the SDK, checkout via redirect with two consents, no secrets in code, build and file limits, publishing policy. Copy it into the project root.

Check the connection

In the agent run /mcp — the itemshop server should be connected. You can also click Test connection in Workspace → MCP. Start with something safe, e.g. “Show the shop context and the list of site files”. Tool calls then show up in the MCP log and on the activity timeline (source mcp).

Skills

Install agent skills with one command (into .claude/skills/ by default):

npx itemshop skills add itemshop-storefront itemshop-theme

Troubleshooting

Symptom	Cause
401 when connecting	ITEMSHOP_TOKEN is empty in the agent’s environment, or the token was revoked.
The agent doesn’t see shop tools	The group is off in Workspace → MCP, or the token lacks the needed scope.
403 on write	The token only has site:read, or your account lost the site:write permission.
A change doesn’t reach production	You approve production yourself — see publishing rules.

All agents

Comparison and shared rules.

MCP

Tools and scopes.