# Sezzle Merchant MCP

An unofficial, experimental, security-focused Model Context Protocol server for safe Sezzle merchant operations, settlement reconciliation, webhook monitoring, and integration diagnostics.

> **This project is unofficial and is not affiliated with, endorsed by, or maintained by Sezzle.**

No Sezzle logos are used. Sezzle trademarks belong to their respective owner.

## Project maturity

This project is an unofficial, experimental integration.

Its deterministic business logic, permission model, mutation guards, and mocked API integration are tested. However, the Sezzle API adapter has not yet been validated with real merchant sandbox credentials.

Do not enable production financial mutations until the [sandbox validation checklist](docs/SANDBOX_VALIDATION.md) has been completed.

Production-oriented and security-focused design does not mean production readiness. Live Sezzle sandbox validation is still required before production use.

> Analyze today’s Sezzle orders, identify uncaptured authorizations and refund mismatches, reconcile the latest settlement, inspect webhook health, and prepare safe actions without executing anything until I approve them.

Sezzle Merchant MCP is not a thin API wrapper. It adds deterministic money validation, mutation previews, explicit approval gates, permission-based tool registration, reconciliation evidence, webhook correlation, Integration Doctor findings, secure support routing, and redacted audit records around the documented Sezzle merchant API.

## Features

- Sandbox-first startup with read-only mode enabled by default.
- Documented Sezzle v2 merchant API adapter with in-memory token renewal.
- Capture, refund, release, session, reference, checkout, and webhook mutation previews.
- Literal `confirm: true`, expiring preview binding, fresh-state validation, and idempotency.
- Integer minor-unit money and `bigint` arithmetic; no floating-point financial calculations.
- Lossless parsing of settlement decimals and four-decimal interest-account values.
- Deterministic settlement matching, duplicate suppression, mismatch detection, expected payout, confidence, and evidence.
- Raw-byte HMAC-SHA256 webhook verification before parsing, idempotent ingestion, and occurrence-time timelines.
- Stable-code Integration Doctor findings and go-live checklists.
- PII-minimized support policy tools with merchant-reference ownership verification.
- Structured JSON logs to stderr, redacted resources, and durable audit metadata.
- MCP stdio and stateless Streamable HTTP transports.
- Memory and SQLite storage, Docker, Compose, CI, Dependabot, ESLint, Prettier, and Vitest.

## Architecture

```mermaid
flowchart LR
    Client[MCP client] --> Transport[stdio or Streamable HTTP]
    Transport --> Registry[Permission-filtered MCP registry]
    Registry --> Services[Operation services]
    Services --> Guards[Preview, confirmation, ownership, idempotency]
    Services --> Domain[Money, reconciliation, diagnostics, support policy]
    Services --> API[Versioned Sezzle v2 adapter]
    API --> Auth[In-memory token manager]
    API --> HTTP[Timeout, retry, concurrency, correlation]
    HTTP --> Sezzle[Documented Sezzle merchant API]
    Services --> Storage[Memory or SQLite]
    Storage --> Audit[Redacted audit evidence]
    Storage --> Events[Verified webhook event timeline]
```

MCP registration is intentionally thin. Services own workflows, domain modules own deterministic calculations, API modules own paths and wire schemas, and storage modules own previews, idempotency, audit events, and webhook records. See [ARCHITECTURE.md](ARCHITECTURE.md) for design decisions and documented API ambiguities.

## Safety Model

The default configuration is:

```env
SEZZLE_ENV=sandbox
SEZZLE_READ_ONLY=true
SEZZLE_REQUIRE_CONFIRMATION=true
SEZZLE_PERMISSION_PROFILE=read
MCP_TRANSPORT=stdio
```

Mutation tools are not registered while `SEZZLE_READ_ONLY=true`. They are absent from `tools/list`; they do not remain visible and return permission errors.

Financial and high-impact operations use two steps:

1. Call the preview tool, or call a combined mutation tool with `confirm: false`.
2. Review current state, requested change, financial impact, validation, warnings, expiry, and audit ID.
3. Repeat the unchanged request with the returned `preview_id` and literal `confirm: true`.

Execution fails if the preview expired, was already used, belongs to another merchant/target/environment, has a different request hash, or current state changed. The model cannot infer confirmation from natural language.

