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

# OpenAI Codex CLI

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

OpenAI Codex CLI 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}
codex
```

## MCP configuration file

```toml .codex/config.toml theme={null}
[mcp_servers.itemshop]
url = "https://itemshop.dev/api/v2/mcp"
bearer_token_env_var = "ITEMSHOP_TOKEN"
```

The project config `.codex/config.toml` works in projects you marked as trusted. Prefer global settings? Append the same section to `~/.codex/config.toml`. `bearer_token_env_var` names the variable, not the token itself.

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

## Instructions file

The panel also generates `AGENTS.md` — the file OpenAI Codex CLI 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 `codex 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.