MCP Server

Cheqi exposes an authenticated MCP server for merchant and backend integrations that need guided access to the zero-knowledge receipt flow over Streamable HTTP.

• MCP endpoint: /mcp
• Transport: Streamable HTTP

Every request must include:

Authorization: Bearer <token>

Supported credentials are a company API key or a client-application OAuth access token. User-only tokens are not supported for merchant receipt issuance.

The server exposes:

• match_customer
• submit_encrypted_receipt
• get_receipt_flow_guidance
• get_receipt_flow_glossary

There is no server-side receipt-template tool in the current digital flow. Receipt contents stay in merchant-controlled memory until they have been encrypted for owner devices.

1. Call match_customer with a pairing code, card PAR, payment-account identifier, or email.
2. Preserve matchId, recipients, and expiresAt exactly as returned.
3. In merchant-controlled code, serialize the definitive receipt input and encrypt it independently for every returned owner device. Use a fresh AES content key per device.
4. Call submit_encrypted_receipt with exactly one deviceDeliveries entry per matched device.
5. Cheqi queues the ciphertext. Owner devices generate, hash, and store their own CHEQI receipt; one leased device performs encrypted downstream fan-out.

The encrypted submission has this logical shape:

{
  "matchId": "match_opaque",
  "storeId": "optional-directly-owned-store-uuid",
  "deviceDeliveries": [
    {
      "deviceRecipientId": "rcpt_temporary",
      "encryptedContent": "base64-aes-gcm-ciphertext",
      "encryptedAesKey": "base64-wrapped-content-key"
    }
  ]
}

Use get_receipt_flow_guidance when an agent is unsure whether it must match, encrypt, or submit next. The result identifies required inputs, values to preserve, and forbidden actions.

Use get_receipt_flow_glossary for definitions including:

• matchId
• deviceRecipientId
• generation input
• accepted formats
• final hash
• distribution lease
• zero-knowledge boundary

The MCP server does not:

• accept plaintext receipt contents for digital issuance
• generate a plaintext receipt template
• perform merchant-side encryption
• combine decrypted merchant contents with customer context
• generate final CHEQI or UBL documents

Merchant-controlled code is responsible for serializing the definitive ReceiptPayload, generating one fresh symmetric key per device, encrypting the payload, and wrapping each key with that device's public key.

The backend legitimately performs customer matching and knows the routing context required for delivery. The owner device joins that server-known context with the decrypted merchant input in memory.

If an MCP host cannot perform cryptography directly, run the Merchant Crypto MCP Container inside merchant-controlled infrastructure. It must return the current per-device encryptedContent and encryptedAesKey handoff; it must never send plaintext contents to Cheqi.