Example capture:

```json
{
  "tool": "sezzle_preview_capture",
  "arguments": {
    "order_uuid": "order-uuid",
    "amount": { "amount_in_cents": 2500, "currency": "USD" }
  }
}
```

After reviewing the preview:

```json
{
  "tool": "sezzle_capture_order",
  "arguments": {
    "order_uuid": "order-uuid",
    "amount": { "amount_in_cents": 2500, "currency": "USD" },
    "preview_id": "preview-from-first-call",
    "confirm": true
  }
}
```

Successful execution is reported only after a successful Sezzle API response. Reauthorization additionally requires `authorization.approved === true`; HTTP 200 alone is not treated as approval.

## Supported Tools

The generated [tool inventory](docs/TOOL_INVENTORY.md) currently verifies 55 tools, 6 resources, and 5 prompts. The active permission profile and read-only setting determine which tools are registered.

### Authentication, sessions, and orders

- `sezzle_authenticate_merchant`
- `sezzle_get_merchant_context`
- `sezzle_create_payment_session`
- `sezzle_get_payment_session`
- `sezzle_cancel_active_checkout`
- `sezzle_get_order`
- `sezzle_update_order_reference`
- `sezzle_preview_capture`
- `sezzle_capture_order`
- `sezzle_preview_refund`
- `sezzle_refund_order`
- `sezzle_preview_release_authorization`
- `sezzle_release_authorization`
- `sezzle_reauthorize_order`

### Settlements, reports, and reconciliation

- `sezzle_list_settlement_summaries`
- `sezzle_get_settlement_details`
- `sezzle_get_order_report`
- `sezzle_get_interest_balance`
- `sezzle_get_interest_activity`
- `sezzle_reconcile_settlement`
- `sezzle_find_unmatched_orders`
- `sezzle_detect_refund_mismatches`
- `sezzle_detect_capture_mismatches`
- `sezzle_detect_fee_anomalies`
- `sezzle_explain_payout_difference`
- `sezzle_generate_finance_daily_brief`

### Webhooks

- `sezzle_list_webhooks`
- `sezzle_create_webhook`
- `sezzle_update_webhook`
- `sezzle_delete_webhook`
- `sezzle_send_test_webhook`
- `sezzle_verify_webhook_signature`
- `sezzle_ingest_webhook_event`
- `sezzle_list_webhook_events`
- `sezzle_get_webhook_event`
- `sezzle_inspect_webhook_health`
- `sezzle_find_missing_order_events`
- `sezzle_detect_out_of_order_events`
- `sezzle_detect_duplicate_webhook_events`

### Integration Doctor

- `sezzle_diagnose_integration`
- `sezzle_validate_session_payload`
- `sezzle_validate_redirect_urls`
- `sezzle_audit_auth_capture_flow`
- `sezzle_detect_stuck_authorizations`
- `sezzle_detect_uncaptured_orders`
- `sezzle_detect_duplicate_refunds`
- `sezzle_test_webhook_configuration`
- `sezzle_generate_go_live_checklist`

### Support and audit

- `sezzle_explain_order_status_for_support`
- `sezzle_classify_support_request`
- `sezzle_draft_customer_response`
- `sezzle_determine_safe_support_route`
- `sezzle_identify_required_escalation`
- `sezzle_list_audit_events`
- `sezzle_get_audit_event`

## Permission Profiles

Set `SEZZLE_PERMISSION_PROFILE` to one profile:

| Profile    | Registered capabilities                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `read`     | Auth context, sessions, orders, settlements, reports, and Integration Doctor                                       |
| `finance`  | Read capabilities plus capture/refund/release/session/order previews, reconciliation, and write tools when enabled |
| `webhooks` | Subscription management, signature verification, ingestion, timelines, and health                                  |
| `support`  | Five isolated support tools; raw order read tools are not registered                                               |
| `admin`    | All capabilities and audit inspection                                                                              |

`read` is the default. Read-only mode independently removes every mutation tool from any profile.

## Installation

Requirements:

- Node.js 20 or later
- npm
- A Sezzle sandbox merchant account for API-backed testing

