# Pancake POS MCP

> The Pancake POS MCP server: connect Claude, Codex or Cursor to a shop to create orders, check revenue, look up stock and issue vouchers in plain language.


---

Source: https://crm.pancake.id/developers/mcp/overview.md

# Overview

**MCP** (Model Context Protocol) is an open standard that lets AI assistants call external tools. The Pancake POS MCP server turns the [Open API](/developers/api/en) into tools that Claude, Codex, Cursor and others can use: you ask in plain language, the AI calls the right API on your shop and answers with real results.

```text
https://mcp-pos.pancake.biz/mcp
```

## What the AI can do

| You say | The AI does |
|---|---|
| "Create an order: 3 size-M shirts for Hoa" | Create, edit and cancel orders; print shipping labels, get tracking numbers, handle returns |
| "What's revenue this week compared with last week?" | Sales reports, profit, period comparisons, best sellers |
| "What's in stock at the Ho Chi Minh City branch?" | Stock by warehouse, low-stock items, in/out history, stocktaking |
| "Change the white t-shirt price to 220k" | Add and edit products, variations, combos, categories |
| "How many orders has Lan placed?" | Customer profiles, membership tiers, reward points, purchase history |
| "Create 100 vouchers worth 50k, valid for a week" | Promotions, single or bulk vouchers |
| "Create a purchase: 100 boxes of cake from supplier ABC at 80k" | Purchases, suppliers, debts |
| "How much does Hung still owe?" | Cash book, customer and supplier debts, e-invoices |
| "How are recent marketplace returns looking?" | Marketplace products and orders, livestream sessions |

The AI can only do what your API key allows (see [Permissions & security](/developers/mcp/en/permissions)).

## How it works

1. You add the MCP server to your client (Claude Desktop, Claude Code, Codex, Cursor…) with a Pancake POS API key. See [Connect](/developers/mcp/en/connect).
2. The client receives a list of tools, one per business area: for example `pos_order` to read orders and `pos_order_write` to create and edit them. See [Tools](/developers/mcp/en/tools).
3. When you ask something, the AI picks a tool, looks up the parameters it needs with `pos_describe`, then calls the Open API with your key.
4. For actions that write data, the client asks you to confirm before running them (depending on its settings).

The MCP server stores no shop data; every call goes straight to the Open API and the result goes back to the AI.

## Pick an integration

| You need | Use |
|---|---|
| Questions and quick actions on your shop through an AI assistant | MCP (this section) |
| Automatic data sync between POS and another system | [Open API](/developers/api/en) |
| Buttons, info blocks or pages right inside the POS interface | [POS Apps](/developers/apps/en) |
| An AI that writes a POS App for you | The POS Apps toolkit's MCP (`pos-app mcp`), see [Build with AI](/developers/apps/en/ai-guide) |

---

Source: https://crm.pancake.id/developers/mcp/connect.md

# Connect

The MCP server address:

```text
https://mcp-pos.pancake.biz/mcp
```

## 1. Get an API key

Prefer an **account API key**: the AI can then do only what you yourself are allowed to do in each shop.

1. Open the **Account** page in Pancake POS, **API Key** section, and click **Create**.
2. Give it a memorable name, for example "Claude".
3. Copy the key right away: it is shown only once.

A shop API key also works (**Settings › Apps › Webhook/API**, **API Key** tab), but it has full access to the shop. Compare the two in [Authentication](/developers/api/en/authentication).

## 2. Add it to your client

### Claude Desktop

1. Open **Settings › Connectors › Add custom connector**.
2. Paste `https://mcp-pos.pancake.biz/mcp` as the URL, give it a name (for example "Pancake POS") and click **Add**.
3. Claude opens your browser on the Pancake POS MCP authorization page. Paste your API key and click **Authorize**. The browser closes when done.

Older Claude Desktop versions without Connectors: open **Settings › Developer › Edit Config** and add the block below (Node.js is required because `mcp-remote` acts as a bridge):

```json
{
  "mcpServers": {
    "pancake-pos": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.18", "https://mcp-pos.pancake.biz/mcp", "--header", "X-Api-Key:API_KEY"]
    }
  }
}
```

