mcp server

klap-mcp

klappay/klap-mcpcommunitylistedunreviewed

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "klappay-klap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@klappay/mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 19, 2026

@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 or list charges and a charge's timeline, inspect the Safe transaction an escrow release/refund would execute, 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.1.0
claude mcp add klap-live -e KLAP_ENV=live -- npx -y @klappay/mcp@1.1.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.1.0"]
    },
    "klap-live": {
      "command": "npx",
      "args": ["-y", "@klappay/mcp@1.1.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.

Environment variables

Variable	Default	Meaning
`KLAP_ENV`	`test`	`test` or `live`, exactly. Anything else refuses to start.
`KLAP_API_KEY`	unset	Use this key instead of `~/.klap/config.json`. Requires `KLAP_BASE_URL`. Its prefix must match `KLAP_ENV`.
`KLAP_BASE_URL`	stored `baseUrl`	Required with `KLAP_API_KEY`. With a stored key it must equal the stored `baseUrl`.
`KLAP_MCP_ALLOW_LIVE_WRITES`	unset	Set to exactly `1` to register `charges_create`, `charges_check` and `webhooks_retry_delivery` in live.

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

Tools

Tool	Test	Live	Live + writes
`klap_status`	yes	yes	yes
`charges_get`	yes	yes	yes
`charges_list`	yes	yes	yes
`charges_timeline`	yes	yes	yes
`charges_prepare_release`	yes	yes	yes
`charges_prepare_refund`	yes	yes	yes
`webhooks_list`	yes	yes	yes
`webhooks_list_deliveries`	yes	yes	yes
`networks_get`	yes	yes	yes
`metrics_query`	yes	yes	yes
`charges_create`	yes	no	yes
`charges_check`	yes	no	yes
`webhooks_retry_delivery`	yes	no	yes
`sandbox_trigger`	yes	no	no

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 (only their read-only prepare step is), webhook create/delete/rotate-secret, recipient changes, live event streams, QR codes and swap quotes.

Documentation

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

Topic
Getting started	Log in, add the server, first prompts
Configuration	How the environment and key are chosen, every refusal
Tools	Every tool's input, output and availability
Security	Threat model, what's excluded and why

License

MIT