```bash
git clone https://github.com/onatozmenn/sezzle-merchant-mcp.git
cd sezzle-merchant-mcp
npm ci
npm run build
npm run inspect-tools
```

Available scripts:

```text
npm run dev
npm run build
npm run start
npm run test
npm run test:watch
npm run test:coverage
npm run lint
npm run typecheck
npm run format
npm run format:check
npm run inspect-tools
npm run docker:build
npm run docker:run
```

## Sandbox Setup

1. Create or obtain a Sezzle sandbox merchant account.
2. Generate sandbox API keys in the sandbox Merchant Dashboard.
3. Copy `.env.example` to `.env`.
4. Keep `SEZZLE_ENV=sandbox`, `SEZZLE_READ_ONLY=true`, and `SEZZLE_PERMISSION_PROFILE=read` initially.
5. Set `SEZZLE_MERCHANT_UUID`, `SEZZLE_API_KEY`, and `SEZZLE_API_SECRET`.
6. Build and connect an MCP client.
7. Validate authentication, read tools, Integration Doctor, and previews before enabling writes.

The default base URL is `https://sandbox.gateway.sezzle.com`. A custom loopback HTTP base URL is accepted only for mock integration tests.

## Production Setup

Production is fail-closed. It requires all of:

```env
SEZZLE_ENV=production
SEZZLE_API_BASE_URL=https://gateway.sezzle.com
SEZZLE_MERCHANT_UUID=your-production-merchant-uuid
SEZZLE_API_KEY=your-production-public-key
SEZZLE_API_SECRET=your-production-private-key
SEZZLE_READ_ONLY=true
SEZZLE_REQUIRE_CONFIRMATION=true
```

The authenticated merchant UUID must match `SEZZLE_MERCHANT_UUID`. Run the go-live checklist in read-only mode first. Enable an appropriate permission profile, then set `SEZZLE_READ_ONLY=false` only after review. Unsafe write mode with `SEZZLE_REQUIRE_CONFIRMATION=false` is rejected at startup.

Use a secret manager, encrypted SQLite storage, TLS termination, transport authentication, restrictive host/origin allowlists, monitoring, and backup/retention controls. Do not place production secrets in MCP client JSON committed to source control.

## Claude Desktop

Build the server, then add it to the Claude Desktop MCP configuration. Use an absolute path:

```json
{
  "mcpServers": {
    "sezzle-ops": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\sezzle-merchant-mcp\\dist\\index.js"],
      "env": {
        "SEZZLE_ENV": "sandbox",
        "SEZZLE_READ_ONLY": "true",
        "SEZZLE_PERMISSION_PROFILE": "read"
      }
    }
  }
}
```

Inject credentials through the operating system or a secret-aware launcher rather than checking them into configuration files.

## Claude Code

Create a project-local `.mcp.json` that is excluded from source control when it contains credentials:

```json
{
  "mcpServers": {
    "sezzle-ops": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/sezzle-merchant-mcp/dist/index.js"],
      "env": {
        "SEZZLE_ENV": "sandbox",
        "SEZZLE_READ_ONLY": "true",
        "SEZZLE_PERMISSION_PROFILE": "read"
      }
    }
  }
}
```

Restart the MCP session after changing environment variables.

## Cursor

Add the same stdio definition to Cursor's MCP configuration:

```json
{
  "mcpServers": {
    "sezzle-ops": {
      "command": "node",
      "args": ["/absolute/path/to/sezzle-merchant-mcp/dist/index.js"],
      "env": {
        "SEZZLE_ENV": "sandbox",
        "SEZZLE_READ_ONLY": "true",
        "SEZZLE_PERMISSION_PROFILE": "read"
      }
    }
  }
}
```

For VS Code, add the same stdio definition to your local user or workspace MCP settings after `npm run build`. Editor-local `.vscode/` configuration is intentionally excluded from the public repository.

## HTTP Transport

Enable stateless Streamable HTTP:

```env
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
```

The MCP endpoint is `http://127.0.0.1:3000/mcp`; health is `GET /health`. Browser origins are rejected unless loopback or listed in `MCP_HTTP_ALLOWED_ORIGINS`.

Every non-loopback bind requires both:

