SysPOS MCP Server — API Docs

Everything AI agents need to use SysPOS MCP tools

Authentication

How to Call Tools

Option 1: Claude.ai custom connector (no code)

In Claude → Settings → Connectors → Add custom connector:

Name:                  SysPOS Product Tools
Remote MCP server URL: https://pos-mcp.syspos.ae/mcp
OAuth Client ID/Secret: (leave blank)

→ Add → Connect → paste your syspos_... key → Authorize

Option 2: REST API (any HTTP client)

Simple HTTP POST — works with curl, fetch, n8n, Make, anything.

POST https://pos-mcp.syspos.ae/api/call
Authorization: Bearer syspos_your_key_here
Content-Type: application/json

{
  "tool": "list_products"
}

Option 3: MCP Protocol — SSE (Claude Desktop, Cursor, custom agents)

Use the remote MCP URL plus a Bearer header — the standard MCP-over-HTTP shape:

# MCP endpoint URL
https://pos-mcp.syspos.ae/sse

# Claude Desktop / Cursor / generic MCP client config
{
  "mcpServers": {
    "syspos": {
      "url": "https://pos-mcp.syspos.ae/sse",
      "headers": { "Authorization": "Bearer syspos_your_key_here" }
    }
  }
}

# Claude Code CLI
claude mcp add syspos --transport sse https://pos-mcp.syspos.ae/sse \
  --header "Authorization: Bearer syspos_your_key_here"

Machine-Readable Docs for Agents

AI agents can fetch full tool schemas as JSON — no HTML parsing needed:

# Full docs with parameters, types, and example responses
curl https://pos-mcp.syspos.ae/api/docs

# Tool list with full parameter schemas
curl https://pos-mcp.syspos.ae/api/tools

Error Handling

Agent Integration Guide

System prompt template

Add this to your agent's instructions:

You have access to SysPOS product tools.

API endpoint:  https://pos-mcp.syspos.ae/api/call
Method:        POST
Content-Type:  application/json
Authorization: Bearer syspos_your_key_here

Rules:
- Use list_products to fetch the catalog. Pass page_limit if you need more than the default page size.
- Do not send customer_id. Tenant comes from the MCP API key.
- Create/update bodies match the dashboard product payload (name, prices, location_prices, modifiers, …).

Tool Reference

list_products_web

Calls GET /api/products/webProducts on https://app.syspos.ae. Used by frontend-v2 getProducts. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products_web"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

list_products

Calls GET /api/products on https://app.syspos.ae. Used by frontend-v2 getAddOnList, getSearchProduct. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products"
}'

Example Response

