# Add the MCP server (/ai/install)

The Poltura MCP server lets an AI tool read and change your stores, inside the permissions you choose when you sign
in. Pick your tool; every tool uses the address `https://api.poltura.com/mcp`.

Not a developer? [Connect Poltura to Claude or ChatGPT without a terminal →](https://docs.poltura.com/en/assistant/connect-ai-apps/)

<ClientTabs>
<ClientTab value='claude-code'>

```bash
claude mcp add --transport http poltura https://api.poltura.com/mcp
```

Then run `/mcp` in Claude Code, pick **poltura** and choose **Authenticate**. Your browser opens the Poltura sign-in.

</ClientTab>
<ClientTab value='codex'>

```bash
codex mcp add poltura --url https://api.poltura.com/mcp
codex mcp login poltura
```

The login opens your browser. The server is saved in `~/.codex/config.toml`.

</ClientTab>
<ClientTab value='claude'>

On claude.ai or in Claude Desktop:

1. Open **Customize**, then **Connectors**, and select **+ Add**, then **Add custom connector**.
2. Name it `Poltura`, paste `https://api.poltura.com/mcp` and select **Add**.
3. Sign in when the Poltura page opens.
4. In a chat, select **+**, open **Connectors** and switch **Poltura** on.

On Team and Enterprise plans an owner adds the connector under **Organization settings, Connectors** first.
Connectors added on the web also work in the Claude mobile apps.

</ClientTab>
<ClientTab value='chatgpt'>

On chatgpt.com in a browser:

1. Open **Plugins**, select **+**, then **Add custom MCP server**.
2. Name it `Poltura`, paste `https://api.poltura.com/mcp` as the **Server URL** and choose **OAuth**.
3. Accept the warning, select **Create as a plugin**, then install it and sign in.
4. In a chat, type `@` and pick **Poltura**.

Changes need a Business, Enterprise or Edu workspace; on Pro the plugin can only read.

</ClientTab>
<ClientTab value='cursor'>

<McpInstallButton client='cursor' />

Or add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one
project):

```json
{
  "mcpServers": {
    "poltura": { "url": "https://api.poltura.com/mcp" }
  }
}
```

Open **Cursor Settings**, then **MCP**, and connect **poltura** to sign in.

</ClientTab>
<ClientTab value='vscode'>

<McpInstallButton client='vscode' />

Or add the server to `.vscode/mcp.json`:

```json
{
  "servers": {
    "poltura": { "type": "http", "url": "https://api.poltura.com/mcp" }
  }
}
```

Select **Start** above the entry. VS Code asks whether the server may sign in: allow it, and your browser opens
the Poltura sign-in.

</ClientTab>
<ClientTab value='cli'>

`poltura mcp connect` writes the configuration of every tool it finds on this machine, or of the one you name. It
never writes a token. (Not published to npm yet.)

```bash
poltura mcp connect
poltura mcp connect cursor --global
```

| Option                | Does                                                                              |
| --------------------- | --------------------------------------------------------------------------------- |
| `claude`, `cursor`, `vscode`, `codex` | The tool to configure. Without one, every tool found here.        |
| `--global`            | The tool's user-level config instead of this project's (not for VS Code).          |
| `--mode typed`        | One tool per record type and action, for clients that search tools themselves.    |
| `--store <id>`        | Pin the connection to one store.                                                  |
| `--token-env [name]`  | Use an API token from this variable (default `POLTURA_TOKEN`) instead of sign-in. |
| `--dry-run`           | Print the entry and change nothing.                                               |

It prints the next step for each tool, such as `Open /mcp in Claude Code and sign in to Poltura.`

</ClientTab>
</ClientTabs>

For scripts and CI, skip the sign-in and send an [API token](/api/tokens) as a bearer header. The token options
for each client are on [Connect an AI tool](/ai/connect#use-an-api-token).

## Sign in and choose access [#sign-in-and-choose-access]

The first call opens one page in Poltura ID, titled with the tool's name, such as "Cursor wants to access your
stores".

**Sign in** to Poltura, if you are not already.

**Check who is asking.** A tool Poltura knows, such as Claude, Claude Code, Codex or VS Code, shows **Verified by
Poltura** with its address. Any other app gets a warning instead: continue only if you started it yourself.

**Pick the stores** the tool may reach. **Grant access to all stores** includes stores you add later.

**Switch on permissions** by area. Each row is tagged **Can only see**, **Can change**, **Can delete** or
**Personal data**. Start with reading; you can connect again to add more.

**Choose the expiry** (30 days by default) and select **Allow access**. A write permission first asks you to
confirm it's you.


The tool then holds a short-lived token it refreshes by itself. It never does more than your own role allows, and
deletes and refunds always wait for a person in **Agent requests**. See
[How agents act on your store](/ai/agents#approval).

## Try a first prompt [#try-a-first-prompt]

Ask in a new chat:

```text
Use Poltura. Tell me my sales for the last 7 days by channel,
and the five products that sold most.
```

Then try a change, which shows how approval works:

```text
Find order 1042 in Poltura and prepare a full refund.
Show me what would happen before anything runs.
```

The refund comes back as a dry run, and running it for real waits in **Agent requests** until you approve it.

## Troubleshooting [#troubleshooting]

| You see                                       | Do this                                                                                                        |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| The browser never opens                       | Claude Code: run `/mcp` and choose **Authenticate** again. Codex: run `codex mcp login poltura`.               |
| "This request has expired"                    | Start the sign-in again from the tool.                                                                         |
| `insufficient_scope`                          | The grant lacks a permission. Connect again; the page marks the one the call asked for.                        |
| `access_disabled`                             | An owner turned off **Allow AI agents (MCP)** in the store, or third-party apps and agents in the organization. |
| The tool lists hundreds of tools or slows down | Use the default address. `?mode=typed` is only for clients that search tools themselves.                      |
| A work network blocks the connection          | Ask your IT team to allow `api.poltura.com`.                                                                   |

To remove a tool, revoke it in Poltura ID under **Account, Connected apps**, or in the admin under
**Settings, AI agents**. It stops working within 30 seconds. Every refusal code is on [Access errors](/api/errors).

## Next [#next]

- [How agents act on your store](/ai/agents): Approval, idempotency keys, dry runs, errors and limits.
- [Tool reference](/ai/reference): Every toolset, record type and action.
- [Connect an AI tool](/ai/connect): The two modes, OAuth in detail and API tokens.