Save the file, quit Claude Desktop completely (macOS: `Cmd+Q`, not just closing the window) and open it again.

### Claude Code

```bash
claude mcp add --transport http -s user pancake-pos https://mcp-pos.pancake.biz/mcp --header "X-Api-Key: API_KEY"
```

Check with `claude mcp list` (you should see `pancake-pos … ✓ Connected`). In a session, type `/mcp` to see the `pos_*` tools.

### Codex

Add to `~/.codex/config.toml` (shared by the Codex app, IDE extension and CLI):

```toml
[mcp_servers.pancake-pos]
url = "https://mcp-pos.pancake.biz/mcp"
http_headers = { "X-Api-Key" = "API_KEY" }
```

Codex uses `http_headers`, not the `headers` field other clients use.

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pancake-pos": {
      "url": "https://mcp-pos.pancake.biz/mcp",
      "headers": { "X-Api-Key": "API_KEY" }
    }
  }
}
```

### Other clients

Any client that supports MCP over HTTP (Streamable HTTP) can connect:

- URL: `https://mcp-pos.pancake.biz/mcp`
- Authentication: the `X-Api-Key: API_KEY` header (or `Authorization: Bearer API_KEY`), or OAuth if the client supports it (the client opens the authorization page for you to paste the key).

## 3. Try it

Start a new conversation and type:

- "List my 5 most recent orders"
- "What's today's revenue?"
- "Which products are running low?"

The first time, the client asks whether to allow the tool call: choose **Allow**. Seeing your order list means you are connected.

If your account has several shops, name the shop in your request, or ask "Which shops do I have?" first.

## Troubleshooting

| Symptom | Fix |
|---|---|
| No `pos_*` tools | Quit and reopen the client; check the URL ends with `/mcp` |
| The authorization page says the API key is invalid | Copy the full key again; create a new key if it was revoked |
| The AI reports missing permissions | Account keys follow your permissions in the shop; ask an admin to grant more |
| `npx` does not run (older Claude Desktop) | Install Node.js 18 or later |
| Codex does not connect | Check you used `http_headers`, not `headers` |

Need help setting up? Contact the Pancake team.

---

Source: https://crm.pancake.id/developers/mcp/permissions.md

# Permissions & security

## How far the AI can go

The AI can only do what the **API key** allows:

| API key | What the AI can do |
|---|---|
| Account API key (recommended) | Exactly your permissions in each shop: role, warehouses, department, work hours, allowed IPs |
| Shop API key | Full Open API access to that shop |

To let the AI only view data, create the API key from an account that only has view permissions, or grant read access when connecting with OAuth (below).

## Read and write

Each business area has separate read and write tools (`pos_order` and `pos_order_write`, see [Tools](/developers/mcp/en/tools)). Tools are annotated following the MCP standard:

- **Read tools** (`readOnlyHint`): only view data. Clients may allow them to run automatically.
- **Write tools**: create, edit and cancel data. Some actions cannot be undone, such as placing an automated call to a customer (`pos_auto_voice`). Clients are told to ask you before running them.

Keep your client asking for confirmation before every write, and read the parameters the AI is about to send before you agree, especially for bulk actions.

## Two ways to authenticate

| Method | Used by | Limits |
|---|---|---|
| **OAuth** | Claude Desktop (Connectors) and clients that support OAuth: the client opens an authorization page where you paste your API key | The client requests `pos:read` (read) and/or `pos:write` (write); the authorization page lists them. The server blocks tools outside the granted access |
| **Header** `X-Api-Key` | Claude Code, Codex, Cursor, file-based configs | The API key's full permissions; the MCP server does not split read and write |

With OAuth, the API key is encrypted inside the token the MCP server issues; the client cannot read the original key.

## Where data goes

- The MCP server stores no shop data: every call goes straight to the Open API and the result goes back to the client.
- The results (orders, customers, revenue…) are sent by the client to the AI model provider (Anthropic, OpenAI…) under that provider's policies. Think before letting the AI read sensitive customer data.