```env
MCP_HTTP_AUTH_TOKEN=a-long-random-transport-token
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com
MCP_HTTP_ALLOWED_ORIGINS=https://trusted-client.example
```

Terminate TLS at a trusted reverse proxy and send `Authorization: Bearer <token>`. `/health` is intentionally unauthenticated and contains no merchant state. HTTP request bodies are limited to 1 MB; webhook ingestion tool inputs are additionally schema-limited.

## Docker

Build and run stdio:

```bash
npm run docker:build
npm run docker:run
```

For HTTP plus persistent SQLite, set `MCP_HTTP_AUTH_TOKEN` in `.env` and run:

```bash
docker compose up --build
```

Compose uses a non-root image, read-only root filesystem, dropped capabilities, a dedicated SQLite volume, and a health check.

## Example Workflows

### Daily operations review

1. Read `sezzle://config`, `sezzle://permissions`, and `sezzle://capabilities`.
2. Authenticate and verify the merchant/environment.
3. Fetch scoped order/report evidence.
4. Run `sezzle_detect_uncaptured_orders`, reconciliation, and webhook health checks.
5. Prepare capture/refund/release previews.
6. Present audit IDs, warnings, and expected financial impact.
7. Stop without executing unless the user separately approves a specific preview.

### Refund workflow

1. Call `sezzle_preview_refund` with an integer minor-unit amount.
2. Confirm the current captured, refunded, and remaining-refundable amounts.
3. Resolve warnings or validation failures.
4. Call `sezzle_refund_order` with the unchanged request, `preview_id`, and `confirm: true`.
5. Treat the returned transaction UUID and request ID as API evidence.

## Webhook Setup

Sezzle documents HMAC-SHA256 over the exact raw webhook body using the merchant signing secret. Configure the value separately:

```env
SEZZLE_WEBHOOK_SECRET=your-signing-secret
```

Use `sezzle_create_webhook` in write-enabled `webhooks` or `admin` mode. It previews URL/event-set changes before confirmation.

For ingestion:

1. Preserve the exact request bytes as a UTF-8 string.
2. Pass the exact raw body and `Sezzle-Signature` value to `sezzle_verify_webhook_signature`.
3. Call `sezzle_ingest_webhook_event` with literal `confirm: true` only after verification policy allows storage.
4. Invalid signatures are rejected before JSON parsing.
5. Event UUID and payload hash deduplicate repeated delivery.
6. Timelines order by `occurredAt`, not receipt order.

Public event tools return metadata and correlation IDs, not raw bodies. SQLite preserves verified raw bodies because correlation and forensic requirements depend on them; protect and retain that database as merchant-sensitive data.

## Reconciliation Example

Reconciliation accepts merchant orders and normalized settlement line items as structured input. Amounts are integer cents:

```json
{
  "input": {
    "currency": "USD",
    "merchant_orders": [
      {
        "record_id": "merchant-1001",
        "order_reference": "order_1001",
        "sezzle_order_uuid": "sezzle-order-uuid",
        "currency": "USD",
        "order_amount_in_cents": 10000,
        "captured_amount_in_cents": 8000,
        "refunded_amount_in_cents": 1000,
        "expected_fee_in_cents": 480
      }
    ],
    "sezzle_records": [
      {
        "record_id": "capture-row-1",
        "type": "CAPTURE",
        "order_uuid": "sezzle-order-uuid",
        "external_reference_id": "order_1001",
        "amount_in_cents": 8000,
        "currency": "USD"
      }
    ],
    "actual_settlement": { "amount_in_cents": 6520, "currency": "USD" },
    "fee_tolerance_in_cents": 0
  }
}
```

Every result includes `summary`, `matched`, `unmatchedMerchantRecords`, `unmatchedSezzleRecords`, `amountMismatches`, `feeAnomalies`, `confidence`, and `evidence`. Duplicate rows are excluded before payout arithmetic. Currency conversion is never inferred.

## Integration Doctor Example

```json
{
  "input": {
    "now": "2026-07-16T12:00:00Z",
    "configured_environment": "sandbox",
    "credential_environment": "sandbox",
    "api_base_url": "https://sandbox.gateway.sezzle.com",
    "orders": [],
    "webhooks": {
      "subscribed_events": ["order.authorized"],
      "required_events": ["order.authorized", "order.captured"],
      "invalid_signature_count": 0,
      "missing_events": [],
      "out_of_order_count": 0
    }
  }
}
```

