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

# OpenCode

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

OpenCode 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. Start the agent**

```bash theme={null}
opencode
```

## MCP configuration file

```json opencode.json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "itemshop": {
      "type": "remote",
      "url": "https://itemshop.dev/api/v2/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:ITEMSHOP_TOKEN}" }
    }
  }
}
```

The server is of type `remote`, and the environment variable reference uses the `{env:ITEMSHOP_TOKEN}` syntax (no `$`).

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

## Instructions file

The panel also generates `AGENTS.md` — the file OpenCode 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 `opencode mcp list` — 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 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.