Add the MCP server
Add Poltura to Claude Code, Codex, Claude, ChatGPT, Cursor or Visual Studio Code, sign in, and run a first prompt.
On this page
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 →
claude mcp add --transport http poltura https://api.poltura.com/mcpThen run /mcp in Claude Code, pick poltura and choose Authenticate. Your browser opens the Poltura sign-in.
codex mcp add poltura --url https://api.poltura.com/mcp
codex mcp login polturaThe login opens your browser. The server is saved in ~/.codex/config.toml.
On claude.ai or in Claude Desktop:
- Open Customize, then Connectors, and select + Add, then Add custom connector.
- Name it
Poltura, pastehttps://api.poltura.com/mcpand select Add. - Sign in when the Poltura page opens.
- 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.
On chatgpt.com in a browser:
- Open Plugins, select +, then Add custom MCP server.
- Name it
Poltura, pastehttps://api.poltura.com/mcpas the Server URL and choose OAuth. - Accept the warning, select Create as a plugin, then install it and sign in.
- In a chat, type
@and pick Poltura.
Changes need a Business, Enterprise or Edu workspace; on Pro the plugin can only read.
Or add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one
project):
{
"mcpServers": {
"poltura": { "url": "https://api.poltura.com/mcp" }
}
}Open Cursor Settings, then MCP, and connect poltura to sign in.
Or add the server to .vscode/mcp.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.
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 on npm yet
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.
For scripts and CI, skip the sign-in and send an API token as a bearer header. The token options for each client are on Connect an AI tool.
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.
Try a first prompt
Ask in a new chat:
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:
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
| 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.