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 Owner Agent
Remote MCP server URL: https://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://mcp.syspos.ae/api/call
Authorization: Bearer syspos_your_key_here
Content-Type: application/json

{
  "tool": "get_executive_daily_brief",
  "compare_with": "yesterday"
}

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://mcp.syspos.ae/sse

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

# Claude Code CLI
claude mcp add syspos --transport sse https://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://mcp.syspos.ae/api/docs

# Tool list with full parameter schemas
curl https://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 restaurant analytics tools.

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

Rules:
- Always call "resolve_locations" first when a user mentions a branch by name.
- Default date is today unless the user specifies otherwise.
- When asked "how did today go?", use "get_executive_daily_brief" with compare_with: "yesterday".

Tool Reference

resolve_locations

Resolve branch/location names to IDs. Use this FIRST when the user refers to a location by name (e.g. "DHA branch", "Mall of Emirates", "downtown store") instead of by ID. Returns matching locations with their IDs, so you can pass the correct location_ids to other tools. Also useful to list all accessible locations for the tenant.

Parameters

Example Request

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

Example Response

{
  "query": "downtown",
  "total": 2,
  "locations": [
    {
      "location_id": 1,
      "name": "Downtown Branch",
      "brand": "My Restaurant",
      "is_primary": true,
      "payment_provider": "ngenius",
      "customer_id": 10
    }
  ],
  "hint": "Use the location_id values from above when calling other tools."
}

get_executive_daily_brief

Get today's executive sales summary for the owner. Returns total orders, gross/net sales, discounts, refunds, AOV, tips, payment breakdown, and optional comparison with yesterday/last week/7-day average. This is the owner's "What happened today?" snapshot.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_executive_daily_brief",
  "date": "2025-01-15",
  "location_ids": [
    1,
    2
  ],
  "compare_with": "yesterday"
}'

Example Response

{
  "date": "2025-03-15",
  "summary": {
    "total_orders": 142,
    "gross_sales": 15200,
    "net_sales": 13800,
    "total_revenue": 14500,
    "total_vat": 700,
    "total_discounts": 450,
    "total_items": 380,
    "aov": 102.11,
    "total_guests": 95,
    "total_tips": 120,
    "refunded_orders": 3,
    "refunded_amount": 85
  },
  "payment_breakdown": {
    "cash": 6200,
    "card": 8300
  }
}

get_multi_location_performance

Compare performance across all branches/locations. Returns per-location: revenue, orders, AOV, guest count, growth %, and ranking. Helps owners identify top/bottom performers and allocate resources.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_multi_location_performance",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ],
  "sort_by": "revenue"
}'

Example Response

{
  "period": {
    "start": "2025-03-01",
    "end": "2025-03-31"
  },
  "locations": [
    {
      "location_id": 1,
      "location_name": "Downtown",
      "revenue": 45000,
      "orders": 520,
      "aov": 86.54,
      "guests": 380,
      "growth_pct": 12.5,
      "rank": 1
    }
  ]
}

get_sales_trend_and_anomalies

Explain "why sales changed." Shows trend lines, anomalies, biggest drivers up/down, and which categories/items caused movement. Owners don't want raw numbers only — they want causality hints.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_sales_trend_and_anomalies",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "group_by": "day",
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "current": {
      "start": "2025-03-01",
      "end": "2025-03-07"
    },
    "previous": {
      "start": "2025-02-22",
      "end": "2025-02-28"
    }
  },
  "grouped_by": "day",
  "overall": {
    "current_revenue": 42000,
    "previous_revenue": 38000,
    "revenue_change_pct": 10.53
  },
  "trend": [
    {
      "label": "2025-03-01",
      "revenue": 6200,
      "orders": 72
    }
  ],
  "anomalies": [],
  "top_movers": {
    "biggest_gainers": [],
    "biggest_decliners": []
  }
}

get_hourly_sales_heatmap

Hourly and day-of-week sales heatmap: shows peak hours, slow periods, covers (guests) density, and best/worst time slots. Helps owners optimize staffing and promotions.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_hourly_sales_heatmap",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-01",
    "end": "2025-03-14"
  },
  "heatmap": [
    {
      "hour": 12,
      "day_of_week": "Monday",
      "revenue": 1200,
      "orders": 18,
      "guests": 12
    }
  ],
  "peak_hours": [
    {
      "hour": 13,
      "avg_revenue": 1450
    }
  ],
  "slow_hours": [
    {
      "hour": 15,
      "avg_revenue": 280
    }
  ]
}

get_payment_mix_analysis

Payment method breakdown and trends: cash vs card vs digital, per-location payment preferences, daily payment trends. Helps owners understand payment behavior and plan for cash handling, terminal needs.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_payment_mix_analysis",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-01",
    "end": "2025-03-31"
  },
  "summary": {
    "cash": {
      "amount": 22000,
      "pct": 42
    },
    "card": {
      "amount": 28000,
      "pct": 54
    },
    "other": {
      "amount": 2000,
      "pct": 4
    }
  }
}

get_profit_leakage_alerts

