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

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

2. Set the environment variable

   The configuration never contains the token — it refers to the ITEMSHOP_TOKEN variable.

   export ITEMSHOP_TOKEN=iswt_...
   
3. Pull the site project

   In an empty folder download the current draft (CLI):

   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

   codex
   

MCP configuration file

.codex/config.toml

[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:

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

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.

All agents

Comparison and shared rules.

MCP

Tools and scopes.