# 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.

## Endpoint

- MCP endpoint: `/mcp`
- Transport: Streamable HTTP


Every request must include:

```http
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.

## Current tools

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.

## Intended flow

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:

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

## Guidance tools

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


## 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.

## Merchant-side crypto helper

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