{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"MCP Server","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"mcp-server","__idx":0},"children":["MCP Server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi exposes an authenticated MCP server for merchant and backend integrations"," ","that need guided access to the zero-knowledge receipt flow over Streamable HTTP."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint","__idx":1},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MCP endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/mcp"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transport: Streamable HTTP"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request must include:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <token>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported credentials are a company API key or a client-application OAuth"," ","access token. User-only tokens are not supported for merchant receipt issuance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"current-tools","__idx":2},"children":["Current tools"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The server exposes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["match_customer"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit_encrypted_receipt"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_receipt_flow_guidance"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_receipt_flow_glossary"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"intended-flow","__idx":3},"children":["Intended flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["match_customer"]}," with a pairing code, card PAR, payment-account"," ","identifier, or email."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["matchId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipients"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," exactly as returned."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit_encrypted_receipt"]}," with exactly one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deviceDeliveries"]}," entry per"," ","matched device."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cheqi queues the ciphertext. Owner devices generate, hash, and store their"," ","own CHEQI receipt; one leased device performs encrypted downstream fan-out."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The encrypted submission has this logical shape:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"matchId\": \"match_opaque\",\n  \"storeId\": \"optional-directly-owned-store-uuid\",\n  \"deviceDeliveries\": [\n    {\n      \"deviceRecipientId\": \"rcpt_temporary\",\n      \"encryptedContent\": \"base64-aes-gcm-ciphertext\",\n      \"encryptedAesKey\": \"base64-wrapped-content-key\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"guidance-tools","__idx":4},"children":["Guidance tools"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_receipt_flow_glossary"]}," for definitions including:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["matchId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deviceRecipientId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["generation input"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["accepted formats"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["final hash"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["distribution lease"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["zero-knowledge boundary"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"zero-knowledge-boundary","__idx":5},"children":["Zero-knowledge boundary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The MCP server does not:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["accept plaintext receipt contents for digital issuance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["generate a plaintext receipt template"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["perform merchant-side encryption"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["combine decrypted merchant contents with customer context"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["generate final CHEQI or UBL documents"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant-controlled code is responsible for serializing the definitive"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptPayload"]},", generating one fresh symmetric key per device, encrypting the"," ","payload, and wrapping each key with that device's public key."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-side-crypto-helper","__idx":6},"children":["Merchant-side crypto helper"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an MCP host cannot perform cryptography directly, run the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp/crypto-container"},"children":["Merchant Crypto MCP Container"]}," inside merchant-controlled"," ","infrastructure. It must return the current per-device ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedContent"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedAesKey"]}," handoff; it must never send plaintext contents to Cheqi."]}]},"headings":[{"value":"MCP Server","id":"mcp-server","depth":1},{"value":"Endpoint","id":"endpoint","depth":2},{"value":"Current tools","id":"current-tools","depth":2},{"value":"Intended flow","id":"intended-flow","depth":2},{"value":"Guidance tools","id":"guidance-tools","depth":2},{"value":"Zero-knowledge boundary","id":"zero-knowledge-boundary","depth":2},{"value":"Merchant-side crypto helper","id":"merchant-side-crypto-helper","depth":2}],"frontmatter":{"title":"MCP Server","seo":{"title":"MCP Server"}},"lastModified":"2026-08-05T15:06:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/mcp/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}