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

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

claude mcp add or .mcp.json.

OpenAI Codex CLI

.codex/config.toml.

OpenCode

opencode.json.

Gemini CLI

gemini mcp add or .gemini/settings.json.

Cursor

.cursor/mcp.json.

Built-in agent

In the cloud, nothing to install.

Agent	Type	MCP file	Instructions file
Built-in ItemShop agent	cloud	—	—
Claude Code	terminal	.mcp.json	CLAUDE.md
OpenAI Codex CLI	terminal	.codex/config.toml	AGENTS.md
OpenCode	terminal	opencode.json	AGENTS.md
Gemini CLI	terminal	.gemini/settings.json	GEMINI.md
Cursor	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

   export ITEMSHOP_TOKEN=iswt_...
   npx itemshop login --shop <shop-id>
   npx itemshop pull
   

   Start the agent in that folder and describe the task.

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:

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).
• 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

Tools, scopes and the stdio bridge.

Agent skills

Ready-made ItemShop knowledge for your agent.