@latticepay/mcp

Model Context Protocol server for integrating the LatticePay checkout-widget, merchant-console-widget, and transaction-widget. Drop it into your AI-aware editor (Claude Code, Cursor, Windsurf, Cline, Continue, Gemini CLI) and your agent can scaffold backend mint routes, frontend embeds, webhook receivers, Apple Pay domain files, Playwright tests, and a production-cutover checklist — and validate the result against the LatticePay integrator API.

• 18 tools (12 offline codegen + 6 live against api.latticepay.io)
• 10 prompts (1 persona + 9 phase-specific)
• 6 frontend frameworks · 5 backend stacks · 5 PSPs
• stdio transport — no hosted endpoint required, no telemetry
• BYO credentials — your LatticePay integrator API key/secret stay on your machine

Install

The server is published as @latticepay/mcp. npx -y @latticepay/mcp fetches and runs it on demand — no global install needed. The credentials you set in the client's env block are passed to the server process at startup.

Claude Code (.mcp.json)

{
  "mcpServers": {
    "lattice": {
      "command": "npx",
      "args": ["-y", "@latticepay/mcp"],
      "env": {
        "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
        "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
        "LATTICE_API_BASE_URL": "https://api.latticepay.io"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "lattice": {
      "command": "npx",
      "args": ["-y", "@latticepay/mcp"],
      "env": {
        "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
        "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
        "LATTICE_API_BASE_URL": "https://api.latticepay.io"
      }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "lattice": {
      "command": "npx",
      "args": ["-y", "@latticepay/mcp"],
      "env": {
        "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
        "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
        "LATTICE_API_BASE_URL": "https://api.latticepay.io"
      }
    }
  }
}

Cline (VS Code → Cline settings → MCP servers)

{
  "mcpServers": {
    "lattice": {
      "command": "npx",
      "args": ["-y", "@latticepay/mcp"],
      "env": {
        "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
        "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
        "LATTICE_API_BASE_URL": "https://api.latticepay.io"
      }
    }
  }
}

Continue (~/.continue/config.json)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@latticepay/mcp"]
        },
        "env": {
          "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
          "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
          "LATTICE_API_BASE_URL": "https://api.latticepay.io"
        }
      }
    ]
  }
}

Gemini CLI (~/.gemini/mcp.json)

{
  "mcpServers": {
    "lattice": {
      "command": "npx",
      "args": ["-y", "@latticepay/mcp"],
      "env": {
        "LATTICE_API_KEY": "<paste-your-integrator-api-key>",
        "LATTICE_API_SECRET": "<paste-your-integrator-api-secret>",
        "LATTICE_API_BASE_URL": "https://api.latticepay.io"
      }
    }
  }
}

Quick start

Once installed, ask your agent:

"Help me embed the LatticePay checkout widget in my Next.js app. The merchant is <merchant-uuid>, amount 49.99 USD."

A well-behaved agent should:

1. Call get_integration_overview (the bootstrap tool — returns persona + phase rules inline so tool-only clients can read them).
2. Call list_merchants to confirm the merchant UUID resolves under your integrator.
3. Call generate_token_mint_endpoint for node-nextjs-route + scope checkout.
4. Call generate_embed_snippet for nextjs-app + widget checkout-widget.
5. Call generate_event_handler for the latticeCallback.
6. Offer to run lint_integration_code over the pasted result and prod_cutover_checklist when you're ready to ship.

(Once the LatticePay sandbox is available, mint_test_token and simulate_payment exercise the full mint-and-pay flow end-to-end; until then they return a structured sandbox-required error against production.)

Tools

Offline codegen (no network, no credentials required)

