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

# 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](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. Add the MCP server**

With one command:

```bash theme={null}
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**

```bash theme={null}
gemini
```

## MCP configuration file

```json .gemini/settings.json theme={null}
{
  "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:

```bash theme={null}
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](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.