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

# Connecting agents

> Work on your shop with Claude Code, Codex, OpenCode, Gemini CLI, Cursor and other agents connected over MCP.

Besides the built-in [AI editor](https://andcze.mintlify.site/en/site/ai-editor.md) you can use the agent you already know. ItemShop provides a **hosted MCP server** — the agent gets tools for site files, builds, products and discounts, and all its changes land in the draft in [Workspace](https://andcze.mintlify.site/en/site/workspace.md).

| Parameter | Value |
| - | - |
| Address | `https://itemshop.dev/api/v2/mcp` |
| Transport | Streamable HTTP (stateless) |
| Authentication | `Authorization: Bearer <workspace token>` (`iswt_…`) |
| Environment variable | `ITEMSHOP_TOKEN` |

## Supported agents

> **[Claude Code](https://andcze.mintlify.site/en/site/agents/claude-code.md)**
>
> `claude mcp add` or `.mcp.json`.

> **[OpenAI Codex CLI](https://andcze.mintlify.site/en/site/agents/codex.md)**
>
> `.codex/config.toml`.

> **[OpenCode](https://andcze.mintlify.site/en/site/agents/opencode.md)**
>
> `opencode.json`.

> **[Gemini CLI](https://andcze.mintlify.site/en/site/agents/gemini-cli.md)**
>
> `gemini mcp add` or `.gemini/settings.json`.

> **[Cursor](https://andcze.mintlify.site/en/site/agents/cursor.md)**
>
> `.cursor/mcp.json`.

> **[Built-in agent](https://andcze.mintlify.site/en/site/ai-editor.md)**
>
> In the cloud, nothing to install.

| Agent | Type | MCP file | Instructions file |
| - | - | - | - |
| Built-in ItemShop agent | cloud | — | — |
| [Claude Code](https://andcze.mintlify.site/en/site/agents/claude-code.md) | terminal | `.mcp.json` | `CLAUDE.md` |
| [OpenAI Codex CLI](https://andcze.mintlify.site/en/site/agents/codex.md) | terminal | `.codex/config.toml` | `AGENTS.md` |
| [OpenCode](https://andcze.mintlify.site/en/site/agents/opencode.md) | terminal | `opencode.json` | `AGENTS.md` |
| [Gemini CLI](https://andcze.mintlify.site/en/site/agents/gemini-cli.md) | terminal | `.gemini/settings.json` | `GEMINI.md` |
| [Cursor](https://andcze.mintlify.site/en/site/agents/cursor.md) | editor | `.cursor/mcp.json` | `AGENTS.md` |
| Windsurf | editor | `~/.codeium/windsurf/mcp_config.json` (global, `serverUrl` field) | `AGENTS.md` |
| Aider | terminal | no native MCP | `CONVENTIONS.md` |
| Any other MCP client | — | `.mcp.json` as in Claude Code | `AGENTS.md` |

**Windsurf**: in Cascade → MCP → "Open MCP config file" paste the configuration (`serverUrl` + header `Authorization: Bearer ${env:ITEMSHOP_TOKEN}`); Windsurf must see the `ITEMSHOP_TOKEN` variable.

**Aider** does not support MCP. It works on local files: start it with the project rules (`aider --read CONVENTIONS.md`, or let `.aider.conf.yml` with `read: [CONVENTIONS.md]` do it) and send changes with `npx itemshop deploy`.

## Connecting step by step

**1. Pick an agent**

**Workspace → Agent** → choose an agent from the list. The panel shows the steps, files and commands for it.

**2. Create a token**

In **Workspace → MCP** (or in the **Agent** tab) create a token with the scopes you need, e.g. `site:write` and `catalog:read`. You see the token only once.

**3. Copy the configuration**

The panel generates a ready command or file in your agent's format plus an instructions file. You can also download everything as a zip bundle (configuration, instructions, `.env.itemshop.example` and `ITEMSHOP-SETUP.md`).

**4. Pull the project and start**

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

Start the agent in that folder and describe the task.

> [!NOTE]
>
> **The token never goes into generated files.** Each format refers to the `ITEMSHOP_TOKEN` variable using its tool's own syntax (`${ITEMSHOP_TOKEN}`, `${env:ITEMSHOP_TOKEN}`, `{env:ITEMSHOP_TOKEN}`, `bearer_token_env_var`), so you can commit the files.

The CLI can generate the configuration without the panel too:

```bash theme={null}
npx itemshop mcp config --agent claude-code   # claude-code | codex | opencode | cursor | gemini
```

After `itemshop login` the CLI fetches the configuration from your workspace; without logging in it prints an offline version with the default MCP address. `--token <t>` embeds a literal token instead of the variable reference.

## Security

* The agent only sees tools from the groups you enabled in **Workspace → MCP**, and only within the token's scope (read or write).
* Orders are read-only and off by default.
* File changes land in the draft — they reach production after your approval (unless you change the [publishing rules](https://andcze.mintlify.site/en/site/workspace.md#publishing-rules)).
* Every tool call is visible in the MCP log and on the activity timeline. You can revoke the token at any time, and it also stops working when its creator loses permissions.

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

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


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