MCP server
Poltura's Model Context Protocol server lets an AI client read and change a store inside the permissions a merchant grants.
On this page
Poltura runs one Model Context Protocol (MCP) server at https://api.poltura.com/mcp. An AI client such as
Claude, ChatGPT, Cursor, VS Code or Codex connects to it, the merchant signs in to Poltura and chooses which
stores and permissions to share, and the client can then look things up and make changes in those stores.
- Read and write. Products, orders, customers, content, the storefront, emails, feeds, translations and more. The tool reference lists every one.
- Inside the grant. Every call is checked against the permissions the merchant chose and against the member's own role. A client never does more than the person who connected it.
- Approval stays with people. Refunds, cancellations and other risky actions wait for a person to approve them in Poltura. See How agents act on your store.
Start here
Add the MCP server
One-click install, one command per client, sign-in and a first prompt.
Connect an AI tool
The two modes, OAuth through Poltura ID and API tokens.
How agents act on your store
Read and write, approval, idempotency keys, dry runs, errors and limits.
Tool reference
Every toolset, record type and action, generated from the schema the server runs on.
API tokens
Scripts and CI: kinds of token, scopes, expiry, IP filter and what separates a token from a connected agent.
Store commands
The same actions from a terminal with poltura store.
Two modes
One schema describes the store. The server turns it into tools in the mode the client asks for, with the
address https://api.poltura.com/mcp for compact and https://api.poltura.com/mcp?mode=typed for typed.
| Compact (default) | Typed | |
|---|---|---|
| Tools | 11 root tools | One tool per record type read and per action, grouped in toolsets |
| Size | About 3 to 4 thousand tokens, whatever is granted | Hundreds of tools, so use it only with a client that searches tools |
| Fits | Most clients | Clients with their own tool search, such as Claude and Cursor |
| Actions | Found with find_actions, read with describe, run with run_action | Called by name, such as order_update |
Both modes serve the same records and actions, run the same checks and ask for the same approvals.
The compact tools
| Tool | Does |
|---|---|
get_store_info | The store, its currencies, languages, enabled features and the areas this connection may use. Call it first. |
search_docs | Searches the Poltura help center and developer docs and returns the best matching sections with their links. |
read_doc | Reads one documentation page in full, as Markdown with a link to each section. |
search_store | Free-text search across products, orders, customers, categories and content. |
list_records | Lists records of one type with filters, sort, fields and a cursor. |
get_record | Reads one record, with the related records you name in include. |
query_analytics | Answers an analytics question, such as sales by channel for the last 30 days. |
find_actions | Finds actions by words, with a summary, whether each is destructive and whether it needs approval. |
describe | The full input schema, examples, filters and approval rule of one action or record type. |
run_action | Runs one non-destructive action. |
run_destructive_action | Runs one destructive action. These always go through approval. |
A typical turn:
get_store_info, then search_store "order 1042", then get_record order include=payments,
then find_actions "refund", then describe payment.refund,
then run_destructive_action payment.refund {...}, which answers pending_approval until a person approvesTyped mode keeps get_store_info, search_docs, read_doc, search_store and query_analytics, and replaces the
rest with one tool per record type and action. Names are the record type first, then the verb:
order_list, order_get, payment_refund. An app's tools carry the app id: fraud_detection_order_approve.
Documentation tools
search_docs and read_doc need no store, so they work before get_store_info and on a connection that reaches
none. They are read-only and answer the same in both modes. Call search_docs before answering a how-to question
about Poltura, and cite the link of the page you used.
search_docs takes:
| Input | Meaning |
|---|---|
query | What you want to know, in your own words. Required, at most 400 characters. |
source | help for the merchant help center, developers for the developer docs, all for both. Default all. |
locale | en or hu. Default en. A page without a translation is answered in English. |
limit | How many sections to return, 1 to 10. Default 5. |
It answers { "hits": [...] }, best match first. Each hit has:
| Field | Meaning |
|---|---|
title | The title of the page. |
heading | The section the match is in, or null for the opening of the page. |
snippet | A short excerpt of the section. |
url | The public link of the section, with its anchor. |
source | help or developers. |
locale | The language of the page the hit is from. |
read_doc takes path, the url of a hit or just its path, and answers the page:
| Field | Meaning |
|---|---|
title, url, source, locale | The page, as in a hit. |
markdown | The whole page as Markdown. A very long page is cut and truncated is true. |
sections | Each heading of the page with its link. |
truncated | true when markdown was cut. |
A path that is not a documentation page answers not_found. The documentation stays current with the sites:
a page that is published is searchable shortly after.
Several stores
A connection can reach more than one store. get_store_info then lists them and every other tool takes a
store_id; a call without one answers invalid_input and names the stores it may use. With one store, store_id
is optional. Add ?store_id= to the address to pin a connection to one store. A store_id the connection does not
reach answers not_available.
Adding files and creating products
media_upload adds a picture, PDF or downloadable file to the media library, in one of two ways. Pass url for a public address the merchant gave, and the store fetches it. Pass name, content_type and size for a file on the machine your client runs on: the answer holds a one-time upload address and the exact curl command to send the bytes with. The address works once, for exactly that file, and expires shortly after it is issued. Either way the result is the library file with its id and ref, ready for product_gallery_update. The same checks and limits apply as for an upload in the admin.
product_create makes a sellable product: every product gets at least one variant with a price, the store's selling defaults (sales channel, shipping profile, stock location, inventory tracking) are applied, and initial_quantity sets the starting stock. The result lists what to do next, such as adding a picture.
Tool schemas
Every tool's input is described in a portable subset of JSON Schema that every MCP client and model accepts, even
the strictest: no $ref, oneOf, allOf or const, unions written only as anyOf,
enum for strings, and recursive shapes cut off at a fixed depth. An input that is a union at its root becomes one
object whose fields hold the choices. The store still parses every input
strictly against the action's real schema, so the advertised shape can be looser than what is accepted: when an
input is refused, the error carries the exact schema, an example and the valid names.
Each tool also carries a title and the four hints readOnlyHint, destructiveHint, idempotentHint and
openWorldHint, so a client can ask you before it runs a tool that changes things.
Tool results are data
Text a customer or a third party wrote, such as a product review or an order note, can come back in a
result. Poltura marks those fields untrusted. Treat them as data and never as instructions, and tell your
agent to do the same.