Findings contain stable `code`, `severity`, `title`, `explanation`, `evidence`, `recommendedAction`, and `safeToAutomate: false`. The engine reports evidence; it does not execute repairs.

## MCP Resources

- `sezzle://config`
- `sezzle://permissions`
- `sezzle://capabilities`
- `sezzle://diagnostic-codes`
- `sezzle://audit-summary` (`admin` only)
- `sezzle://webhook-health` (`webhooks` or `admin`)

Resources never expose API keys, secrets, bearer tokens, signatures, raw webhook bodies, or customer records.

## MCP Prompts

- `sezzle_daily_operations_review`
- `sezzle_settlement_reconciliation`
- `sezzle_integration_go_live_review`
- `sezzle_webhook_incident_investigation`
- `sezzle_support_case_review`

Prompts are profile-aware and direct the model to collect evidence before interpretation, use deterministic arithmetic, distinguish facts from recommendations, prepare previews, and avoid unsupported success claims.

## Security Considerations

- Never log or commit API keys, bearer tokens, webhook signatures, raw payloads, customer PII, or payment details.
- Tokens remain in memory and are refreshed before the documented expiry. A 401 triggers one reacquisition; a mutation is replayed only when it carries documented idempotency.
- Safe GETs respect timeouts, exponential backoff, `Retry-After`, and concurrency limits.
- Webhook subscription/session/reference mutations are not retried automatically because their endpoints do not document idempotency.
- Settlement JSON decimals use a lossless parser. CSV decimals are converted from text directly to scaled integers.
- Support order access requires authenticated merchant access and a matching merchant reference. Returned order projections exclude customer fields.
- SQLite preserves raw verified webhook bodies. Use encrypted storage, strict access, backups, and retention controls.
- Remote HTTP requires transport authentication, allowed hosts, TLS termination, and network controls.
- Review [SECURITY.md](SECURITY.md) before production deployment.

## Known Limitations

- `GET /v2/orders/report` is available by request only and supports a maximum seven-day range.
- Interest endpoints require enrollment in Sezzle's interest account program.
- Settlement details are CSV; schema changes by Sezzle may require adapter updates.
- The Sezzle documentation currently links to `https://gateway.sezzle.com/v2api.yaml`, which returns 404. This project uses the published `https://docs.sezzle.com/openapi.yaml`.
- Authorization event examples and their component schema use two documented shapes; the adapter supports those two shapes only.
- The upcharge API is marked in development and not available for production, so it is intentionally not exposed.
- No documented endpoint lists arbitrary current merchant orders. Integration Doctor and reconciliation accept scoped structured records rather than scraping a dashboard.
- The order report API includes customer fields; Sezzle Merchant MCP removes them from its normalized response.
- Streamable HTTP is stateless. Durable workflow state belongs in SQLite; multi-node shared storage is not implemented.
- SQLite data is not application-level encrypted. Use encrypted disks/volumes and platform access controls.
- OAuth is not bundled. Remote deployments use a configured bearer token and should sit behind a production identity-aware reverse proxy.
- Support drafting is deterministic policy templating, not an embedded LLM. The MCP client may use the returned facts/policy to assist drafting.

## Roadmap

- Shared transactional storage for multi-node HTTP deployments.
- Pluggable secret-manager and encrypted-record integrations.
- Configurable webhook retention and deletion policies.
- OAuth/OIDC deployment adapter for remote MCP clients.
- OpenAPI contract drift automation against published Sezzle specifications.
- Additional reconciliation import adapters that preserve deterministic core types.

## Source of Truth

- Sezzle documentation index: <https://docs.sezzle.com/llms.txt>
- Sezzle OpenAPI specification: <https://docs.sezzle.com/openapi.yaml>
- MCP TypeScript SDK v1 documentation: <https://ts.sdk.modelcontextprotocol.io/>
- MCP TypeScript SDK v1 source: <https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x>

No endpoint absent from the published Sezzle OpenAPI specification is intentionally exposed.

## License

MIT. See [LICENSE](LICENSE).