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

# Cursor

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

Cursor 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. Save the MCP configuration**

Save the file from the next section in the project folder.

**5. Enable the server in the editor**

Open the project in Cursor, go to **Settings → MCP** and enable the `itemshop` server. Then use the agent in the chat panel.

## MCP configuration file

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "itemshop": {
      "url": "https://itemshop.dev/api/v2/mcp",
      "headers": { "Authorization": "Bearer ${env:ITEMSHOP_TOKEN}" }
    }
  }
}
```

The variable reference uses the `${env:ITEMSHOP_TOKEN}` syntax. Cursor must see the variable — start it from the terminal where you exported it (`cursor .`), or set it in your system environment and restart the editor.

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 cursor
```

## Instructions file

The panel also generates `AGENTS.md` — the file Cursor 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

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 a command, pointing at this agent's skills folder:

```bash theme={null}
npx itemshop skills add itemshop-storefront --dir <agent-skills-folder>
```

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