| Tool | What it does | |---|---| | get_integration_overview | Bootstrap — returns recommended widgets, integration sequence, and the persona/phase rules inline. | | generate_token_mint_endpoint | Backend mint route across 5 stacks (Express, Next.js route, FastAPI, Spring, net/http). | | generate_embed_snippet | Frontend widget embed across 6 frameworks (React, Next.js app, Vue 3, Angular 17, Svelte, vanilla HTML). | | generate_event_handler | Framework-idiomatic latticeCallback with success / failure / error branches. | | generate_apple_pay_domain | .well-known/apple-developer-merchantid-domain-association body + hosting instructions for 6 hosting targets. | | generate_webhook_handler | HMAC-SHA256 webhook receiver across 5 backend stacks with constant-time signature compare and replay protection. | | generate_e2e_test | Playwright (default) or Cypress checkout-flow spec. | | lint_integration_code | Static rules for 7 known anti-patterns (hard-coded token, missing callback, mount mismatch, dev URL in prod, secret leaked client-side, missing webhook HMAC, non-constant-time compare). | | compare_integration_configs | Diffs two configs; flags expected vs unexpected divergence; redacts secret-shaped values. | | prod_cutover_checklist | Stack-tailored checklist (frontend × backend × Apple Pay × webhook). | | decode_session_token | Local JWT decode + expiry / scope inspection (no signature verification). | | decode_error | Catalog-backed diagnosis for runtime/widget errors from the Phase 8 anti-pattern table. |

Live (require LatticePay integrator credentials)

| Tool | Endpoint / behavior | Status | |---|---|---| | list_merchants | Paginated walk of GET /v1/merchants under the integrator owning the API key. | ✅ available | | list_supported_psps | Static PSP catalog (Stripe, Braintree, PayPal, Klarna, Coinbase). | ✅ available | | inspect_session_token | Local decode + expiry check. Does NOT verify the JWT signature; JWKS-based verification ships in a future release. | ✅ available | | mint_test_token | Real POST /v1/auth/merchant-session round-trip + auto-decode of the returned JWT. | ⏳ requires sandbox | | simulate_payment | Real mint + synthesized complete event keyed off the test card's expected outcome. | ⏳ requires sandbox | | get_test_credentials | Curated PSP test cards with expectedOutcome annotations. | ⏳ requires sandbox |

Live tools fail closed when LATTICE_API_KEY / LATTICE_API_SECRET are unset — the error response carries copy-paste mcpServers config blocks for Claude Code, Cursor, and Windsurf.

The three write-side tools (mint_test_token, simulate_payment, get_test_credentials) are gated behind the LatticePay sandbox environment, which is on the roadmap but not yet available to external integrators. Against production they currently return a structured sandbox-required error. Once the sandbox ships, set LATTICE_API_BASE_URL=https://api.sandbox.latticepay.io and they auto-enable. Advanced users running their own internal test merchant against production can re-enable mint_test_token and simulate_payment with LATTICE_ALLOW_PROD_MINT=1 (each invocation emits a stderr banner naming the merchant, amount, and currency); get_test_credentials stays gated even with the flag because PSP test cards do not work in production.

Prompts

• persona-rules — cross-cutting rules every integration session should obey (read tool descriptions before calling, never invent merchant IDs, redact secrets, etc).
• phase-0-discover through phase-8-troubleshoot — phase-specific playbooks an agent can pull when the user asks about a specific stage of the journey.

Security model

• stdout is reserved for MCP JSON-RPC. All diagnostics go to stderr. Never console.log from a tool — it would corrupt the protocol stream.
• No credentials reach the browser. Every backend codegen template documents this; the lint tool catches it as api-secret-client-side.
• Secrets only in the MCP client's env. The server reads LATTICE_API_KEY / LATTICE_API_SECRET at startup; nothing is persisted to disk by the server itself.
• Tool descriptions are the only routing signal. Each is ≥120 chars with what / when / required-args / next-tool structure, enforced by snapshot test.

See ARCHITECTURE.md for the full design.

Versioning

Pre-1.0: minor versions can introduce breaking changes. After 1.0, semver. See CHANGELOG.md.

License

Apache-2.0