## Revoking access

1. Revoke the API key: **Account › API Key** (account keys) or delete it in **Settings › Apps › Webhook/API** (shop keys). Every client using that key loses access immediately.
2. Remove the server from the client: delete the connector in Claude Desktop, run `claude mcp remove pancake-pos` in Claude Code, or remove the config block in Codex or Cursor.

Use a separate API key per client so you can revoke them one at a time.

---

Source: https://crm.pancake.id/developers/mcp/tools.md

# Tools

The MCP server builds its tools from the [Open API](/developers/api/en): each endpoint group (business area) becomes a tool named `pos_<area>`. Areas with both read and write actions are split into two tools, the write tool ending in `_write`, so clients can allow each kind separately.

Each tool takes an `action` parameter that selects the operation, for example `pos_order` with `action: "list"` to list orders. The list below is generated from the current Open API, the same list your client receives.

## Looking up parameters

To keep the tool list small, clients only receive action names. Before calling an action, the AI calls `pos_describe` to get its full parameters and description:

```json
{ "tool": "pos_order", "action": "list" }
```

You never need to call `pos_describe` yourself; the AI does it when needed.

## Available tools

| Tool | Access | Area | Actions |
|---|---|---|---|
| `pos_address` | Read | Address | 3 |
| `pos_ads_manager` | Read | Ads Manager | 4 |
| `pos_auto_voice` | Write | Auto Voice | 1 |
| `pos_call_later` | Read | Call Later | 1 |
| `pos_call_later_write` | Write | Call Later | 1 |
| `pos_combo` | Read | Combo | 1 |
| `pos_combo_write` | Write | Combo | 1 |
| `pos_customer` | Read | Customer | 5 |
| `pos_customer_write` | Write | Customer | 4 |
| `pos_debt` | Read | Debt | 1 |
| `pos_e_commerce` | Read | eCommerce | 4 |
| `pos_e_invoice` | Read | E-Invoice | 1 |
| `pos_employee` | Read | Employee | 1 |
| `pos_export` | Read | Export | 2 |
| `pos_export_write` | Write | Export | 2 |
| `pos_livestream` | Read | Livestream | 1 |
| `pos_lot` | Read | Lot | 1 |
| `pos_order` | Read | Order | 9 |
| `pos_order_tag` | Read | Order tag | 2 |
| `pos_order_tag_write` | Write | Order tag | 2 |
| `pos_order_write` | Write | Order | 7 |
| `pos_product` | Read | Product | 7 |
| `pos_product_write` | Write | Product | 8 |
| `pos_promotion` | Read | Promotion | 1 |
| `pos_promotion_write` | Write | Promotion | 3 |
| `pos_purchase` | Read | Purchase | 2 |
| `pos_purchase_write` | Write | Purchase | 3 |
| `pos_reconciliation` | Read | Reconciliation | 1 |
| `pos_shop` | Read | Shop | 2 |
| `pos_statistics` | Read | Statistics | 4 |
| `pos_statistics_customer_analytics` | Read | Statistics customer analytics | 1 |
| `pos_statistics_inventory_analytics` | Read | Statistics inventory analytics | 2 |
| `pos_stocktaking` | Read | Stocktaking | 2 |
| `pos_stocktaking_write` | Write | Stocktaking | 2 |
| `pos_supplier` | Read | Supplier | 1 |
| `pos_transaction` | Read | Transaction | 2 |
| `pos_transaction_write` | Write | Transaction | 2 |
| `pos_voucher` | Read | Voucher | 2 |
| `pos_voucher_write` | Write | Voucher | 1 |
| `pos_warehouse` | Read | Warehouse | 2 |
| `pos_warehouse_transfer` | Read | Warehouse Transfer | 3 |
| `pos_warehouse_transfer_write` | Write | Warehouse Transfer | 2 |
| `pos_warehouse_write` | Write | Warehouse | 2 |
| `pos_webhook` | Write | Webhook | 1 |

Each tool maps to a group in the [Open API reference](/developers/api/en); parameters and returned data match the corresponding endpoints.