GenesisPay

@genesis-tech/genesispay-mcp

MCP (Model Context Protocol) stdio server that lets AI agents pay for x402-gated HTTP resources through GenesisPay — with spending policies and human approvals enforced server-side.

This README documents 2.0.0 (prepared, not published), which requires Agent SDK ^2.0.0. Its description, result, external-directory and review tools need a GenesisPay deployment that serves them; review writes require explicit review permission (migrations through 0161, and 0162 for external-service purchase reviews). The external-directory tools (since 1.5.0) also need a deployment that serves the buyer-fee hint (include=buyerFee, ADR-0101 S5). The physical-commerce tools of 1.6.0 (genesispay_quote, genesispay_shipping_profile and the quote form of genesispay_pay) need a deployment that serves the agent shipping-profile, commerce-quote and commerce-purchase routes (ADR-0108); an older one answers them with a plain "not supported yet" error.

Setup requires a GenesisPay deployment that serves /api/v2/agent/pay and MCP server version 1.0 or later. POST purchases additionally need a deployment that confirms them (its v2 answer echoes requestMethod and bodySha256); against an older one the purchase is reported as an unknown outcome, never as a success.

Web chats (Claude.ai, ChatGPT) cannot run a stdio process. A GenesisPay deployment with remote MCP enabled hosts these same tools itself at https:// /mcp, authorized with OAuth: you add that URL as a custom connector, sign in to GenesisPay and approve one agent — no package to install and no key to copy. Availability depends on the deployment; see "Connect a web chat" on the deployment's /docs/mcp page. This package is what serves it (the ./http export below).

MCP Registry. The package's registry name is finance.genesispay/mcp (mcpName in package.json); server.json beside it describes both the npm package (stdio) and the hosted remote https://genesispay.finance/mcp.

Ships the genesispay-mcp binary and exposes seventeen tools:

Payments above the account's caps pause as pending_approval. The tool result then carries an approvalUrl (/dashboard/approvals?payment= , which highlights that entry); the model is instructed to tell the user the amount, resourceUrl and paymentId, and to poll genesispay_payment_status rather than retrying the payment. Approving executes it server-side. An allowlist miss or a paused account is policy_blocked: a hard stop, not an approval request — the model is told to stop and tell the user rather than retry under another key.

A settled payment carries the paid response under resource. Since 1.9.0 the provider's text is wrapped and labelled in the data itself, apart from GenesisPay's own fields and instructions: resource.providerContent = { trust: "untrusted_provider_data", body }, or { trust, bodyPreview } when the response is longer than 50,000 characters (truncated: true; read the rest with genesispay_result). Before 1.9.0 the body sat directly in resource.body / resource.bodyPreview. genesispay_result labels its stored body the same way: result.response.providerContent = { trust: "untrusted_provider_data", bodyChunk }, with offset, nextOffset, totalChars, complete and any review instructions outside it (before 1.9.0: result.response.bodyChunk). Only an available result is wrapped, so a body under any other result state is refused with a tool error that quotes none of it, never passed on unlabelled; so is a result state this client does not know. The error says not to buy again.

The GenesisPay fee on external x402 purchases (1.5.0)

When the provider is not a GenesisPay seller, GenesisPay adds its own fee on top of the provider's price (currently 1 % of the price, with a minimum; the provider still receives its full price), paid from the same agent wallet and charged only if the purchase settles. maxAmountUsdc keeps bounding the provider's price; the owner's caps and approval limits apply to the total. The tool description tells the model to name the total before paying, and, for a URL without a hint, not to estimate the fee from the percentage (the minimum dominates small prices) but to say a fee may be added on top.

• Before paying: genesispay_discover (external results) and genesispay_describe_service (an ext_… id) return each service's buyerFee hint, { active, bps, minMinor, feeMinor, totalMinor } in USDC minor units, plus a feeSummary when it is active. It is an estimate, not a quote; an absent hint does not mean no fee.
• After paying: a genesispay_pay answer (settled, pending_approval or not_confirmed_yet) whose payment carries the fee adds genesisPayFeeUsdc, totalUsdc, buyerFeeStatus (quoted, pending, collected, not_charged, waived, or a newer value) and a feeSummary line computed from integer minor units:

{

"amountUsdc": "0.001", "genesisPayFeeUsdc": "0.005", "totalUsdc": "0.006", "buyerFeeStatus": "pending", "feeSummary": "0.001 + GenesisPay fee 0.005 = 0.006 USDC" }

A fee that no longer moves (not_charged, waived) is shown out of the total. Without a fee the answer carries none of these fields. genesispay_payment_status returns the payment's raw buyerFeeMinor, totalDebitMinor and buyerFeeStatus.

A curated external service can be refused before anything is sent or signed: external_service_quarantined (422) and external_registry_unavailable (503) come back with outcome: "not_charged" — the model is told not to retry a quarantined service, and that a registry outage may be retried later with the same idempotencyKey. external_offer_not_pinned (422, the live offer is outside the curated terms) is a plain rejection. None of these carries the "may already have been charged" warning.

Physical products: quote, confirm the address, buy (1.6.0)

A seller's WooCommerce products appear in genesispay_discover with purchase: { mode: "quote", productId, listedPriceUsdc } and no resourceUrl: shipping, tax, stock and the exact total depend on the delivery address, so they cannot be paid by URL (ADR-0108). The flow:

1. genesispay_quote({ productId, quantity }) quotes to the account owner's one saved shipping address. Nothing is ordered or charged.
2. The answer car