Detect suspicious operational leakage: unusual refunds, voids, high discount usage, inventory variance, cash mismatches, manager overrides, and low-margin items. One of the most valuable tools for owners — highlights where money may be leaking.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_profit_leakage_alerts",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-08",
    "end": "2025-03-15"
  },
  "total_alerts": 2,
  "critical_alerts": 1,
  "alerts": [
    {
      "type": "high_refund_rate",
      "severity": "critical",
      "location": "Mall Branch",
      "detail": "8.5% refund rate"
    }
  ]
}

get_branch_health_score

One-number operational health overview per branch. Composite score from: sales performance, stock health, refund anomalies, discount usage, void rate, and shift execution. Excellent for dashboards and quick owner assessments.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_branch_health_score",
  "date": "2025-01-15",
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "date": "2025-03-15",
  "total_branches": 3,
  "avg_health_score": 72.5,
  "branches": [
    {
      "location_id": 1,
      "location_name": "Downtown",
      "health_score": 85,
      "health_label": "excellent",
      "issues": []
    }
  ]
}

get_shift_performance

Analyze shift-level performance: revenue per shift, orders per shift, cash accuracy, opening/closing times. Helps owners spot underperforming shifts and scheduling issues.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_shift_performance",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-08",
    "end": "2025-03-15"
  },
  "total_shifts": 14,
  "shifts": [
    {
      "shift_id": 101,
      "location_name": "Downtown",
      "shift_date": "2025-03-15",
      "revenue": 3200,
      "orders": 45,
      "aov": 71.11,
      "cash": {
        "variance": -5,
        "variance_flag": "ok"
      }
    }
  ]
}

get_staff_performance

Staff performance analysis: revenue per cashier, orders handled, average order value, discount usage, refund rate. Helps owners identify top performers and those needing coaching.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_staff_performance",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-08",
    "end": "2025-03-15"
  },
  "staff": [
    {
      "user_id": 5,
      "username": "ahmed",
      "revenue": 12400,
      "orders": 145,
      "aov": 85.52,
      "discount_rate": 2.1
    }
  ]
}

get_inventory_alerts

Inventory health overview: low stock items, out-of-stock items, overstocked items, and reorder suggestions across locations. Helps owners prevent stockouts and reduce waste.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_inventory_alerts",
  "location_ids": [
    1,
    2
  ],
  "include_details": false
}'

Example Response

{
  "summary": {
    "total_items_tracked": 120,
    "out_of_stock": 3,
    "low_stock": 8,
    "overstocked": 2,
    "healthy": 107
  },
  "critical_items": [
    {
      "material_name": "Chicken Breast",
      "current_stock": 0,
      "reorder_level": 10,
      "status": "out_of_stock"
    }
  ]
}

get_menu_performance_summary

Strategic menu engineering analysis. Shows top sellers, high-revenue/low-margin items, low performers, dead items, candidate bundles, and pricing review suggestions. Gives the owner product and pricing decisions.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_menu_performance_summary",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-01",
    "end": "2025-03-31"
  },
  "overview": {
    "total_products_sold": 45,
    "total_revenue": 52000,
    "total_quantity": 3200,
    "dead_items_count": 8
  },
  "top_sellers": [
    {
      "product_name": "Chicken Shawarma",
      "total_qty_sold": 420,
      "total_revenue": 8400,
      "classification": "star"
    }
  ]
}

get_customer_retention_snapshot

Customer repeat behavior analysis. Shows new vs returning customers, repeat purchase rates, churn-risk segments, high-value customer groups, and promo recommendation hooks. Useful when SysPOS has CRM/customer order history.

Parameters

Example Request

curl -X POST https://mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_customer_retention_snapshot",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "location_ids": [
    1,
    2
  ]
}'

Example Response

{
  "period": {
    "start": "2025-03-01",
    "end": "2025-03-31"
  },
  "summary": {
    "total_customers": 850,
    "new_customers": 120,
    "returning_customers": 730,
    "retention_rate": 85.88
  }
}

get_location_settings

Get configuration/settings for locations: currency, VAT %, daily target, fixed costs (yearly/quarterly/monthly), business info (name, address, phone, email), font size, page width, page margins, max order time, and any other config key-value pairs. Use resolve_locations first if the user refers to a branch by name.

Parameters

Example Request

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

Example Response

{
  "total_locations": 2,
  "locations": [
    {
      "location_id": 1,
      "location_name": "Downtown",
      "settings": {
        "currency": "AED",
        "vat": "5",
        "daily_target": "15000"
      }
    }
  ]
}

get_locations_overview

Get a complete overview of all locations (branches) accessible to this account. Returns total count plus per-location details: name, address, phone, timezone, opening hour, currency, and daily revenue target. Use this to answer "how many locations do I have?" or "what are my branch details?".

Parameters

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

Example Request

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

Example Response

{
  "total_locations": 3,
  "locations": [
    {
      "location_id": 1,
      "name": "Downtown Branch",
      "brand": "My Restaurant",
      "is_primary": true,
      "timezone": "+04:00",
      "opening_hour": "09:00",
      "currency": "AED",
      "daily_target": 15000
    }
  ]
}