@klappay/mcp

A local Model Context Protocol server for the Klap Core API. Your AI assistant (Claude Code, Claude Desktop, Cursor, or any MCP client) runs it on your own machine over stdio with npx. Nothing is hosted by Klappay: the server talks straight to the Klap API with the key klap login already stored in ~/.klap/config.json.

What the assistant can do with it:

• Read: look up a charge and its timeline, list webhooks and their deliveries, list accepted (token, network) pairs, run metrics queries.

• Test mode: create charges, re-check them on-chain, retry webhook deliveries and push a sandbox charge through its payment states.

• Live mode: read-only by default. Writes are only registered when you opt in explicitly.

Moving money (escrow release/refund) and managing webhook endpoints or payout recipients are never exposed. See Security.

Install

Requires Node.js 24+. Log in once with the CLI so the key lives in ~/.klap/config.json instead of your MCP client's config file:

npx @klappay/cli login --api-key - --base-url https://api.klap.example

Paste the key on stdin and press Ctrl-D. --api-key - keeps the key out of your shell history; KLAP_API_KEY=... npx @klappay/cli login --base-url ... works too.

Then add one server per environment. Keeping test and live as separate servers means the assistant always knows which one it is talking to, and you can turn live off without touching test.

Claude Code

claude mcp add klap-test -- npx -y @klappay/mcp@1.0.0
claude mcp add klap-live -e KLAP_ENV=live -- npx -y @klappay/mcp@1.0.0

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json)

Both use the same shape:

{
  "mcpServers": {
    "klap-test": {
      "command": "npx",
      "args": ["-y", "@klappay/mcp@1.0.0"]
    },
    "klap-live": {
      "command": "npx",
      "args": ["-y", "@klappay/mcp@1.0.0"],
      "env": { "KLAP_ENV": "live" }
    }
  }
}

Pin the exact version as above rather than @latest: an MCP server runs with your API key, so upgrade it on purpose. On startup it prints one line to stderr, e.g. klap-mcp: test → api.example.com, and never the key.

Related MCP server: cryptbrew-mcp

Environment variables

An empty value counts as unset. Full rules: Configuration.

Tools

Every result is JSON and carries environment. Inputs and outputs are described in Tools.

Security notes

• Live is read-only unless KLAP_MCP_ALLOW_LIVE_WRITES=1.

• A key stored by klap login is only ever sent to the base URL it was stored with. Pointing KLAP_BASE_URL somewhere else refuses to start.

• Plain http:// is only accepted for localhost, 127.0.0.1 and [::1].

• API responses are filtered through the published @klappay/types schemas before the assistant sees them; unknown fields are dropped and a charge's metadata is left out unless asked for.

• Not available at all: escrow release/refund, webhook create/delete/rotate-secret, recipient changes, live event streams, QR codes and swap quotes.

More in Security.

Documentation

Full docs live in docs/ and as a browsable site at mcp.klappay.com, which also publishes llms.txt and llms-full.txt.

License

MIT