sapo-mcp
Model Context Protocol server for Sapo.vn POS & e-commerce platform.
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
Model Context Protocol server for Sapo.vn POS & e-commerce platform.
Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.
pos-online (51), web (31), pos-counter (15), analytics (10) — 2 read tools shared between pos-online and webSAPO_ALLOW_OPS (default: none); all destructive calls also require confirm: trueRequires Node.js 20 or newer. Verify with node --version.
Recommended for MCP clients (Claude Desktop, Cursor). Always pulls the latest published version:
npx -y sapo-mcp@latest --version
npm install -g sapo-mcp
sapo-mcp --version
sapo-mcp --help
npm install sapo-mcp
npx sapo-mcp --mode=pos-online
Create a Private App at developers.sapo.vn:
mystorename → mystorename.mysapo.netEdit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):
{
"mcpServers": {
"sapo": {
"command": "npx",
"args": ["-y", "sapo-mcp", "--mode=pos-online,web,analytics"],
"env": {
"SAPO_STORE": "mystorename",
"SAPO_API_KEY": "xxx",
"SAPO_API_SECRET": "yyy"
}
}
}
}
Restart Claude Desktop. Tools appear under the 🔌 plug icon.
Edit ~/.cursor/mcp.json or per-workspace .cursor/mcp.json:
{
"mcpServers": {
"sapo": {
"command": "npx",
"args": ["-y", "sapo-mcp", "--mode=pos-online,web"],
"env": {
"SAPO_STORE": "mystorename",
"SAPO_API_KEY": "xxx",
"SAPO_API_SECRET": "yyy"
}
}
}
}
npx @modelcontextprotocol/inspector \
-e SAPO_STORE=mystorename \
-e SAPO_API_KEY=xxx \
-e SAPO_API_SECRET=yyy \
npx -y sapo-mcp --mode=pos-online
Open the printed URL in a browser to inspect/invoke registered tools.
Use --mode=pos-online,web,analytics to register multiple modes (union of tools; shared tools registered once).
*One of SAPO_API_SECRET or SAPO_API_SECRET_FILE is required.
†HTTP-only. Token is enforced when SAPO_HTTP_HOST is not 127.0.0.1/localhost/::1.
Note:
pos-counterexcludes 5 internal-only endpoints (purchase_orders,purchase_returns,stock_adjustments,cash_transactions,cashbook) — these return HTTP 403 for Private App credentials and require an OAuth Partner App (post-1.0 roadmap).Analytics tools auto-paginate up to
SAPO_MAX_AUTO_PAGES; results carrytruncated: truewhen the cap is hit.
Verification levels for the 105 unique tools (last updated 2026-04-30):
These 2 tools may fail at runtime. POS shift management currently requires admin UI.
Click each section to expand the full tool list with status icons.
Customers (7)
list_customers, get_customer, search_customers, count_customers, list_customer_orderscreate_customer, update_customerCustomer Addresses (4)
list_customer_addresses, add_customer_address, update_customer_address, set_default_customer_addressProducts (read) (4)
list_products, get_product, search_products, count_productsVariants (read) (2)
list_variants_for_product, get_variantInventory (read) (1)
get_inventory_levelsOrders (4)
list_orders, get_order, count_orders, search_ordersOrder Transactions (2)
list_order_transactions, create_order_transactionFulfillments (4)
list_fulfillments_for_order, get_fulfillmentcreate_fulfillment, update_fulfillment_trackingRefunds (3)
list_refunds, get_refund, create_refund (create_refund destructive: SAPO_ALLOW_OPS=refund)Draft Orders (7)
list_draft_orders, get_draft_ordercreate_draft_order, update_draft_order, complete_draft_order, send_draft_order_invoice, delete_draft_order (destructive: delete)Price Rules (5)
list_price_rules, get_price_rulecreate_price_rule, update_price_rule, delete_price_rule (destructive: delete)Discount Codes (3)
list_discount_codes, create_discount_code, delete_discount_code (destructive: delete)Destructive (cancel/delete-strict) (4)
cancel_order, close_order, cancel_fulfillment (destructive: cancel)delete_customer, delete_variant (destructive: delete_strict)Store (1)
get_store_infoArticles (5)
list_articles, get_article, create_article, update_article, delete_article (destructive: delete)Blogs (5)
list_blogs, get_blog, create_blog, update_blog, delete_blog (destructive: delete)Pages (4)
list_pages, get_pageupdate_page_seo, delete_page (destructive: delete)Collections (10)
list_custom_collections, get_custom_collection, create_custom_collection, update_custom_collection, delete_custom_collection (destructive: delete)list_smart_collections, get_smart_collectionlist_collects, create_collect, delete_collect (destructive: delete)Script Tags (3)
list_script_tags, create_script_tag, delete_script_tag (destructive: delete)Products SEO (1)
update_product_seoVariants (read, shared) (2)
list_variants_for_product, get_variantLocations (2)
list_locations, get_locationPayment Methods (1)
list_payment_methodsInventory (write) (3)
adjust_inventory_level, connect_inventory_levelset_inventory_level (destructive: inventory_set)Variants (write) (1)
update_variantPOS Orders (2)
list_pos_orders, get_pos_order (uses /admin/orders?source_name=pos)Suppliers (2)
list_suppliers, get_supplierStock Transfers (2)
list_stock_transfers, get_stock_transferPOS Shifts (2)
list_pos_shifts, get_pos_shift (see Broken section above — endpoint returns HTML)All 10 are 🔵 composed (aggregate from multiple Sapo endpoints, no single endpoint to verify):
revenue_summary, top_products, top_customers, customer_ltv, tax_summary, online_vs_counter_breakdown, discount_usage_report, shift_report, inventory_low_stock, inventory_value
Destructive tools (cancel, delete, bulk-delete) are blocked by default. To enable specific categories:
# Allow order cancellation and standard deletes only
SAPO_ALLOW_OPS=cancel,delete npx sapo-mcp --mode=pos-online
Supported categories: cancel, delete, delete_strict, inventory_set, refund, shift_close, cashbook_write.
All destructive tool calls also require confirm: true in the tool arguments — this prevents accidental execution when an LLM calls the tool without explicit intent.
ENV credentials are visible to other processes via ps / /proc/<pid>/environ on shared hosts. Use SAPO_API_SECRET_FILE to pass the secret via a file instead of an env var where possible.
Note: full secret-file isolation (reading the secret only at startup, then clearing) is tracked for the post-1.0 roadmap.
Verify which Sapo API endpoints are available on your store before configuring tools.
# Read-only probe — safe to run against any store (GET only)
SAPO_STORE=mystore SAPO_API_KEY=xxx SAPO_API_SECRET=yyy npm run probe
# Schema drift check — same probe + Zod validation against fixtures
npm run canary
Write-probe (npm run probe:write) refuses to run unless SAPO_STORE contains test, dev, or sandbox — never against production.
Run as an HTTP server for remote MCP clients (e.g. GoClaw) or self-hosted Docker:
# Local-only (no auth required)
sapo-mcp --mode=pos-online --transport=http --port=3333
# Public bind (auth token required)
SAPO_HTTP_HOST=0.0.0.0 \
SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
sapo-mcp --mode=pos-online --transport=http
Endpoints:
Session model: Each MCP client gets a UUID session, isolated by an
McpServer instance. Idle sessions (SAPO_HTTP_SESSION_IDLE_MS) are
evicted automatically. Concurrent sessions cap at SAPO_HTTP_MAX_SESSIONS
(503 returned when full).
Security:
127.0.0.1 — loopback only. Token optional.SAPO_HTTP_HOST=0.0.0.0 (or any non-loopback) requires
SAPO_MCP_AUTH_TOKEN. The server refuses to start otherwise.SAPO_HTTP_CORS_ORIGINS
(CSV of origins, or * for all). Only enable when serving browser-based
agents.docker build -f examples/Dockerfile -t sapo-mcp:local .
docker run --rm -p 3333:3333 \
-e SAPO_STORE=mystore \
-e SAPO_API_KEY=xxx -e SAPO_API_SECRET=yyy \
-e SAPO_HTTP_HOST=0.0.0.0 \
-e SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
sapo-mcp:local
npm install
npm run typecheck # Type check
npm run lint # Lint
npm run test # Run tests
npm run build # Build for release
The 1.0.0 stable cut is gated on the following items, deferred from this release:
sapo://shop/info, sapo://orders/today, sapo://orders/pending, sapo://inventory/low-stock. Read-heavy data is more efficient as a Resource than repeated tool calls.respond_to_complaint, weekly_report, seo_optimize_product, customer_followup).pos-counter and 4 deferred finance/PO reports (cashflow_summary, pnl_summary, supplier_purchase_summary, daily_pos_report).See CHANGELOG.md for the per-version history.
MIT — See LICENSE
Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Sapo roda localmente via stdio.
Última verificação: 2026-10-27. Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.