Skip to main content

MCP Quickstart

Fast path to connect an MCP client to FlowPOS.

Use this guide when you need a working connection quickly. For full endpoint and tool details, see API Reference.

1) Choose auth mode​

V1 API key (server-to-server or internal automation)​

  • Best for internal scripts and backend integrations
  • Token is long-lived until revoked/expired

V2 OAuth token (merchant-facing assistants)​

  • Best for user-authenticated flows
  • Derived from Firebase ID token
  • Supports multi-business context switching (set_active_business)

2) Initialize MCP session​

Both V1 and V2 use the same MCP transport flow:

  1. POST /mcp with initialize
  2. Save mcp-session-id response header
  3. Use that header on all subsequent calls

Example initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0" }
  }
}

3) V1 flow (API key)​

Create key​

curl -s -X POST http://localhost:4000/mcp/keys \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "<business-uuid>",
    "role": "merchant",
    "scopes": ["pos:read","pos:write","reports:read","psa:read"],
    "label": "automation-key"
  }'

Use rawKey as Bearer token for /mcp.

Initialize and capture session id​

SESSION_ID=$(curl -s -D - -o /dev/null \
  -X POST http://localhost:4000/mcp \
  -H "Authorization: Bearer <rawKey>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}' \
  | rg -i "mcp-session-id" | awk '{print $2}' | tr -d '\r')

List tools​

curl -s -X POST http://localhost:4000/mcp \
  -H "Authorization: Bearer <rawKey>" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

4) V2 flow (Firebase -> MCP JWT)​

Exchange Firebase token​

curl -s -X POST http://localhost:4000/mcp/token \
  -H "Content-Type: application/json" \
  -d '{"firebaseIdToken":"<firebase-id-token>"}'

Use accessToken as Bearer token for /mcp.

Refresh later (no Firebase token needed)​

curl -s -X POST http://localhost:4000/mcp/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"token":"<mcp-jwt>"}'

Refresh window: up to 7 days after expiry.

Multi-business switch (if available in tools/list)​

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "set_active_business",
    "arguments": { "businessId": "<authorized-business-uuid>" }
  }
}

5) Call a tool​

curl -s -X POST http://localhost:4000/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_products",
      "arguments": { "page": 1, "limit": 20 }
    }
  }'

6) Close session​

curl -s -X DELETE http://localhost:4000/mcp \
  -H "Authorization: Bearer <token>" \
  -H "mcp-session-id: $SESSION_ID"

Common failure modes​

  • 400 mcp-session-id header required
    • You sent a non-initialize request without session id
  • 400 Unknown session ID
    • Session was lost (restart/routing); re-initialize
  • 401 Authentication required
    • Bearer credential is missing/invalid/expired
  • tool not present in tools/list
    • Missing role/scope or visibility condition not met

For deeper diagnostics: MCP session/auth troubleshooting runbook.