Whiteflow

Whiteflow Merchant MCP

Manage payment collection by asking your AI assistant: create payment links and invoices, check whether they're paid, see what's outstanding, and draft reminders. It's a local MCP server (stdio), packaged as `whiteflow.mcpb` for MCPB clients such as Claude Desktop, with a manual config for other clients.

Not production. It runs in one of two modes, and every result says which:

- Sandbox (the default): a simulator on your computer. No account, no network, no real money. URLs on sandbox.whiteflow.invalid don't open.

- Testnet: the Whiteflow gateway on Whitechain Testnet with your sk_test_ key. Test USDT only. Payment links, payments and collection summaries are live once the gateway routes in PR #48 are deployed. Customers, invoices and reminders are not on the testnet backend yet, and those tools say so.

Install

Claude Desktop (.mcpb)

cd packages/mcp && npm ci && npm run pack

This builds dist/whiteflow.mcpb, plus whiteflow.mcpb.sha256 (the archive) and whiteflow.mcpb.contents.sha256 (its files). The archive also contains sbom.cdx.json, a CycloneDX list of every package bundled in it. Open the .mcpb with Claude Desktop, or use Settings → Extensions → Install extension. Then fill in the settings:

Check the archive before installing: sha256sum dist/whiteflow.mcpb (PowerShell: Get-FileHash dist\whiteflow.mcpb) must match whiteflow.mcpb.sha256. The archive's hash changes on every pack, because mcpb 2.1.2 stamps zip entries with the current time. The contents hash stays the same for the same source. A checksum only helps if you got it from a channel you trust: the archive isn't signed yet, and nothing proves who built it (see "what production needs").

Optional setting, environment only: WHITEFLOW_TRUSTED_ORIGINS, comma-separated https origins of an approved custom checkout domain. The connector shows payment and review URLs only on the gateway's own origin and these.

Other clients (manual stdio)

Build once (npm run pack), then point the client at the bundled server. For example, Claude Desktop's claude_desktop_config.json:

{

"mcpServers": { "whiteflow": { "command": "node", "args": ["/absolute/path/to/packages/mcp/dist/bundle/server/index.mjs"], "env": { "WHITEFLOW_MODE": "sandbox", "WHITEFLOW_TIMEZONE": "Asia/Kolkata" } } } }

Claude Code: claude mcp add whiteflow --env WHITEFLOW_TIMEZONE=Asia/Kolkata -- node /absolute/path/to/packages/mcp/dist/bundle/server/index.mjs

For testnet, add "WHITEFLOW_MODE": "testnet" and "WHITEFLOW_API_KEY": "sk_test_…". Keep the default local scope in Claude Code: --scope project would write the key into the repo's .mcp.json. From a checkout, node src/index.ts also works (Node 22.18 or newer runs the TypeScript directly). The bundle needs Node 20 or newer and no node_modules.

Authentication

• Testnet: a merchant-scoped secret key (sk_test_…) from the dashboard's Developers screen. The server works out your business from the key; no tool takes a merchant or business id.
• Revoke a key on the same screen; the connector then gets 401 and tells you so.
• A publishable key (pk_…) is refused.
• Testnet keys have no scopes or expiry yet: a key can do everything the merchant API allows, though this connector only calls the routes in API-CONTRACT.md. Use a key just for the assistant, so you can revoke it alone.
• Sandbox: no key needed. A local sandbox key is created next to the sandbox data, owner-only. Sandbox keys do have scopes and expiry, so you can try a narrower key.
• Never give the connector a wallet private key, a seed phrase or a payment-provider master secret. It never asks for one, and no tool can use one.
• Where the key is stored. In an .mcpb install, Claude Desktop keeps sensitive settings encrypted with Electron safeStorage, whose key is in the OS keychain (mcpb #41; help article). An open report says the settings panel can show them in plain text (mcpb #244). A manual config file holds the key in plain text, so protect that file.

Try the sandbox demo

In the assistant:

1. "Find Priya Sharma, or add her with priya@example.com."
2. "Draft an invoice for Priya: three consulting sessions at 20 USDT each, due next Friday." The assistant shows the totals and the resolved date and waits for your OK.
3. "Publish it." The assistant asks to publish this exact version. Nothing is published or emailed yet: the result gives an approval id (apr_…) for the business Owner.

In a terminal, act as the Owner on the review page, then as the customer paying. In the sandbox the review page is the approve command. The pay command sends signed provider events, and the sandbox processes them like webhooks:

cd packages/mcp

npm run sandbox -- approve apr_… # the Owner approves: the invoice becomes WF-1001, with a payment URL npm run sandbox -- pay WF-1001 # or: node dist/bundle/server/sandbox-cli.mjs pay WF-1001 npm run sandbox -- status

Back in the assistant:

1. "Has WF-1001 been paid?" It's paid, according to the processed payment record.
2. "Summarize collections this week." The summary shows the 60.00 USDT.

Scenarios for the simulator: --scenario duplicate | out-of-order | bad-signature | fail, and --amount 25 for an underpayment. npm run sandbox -- reconcile rebuilds each invoice's paid total from verified payments. The sandbox lives in %APPDATA%\whiteflow-mcp (Windows) or ~/.config/whiteflow-mcp, or in WHITEFLOW_STATE_DIR. Delete the folder to start over.

Example prompts

There are also prompt templates: Collect a payment, Create an invoice, Review overdue invoices and Summarize collections.

Tools

How writes behave (production review F2/F3):

• One operation identity. Each write sends an Idempotency-Key, and the connector records it before sending. The server replays the same record for the same key and request, marked replayed, and refuses the same key with a different request.
• Unknown outcomes are resumed, not repeated. If there's no answer (a timeout, a 5xx, a malformed or oversized reply), retrying the same request resumes that operation with the same key for as long as the server keeps it: 24 hours, across restarts and key rotations for the same business. After that, the connector refuses to send it again and marks it needs_reconciliation: check the record, then use create_another.
• Repeats vs new sales. The same request repeated within 15 minutes of a success replays it. A deliberate second, identical record needs create_another: true.
• Replies are checked. Every reply is size-capped and schema-checked. A write's reply must match what was asked: amount, currency, text, reference, single-use, expiry, customer and totals, with URLs on a trusted origin. If it doesn't, the result is an error marked for reconciliation, never a success to share.
• Never authorization. A tool's annotations are hints for the client. What each key can do, and who may publish, is enforced on the server.

How it's built

MCP client ──stdio── src/index.ts → src/server.ts (14 tools, 4 prompts)

│ tools/* → context (profile, capability gate, journaled writes, redacting reply) ▼ src/client.ts (Bearer key, timeouts, retries with the same key, no redirects, size caps, zod schemas) ├── testnet: https:// /api/v1/… (apps/web: links, account, payments, reports, operations) └── sandbox: src/sandbox/backend.ts, the same HTTP contract served in-process ├── store.ts (JSON file, lock and atomic write, owner-only) ├── records.ts (customers, links, invoices + revisions, approvals, receivables, reports) └── provider.ts (signed provider events → processing → reconcile) ← cli.ts (a person)

The bundle is a thin client. Durable records, authorization, payment verification and audit belong to the backend. On testnet, payments are MerchantPay's on-chain records, read by the gateway. The sandbox stands in for the backend routes that don't exist yet, and API-CONTRACT.md is the contract it implements.

Security notes

• Stored text is data. Customer names, descriptions, memos and references are b