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

# 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](https://andcze.mintlify.site/en/developers/mcp.md) (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](https://andcze.mintlify.site/en/site/workspace.md).

## 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](https://andcze.mintlify.site/en/site/workspace.md#workspace-token) page.

**2. Set the environment variable**

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

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

**3. Pull the site project**

In an empty folder download the current draft ([CLI](https://andcze.mintlify.site/en/site/cli.md)):

```bash theme={null}
npx itemshop login --shop <shop-id>
npx itemshop pull
```

**4. Add the MCP server**

With one command:

```bash theme={null}
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**

```bash theme={null}
claude
```

## MCP configuration file

```json .mcp.json theme={null}
{
  "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:

```bash theme={null}
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](https://andcze.mintlify.site/en/developers/agent-skills.md) with one command (into `.claude/skills/` by default):

```bash theme={null}
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](https://andcze.mintlify.site/en/site/workspace.md#publishing-rules). |

> **[All agents](https://andcze.mintlify.site/en/site/agents.md)**
>
> Comparison and shared rules.

> **[MCP](https://andcze.mintlify.site/en/developers/mcp.md)**
>
> Tools and scopes.


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