@klappay/mcp
OfficialSummary: This is a local stdio MCP server that lets an AI assistant inspect Klap Core API data, run metrics queries, prepare (not execute) escrow Safe transactions, and perform limited test/sandbox actions, with live writes disabled by default.
Check which Klap environment/API host the server is connected to (
klap_status).Read charges: fetch one, list/filter/paginate, and view lifecycle timelines; sensitive
metadatais omitted unless explicitly requested.Prepare escrow release/refund Safe transactions read-only, returning destination/token/amount/chain/nonce/safeTxHash and EIP-712 typed data; it never signs or submits them.
List webhook endpoints and their delivery attempts; retry a past delivery (test by default; live only with explicit opt-in).
List accepted
(token, network)payment pairs.Run aggregate metrics queries over charges, transactions, or split distributions (counts/sums/avg/min/max, filters, grouping, date buckets).
Test mode: create charges, re-check payments on-chain, retry webhook deliveries, and simulate sandbox charge states/webhooks (
sandbox_trigger).Live mode is read-only by default;
charges_create,charges_check, andwebhooks_retry_deliveryappear only when live writes are explicitly enabled.It does not expose actual escrow release/refund execution, webhook endpoint management, recipient changes, live event streams, QR codes, or swap quotes.
Note: the README lists
recipients_listandrecipients_transferability, but the provided schema does not include those tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@klappay/mcp look up charge ch_9f2a and show its timeline"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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.
Part of Klap, the non-custodial crypto payments API.
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, list split recipients and check whether a token issuer restricts their address.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.examplePaste 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.0Claude 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.
Related MCP server: Stax Payments MCP Connector
Environment variables
Variable | Default | Meaning |
|
|
|
| unset | Use this key instead of |
| stored | Required with |
| unset | Set to exactly |
An empty value counts as unset. Full rules: Configuration.
Tools
Tool | Test | Live | Live + writes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | yes | yes |
| yes | no | yes |
| yes | no | yes |
| yes | no | yes |
| 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 loginis only ever sent to the base URL it was stored with. PointingKLAP_BASE_URLsomewhere else refuses to start.Plain
http://is only accepted forlocalhost,127.0.0.1and[::1].API responses are filtered through the published
@klappay/typesschemas before the assistant sees them; unknown fields are dropped and a charge'smetadataand thelabelinrecipients_listare left out unless asked for.Not available at all: escrow
release/refund(only their read-onlypreparestep is), 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.
Topic | |
Log in, add the server, first prompts | |
How the environment and key are chosen, every refusal | |
Every tool's input, output and availability | |
Threat model, what's excluded and why |
License
Available Tools
14 toolscharges_checkRe-check charge on-chainAIdempotent
Ask the API to re-check a charge's payment on-chain now instead of waiting for the background pass. Optionally pass txHash together with network to verify one specific transaction. Never credits anything that is not really on-chain.
Inputs: id (required), txHash, network.
charges_createCreate chargeA
Create a new test charge. Escrow charges and redirectUrl are not available through this server. Pass idempotencyKey to make a retry safe; without it every call creates a new charge.
Inputs: amount (required), expiresIn (required), acceptedPayments (required), source, +6 more.
charges_getGet chargeARead-only
Fetch one charge by id: status, settlement status, amounts, accepted payment pairs, split recipients and timestamps. metadata is left out unless includeMetadata is true.
Inputs: id (required), includeMetadata.
charges_listList chargesARead-only
List this environment's charges, newest first, optionally filtered by status, paid token/network, creation time (since) or isOverpaid. Paginate with limit and the previous page's nextCursor. metadata is left out unless includeMetadata is true.
Inputs: limit, since, token, cursor, +4 more.
charges_prepare_refundPrepare escrow refundARead-only
Show the exact Safe transaction an escrow refund of this charge would execute: destination, token, amount in base units, chain id, Safe nonce, safeTxHash and the EIP-712 typedData the escrow releaser must sign. Read-only: it signs and submits nothing, and the refund itself is not available through this server. Valid only while the escrow's balance is unchanged.
Inputs: id (required).
charges_prepare_releasePrepare escrow releaseARead-only
Show the exact Safe transaction an escrow release of this charge would execute: destination, token, amount in base units, chain id, Safe nonce, safeTxHash and the EIP-712 typedData the escrow releaser must sign. Read-only: it signs and submits nothing, and the release itself is not available through this server. Valid only while the escrow's balance is unchanged.
Inputs: id (required).
charges_timelineGet charge timelineARead-only
List the lifecycle events of one charge in order (created, transfers detected, confirmed, settled, ...).
Inputs: id (required).
klap_statusKlap connection statusARead-only
Show which Klap environment (test or live) and API host this server is connected to. Makes no API call.
Inputs: no named parameters.
metrics_queryQuery business metricsARead-only
Run an aggregate query over this environment's charges, transactions or distributions (counts, sums, grouped by date bucket or dimension).
Inputs: query (required).
networks_getGet accepted networksARead-only
List the (token, network) payment pairs this environment accepts right now — the same list charges_create validates acceptedPayments against.
Inputs: no named parameters.
sandbox_triggerSimulate sandbox charge eventADestructive
Push a test charge into a payment state (confirmed, partially paid, overpaid, expired, underpaid, settled, settlement failed) without moving funds, and fire the matching webhook. Test environment only.
Inputs: event (required), chargeId (required), amount.
webhooks_listList webhooksARead-only
List webhook endpoints and the events they subscribe to. Endpoint URLs are shown as origin + path only (credentials and query strings removed); secrets are never returned, only their display hint.
Inputs: no named parameters.
webhooks_list_deliveriesList webhook deliveriesARead-only
List one webhook's delivery attempts (event, status, attempts, response code), newest first. Paginate with limit and the previous page's nextCursor.
Inputs: webhookId (required), limit, cursor.
webhooks_retry_deliveryRetry webhook deliveryADestructive
Re-send one past webhook delivery to its endpoint now. The receiving system will process the event again.
Inputs: webhookId (required), deliveryId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool maps to a distinct resource and action: charges get/list/timeline/check/create, webhook list/deliveries/retry, escrow prepare release vs refund, plus networks, metrics, sandbox, and environment status. The read-only prepare tools are clearly separated from execution and from charge inspection, so an agent can select reliably.
Most tool names follow a predictable resource_action snake_case pattern (charges_get, webhooks_list_deliveries, networks_get, metrics_query). The main deviation is klap_status, which breaks the resource-prefix convention but remains readable and clearly scoped.
Fourteen tools is well within the appropriate range for a payment operations server. Each tool covers a meaningful operation across charges, webhooks, networks, metrics, sandbox testing, and environment status, with little apparent redundancy.
The surface covers charge inspection, test charge creation, webhook delivery inspection/retry, network discovery, metrics, and sandbox simulation. However, notable lifecycle gaps remain: webhook endpoints cannot be created/updated/deleted, and escrow release/refund can only be prepared, not executed, creating dead ends for those workflows.
Maintenance
Related MCP Connectors
Run any Relay model (image, video, audio, LLM), poll tasks, upload files and search Relay's docs.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables AI agents to answer Cryptbrew product questions and check live API health without merchant authentication. Exposes tools for pricing, FAQs, invoice flow, and health probes over stdio or streamable HTTP.8MIT- AlicenseNot gradedqualityBmaintenanceLets AI clients work with one or more Stax Payments merchant accounts over stdio, discovering and switching between accounts, finding customers, listing saved payment methods, and reading transactions. Read-only by default, with opt-in write tools for creating customers, charging saved payment methods, capturing, refunding, and voiding transactions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables local AI clients such as Claude Code and Cursor to search, analyze, and monitor prediction-market data, and, once live mode is explicitly switched on, sign and submit CLOB orders from the operator's own wallet. It runs in a safe preview mode by default, writing simulated trades to local SQLite instead of sending orders.115 npm3MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read and modify an Acumulus administration through natural language over the official API, including invoices, picklists, and direct endpoint calls. Runs locally over stdio and supports test mode to validate writes without persisting them.427 PyPIAGPL 3.0