Skip to main content
Glama

@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.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.

Related MCP server: Stax Payments MCP Connector

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

recipients_list

yes

yes

yes

recipients_transferability

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 and the label in recipients_list are 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.

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

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

Available Tools

14 tools
charges_checkRe-check charge on-chainA
Idempotent

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 chargeA
Read-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 chargesA
Read-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 refundA
Read-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 releaseA
Read-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 timelineA
Read-only

List the lifecycle events of one charge in order (created, transfers detected, confirmed, settled, ...).

Inputs: id (required).

klap_statusKlap connection statusA
Read-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 metricsA
Read-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 networksA
Read-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 eventA
Destructive

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 webhooksA
Read-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 deliveriesA
Read-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 deliveryA
Destructive

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

    A3.9/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      4
      27 PyPI
      AGPL 3.0