Gemini CLI

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

Gemini 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. Add the MCP server

   With one command:

   gemini mcp add --transport http --scope project --header 'Authorization: Bearer ${ITEMSHOP_TOKEN}' itemshop https://itemshop.dev/api/v2/mcp
   

   or save the file from the next section.

5. Start the agent

   gemini
   

MCP configuration file

.gemini/settings.json

{
  "mcpServers": {
    "itemshop": {
      "httpUrl": "https://itemshop.dev/api/v2/mcp",
      "headers": { "Authorization": "Bearer ${ITEMSHOP_TOKEN}" }
    }
  }
}

The httpUrl field selects the Streamable HTTP transport (a plain url would mean SSE). The single quotes around the header stop your shell from expanding the variable — Gemini CLI expands it 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 gemini

Instructions file

The panel also generates GEMINI.md — the file Gemini 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 gemini 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.