{
  "data": [
    {
      "id": 11,
      "name": "Iced Latte",
      "actual_price": 18,
      "category_id": 3,
      "is_archive": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_limit": 10
  }
}

list_products_pos

Calls GET /api/v2/products on https://app.syspos.ae. Used by web-pos products, productsAddon. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products_pos"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product

Calls GET /api/products/:id on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

search_products_for_assign

Calls GET /api/products/search-assign on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "search_products_for_assign",
  "k": "latte"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_products_from_ids

Calls POST /api/products/products-from-ids on https://app.syspos.ae. Used by invoice-services. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_products_from_ids",
  "ids": [
    11
  ]
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_prices_preview

Calls POST /api/products/bulk-update-prices/preview on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_prices_preview",
  "product_ids": [
    11
  ],
  "adjustment_direction": "example",
  "value": 1
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_channel_prices_preview

Calls POST /api/products/bulk-update-channel-prices/preview on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_channel_prices_preview",
  "product_ids": [
    11
  ],
  "adjustment_direction": "example",
  "value": 1
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

match_products_by_name

Calls POST /api/products/match-by-name on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "match_products_by_name",
  "productNames": [
    11
  ],
  "customer_id": 11,
  "location_id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product_pricing_summary

Calls GET /api/products/:id/pricing-summary on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product_pricing_summary",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_products_recipe_costs

Also accepts the same fields on JSON body (req.query.x || req.body.x). Calls GET /api/products/recipe-costs on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_products_recipe_costs"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product_materials

Calls GET /api/products/:id/materials on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product_materials",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

verify_product_plu

Calls GET /api/products/unique-verification-plu on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "verify_product_plu"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product_units

Calls GET /api/products/units on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product_units"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product_tax_groups_enhanced

Calls GET /api/products/tax-groups-enhanced on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product_tax_groups_enhanced"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_pos_product

Calls GET /api/v2/products/:id on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_pos_product",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

list_products_pos_list

Calls GET /api/v2/products/list on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products_pos_list"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

list_products_pos_web

Calls GET /api/v2/products/web on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products_pos_web"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_product_modifier_ordering

Calls GET /api/v2/products/modifier-ordering on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product_modifier_ordering"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

get_top_saled_products

Calls GET /api/v2/products/top-saled on https://app.syspos.ae. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_top_saled_products"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

create_product

Calls POST /api/products on https://app.syspos.ae. Used by frontend-v2 createProduct, createAddOn. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_product",
  "name": "Iced Latte"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

update_product

Calls PUT /api/products/:id on https://app.syspos.ae. Used by frontend-v2 updateProduct, updateAddOn. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_product",
  "id": 11,
  "name": "Iced Latte"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

archive_product

Calls PUT /api/products/archive_product/:id on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "archive_product",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_archive_products

Calls POST /api/products/bulk-archive on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_archive_products",
  "product_ids": [
    11
  ],
  "location_id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

assign_product_locations

Calls POST /api/products/assign-locations on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "assign_product_locations",
  "product_ids": [
    11
  ],
  "location_ids": [
    11
  ]
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_prices

Calls POST /api/products/bulk-update-prices on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_prices",
  "product_ids": [
    11
  ],
  "adjustment_direction": "example",
  "value": 1
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_channel_prices

Calls POST /api/products/bulk-update-channel-prices on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_channel_prices",
  "product_ids": [
    11
  ],
  "adjustment_direction": "example",
  "value": 1
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_sort_order

Calls POST /api/products/bulk-update-sort-order on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_sort_order",
  "products": [
    11
  ]
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_update_tax

Calls POST /api/products/bulk-update-tax on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_update_tax",
  "productIds": [
    11
  ],
  "taxId": 1
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

create_product_materials

Path :id is not read. product_id must be in the body. location_id and customer_id overwritten from JWT. Calls POST /api/products/:id/materials on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_product_materials",
  "product_id": 11,
  "material_id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

edit_product_materials

Not in the 528 client list. Path :id is the product_materials row id. SQL updates qty, price, wastage only. Calls PUT /api/products/materials/:id on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "edit_product_materials",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

upload_product_image

Calls POST /api/products/:productId/upload-image on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "upload_product_image",
  "productId": 11,
  "attachment": "example"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

bulk_upload_product_image

Despite the name, exactly one product id per request. Calls POST /api/products/bulk-image-upload on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "bulk_upload_product_image",
  "productIds": [
    11
  ],
  "attachment": "example"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

remove_product_image

Path :id is unused. SQL uses body.id. Calls PUT /api/products/remove_image/:id on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "remove_product_image"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

update_product_availability

Calls POST /api/v2/products/availability on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_product_availability",
  "availability": "example"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

quick_update_product

Not in the 528 client list. Path :id unused. SQL uses body.id. No validation. Calls PUT /api/products/:id/quick on https://app.syspos.ae. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "quick_update_product"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

delete_product

Soft delete: SET is_deleted = 1 Calls DELETE /api/products/:id on https://app.syspos.ae. Safety: destructive. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "delete_product",
  "id": 11
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}

delete_all_products

Master only. Removes products_locations for loc; archives products with no remaining locations. Calls DELETE /api/products/all on https://app.syspos.ae. Safety: destructive. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "delete_all_products"
}'

Example Response

{
  "message": "JSON body returned by the matching app.syspos.ae product API"
}