agentpay-mcp 4.1.6 → 4.1.8

package/README.md

@@ -1,8 +1,9 @@
 # AgentPay MCP
 
 [![npm version](https://img.shields.io/npm/v/agentpay-mcp.svg)](https://www.npmjs.com/package/agentpay-mcp)
+[![Glama MCP Server](https://img.shields.io/badge/glama.ai-MCP%20server-1ee495?logo=githubsponsors&logoColor=1ee495&labelColor=0a0a0a)](https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-149%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-195%20passing-brightgreen.svg)](tests/)
 [![Patent Pending](https://img.shields.io/badge/patent-pending-orange.svg)](https://uspto.gov)
 
 **Compatible with x402 V1/V2 + Stripe MPP — protocol-agnostic spend controls.**
@@ -91,6 +92,7 @@ AgentPay MCP is built for enterprise MCP deployments where supply chain security
 - **x402 TVM readiness.** For TVM/TON exact-payment offers from emerging x402 examples, use the [x402 TVM readiness note](docs/x402-tvm-readiness.md) to confirm unsupported TVM requirements fail closed until deliberate signing, gas, jetton, and settlement support exists.
 - **x402 MCP funding UX.** For hosted fund-link and managed-wallet comparisons, use the [x402 MCP funding UX benchmark](docs/x402-mcp-funding-ux-benchmark.md) to keep onboarding speed separate from approval gates, daily caps, auditability, and non-custodial controls.
 - **Directory introspection readiness.** For Glama, Smithery, and other MCP catalogs, use the [directory introspection readiness note](docs/directory-introspection-readiness.md) for verified `npx`, Docker, MCP name, and non-custodial metadata paths.
+- **x402-native vs Stripe-proxy MCP.** For builders comparing AgentPay MCP with emerging Stripe-proxy MCP repos, use the [x402-native vs Stripe-proxy note](docs/x402-native-vs-stripe-proxy.md) to keep approval gates, spend caps, audit rows, and non-custodial signing separate from proxy billing claims.
 - **WhatsApp and SMB agent controls.** For channel-native paid agents, use the [WhatsApp and SMB paid-agent controls recipe](docs/whatsapp-smb-agent-controls.md).
 - **Channel-agent affiliate payout controls.** For Axon-style affiliate and referral revenue shares, use the [channel-agent affiliate controls spec](docs/channel-agent-affiliate-controls.md) to keep payout caps, per-contact approval, audit rows, and optional x402 settlement separate from paid tool spend approval.
 - **x402 chain drift.** AgentPay MCP tracks the x402 Foundation paywall-template baseline with `viem` `^2.47.12` or newer, and fails closed for unmapped chains. For PaymentWrapper and paywall template changes, follow the [x402 chain-drift compatibility note](docs/x402-chain-drift-compatibility.md).
@@ -210,6 +212,34 @@ Both projects enable agent payments. They solve different problems at different
 
 ---
 
+## FAQ: x402-native AgentPay MCP vs Stripe-proxy MCP
+
+Public MCP payment repos are starting to use x402 plus Stripe Agent wording for discovery. Treat that as a market signal, not as proof that every proxy has shipped complete spend control.
+
+**What is the main difference?**
+
+AgentPay MCP keeps the payment decision inside the agent's policy boundary. The agent requests `x402_pay`, AgentPay checks approval state and spend policy before signing, and the audit trail records the tool, amount, merchant, receipt, and policy result. A Stripe-proxy pattern usually puts a payment or billing proxy in front of a downstream service.
+
+**Why not use a proxy for every paid MCP call?**
+
+A proxy can help with billing and account aggregation. It does not automatically answer who approved the spend, whether the agent stayed inside its task budget, or whether a signature was blocked before policy approval. AgentPay MCP handles those controls before payment execution.
+
+**What proof can a directory or buyer check today?**
+
+- npm: `agentpay-mcp@4.1.8` or newer
+- Glama: https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp
+- Catalog metadata: `glama.json` and `smithery.yaml`
+- Install paths: `npx` and Docker
+- Introspection: 27 MCP tools including `x402_pay`, `check_budget`, `set_spend_policy`, and `otel_evaluate_spend`
+
+**How does this compare with Lightning Wallet MCP?**
+
+Lightning Wallet MCP is a Bitcoin wallet MCP with Glama-facing badge work and x402 fallback positioning. AgentPay MCP is focused on x402 payment-tool governance: approval gates, hard spend caps, non-custodial local signing, directory metadata, and audit rows tied to paid tool calls.
+
+For the full checklist, see [x402-native AgentPay MCP vs Stripe-proxy MCP patterns](docs/x402-native-vs-stripe-proxy.md).
+
+---
+
 
 ## Quick Start
 

package/dist/index.js

@@ -42,7 +42,7 @@ const otel_budget_js_1 = require("./tools/otel-budget.js");
 // ─── Server configuration ──────────────────────────────────────────────────
 const SERVER_INFO = {
     name: 'agentpay-mcp',
-    version: '4.1.6',
+    version: '4.1.8',
 };
 const SERVER_CAPABILITIES = {
     tools: {},
@@ -261,7 +261,7 @@ async function main() {
     });
     await server.connect(transport);
     // Log to stderr (not stdout — stdout is reserved for MCP protocol)
-    process.stderr.write(`AgentPay MCP v4.1.6 started. ` +
+    process.stderr.write(`AgentPay MCP v4.1.8 started. ` +
         `Wallet: ${process.env['AGENT_WALLET_ADDRESS'] ?? '(not configured)'} | ` +
         `Chain: ${process.env['CHAIN_ID'] ?? '8453 (Base Mainnet)'} | ` +
         `Session TTL: ${process.env['SESSION_TTL_SECONDS'] ?? '3600'}s\n`);

package/docs/x402-native-vs-stripe-proxy.md

@@ -0,0 +1,79 @@
+# x402-native AgentPay MCP vs Stripe-proxy MCP patterns
+
+Toolstem opened a public MCP proxy repo on 2026-05-01 with x402 and Stripe Agent positioning. The verified README signal is useful: paid MCP discovery is moving toward familiar payment keywords before every project has shipped a full implementation.
+
+AgentPay MCP should be evaluated on a different axis. It is not a pooled-token proxy that hides a downstream account. It is an MCP payment-control server for agents that need x402 payment execution with local policy, human approval, spend caps, and audit trails before signing.
+
+## Quick answer
+
+Choose AgentPay MCP when the agent owns the spend decision and must prove who approved the payment, how much was allowed, which tool requested it, and whether the policy engine accepted or rejected the transaction.
+
+Use a Stripe-proxy pattern when the product goal is to put a familiar billing surface in front of a downstream service and the operator is comfortable with the proxy holding pooled service credentials.
+
+## Comparison
+
+| Question | AgentPay MCP x402-native path | Stripe-proxy MCP pattern |
+|---|---|---|
+| Payment trigger | Agent calls `x402_pay` after an HTTP 402 challenge or paid-tool request | Agent pays a proxy that forwards to another gateway |
+| Custody posture | Non-custodial by default; `AGENT_PRIVATE_KEY` stays local | Often proxy-operated credentials or pooled downstream tokens |
+| Approval gate | Human approval and policy approval can be required before signing | Depends on proxy implementation |
+| Spend caps | Per-transaction, daily, session, and policy caps before payment | Usually billing or account limits outside the agent loop |
+| Audit trail | Tool, merchant, amount, policy result, receipt, and transaction history | Depends on proxy logging and downstream account data |
+| Directory proof | Glama listing, `glama.json`, `smithery.yaml`, Docker path, npm path, and 27-tool introspection proof | Repo-specific; do not assume until listed and introspected |
+| Failure mode | Fail closed when policy, chain, asset, or approval state is unsupported | Depends on proxy implementation |
+
+## What "x402-native" means here
+
+AgentPay MCP keeps the payment contract visible to the agent runtime:
+
+1. The agent sees a paid endpoint or paid MCP tool.
+2. AgentPay checks policy before any signature is produced.
+3. If human approval is required, the payment waits.
+4. If the policy rejects, the request fails closed.
+5. If approved, `x402_pay` signs and submits through the configured x402 path.
+6. The audit trail records the tool, amount, policy version, approval state, and receipt.
+
+That is different from routing every paid call through a proxy that owns the downstream service account. A proxy can be useful, but it does not automatically solve per-agent spend authority.
+
+## Directory proof status
+
+AgentPay MCP currently has public discovery and package proof:
+
+- Glama listing: https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp
+- npm package: `agentpay-mcp@4.1.8` or newer
+- Packaged catalog metadata: `glama.json` and `smithery.yaml`
+- Packaged install paths: `npx` and Docker
+- Introspection proof: 27 MCP tools, including `x402_pay`, `check_budget`, `set_spend_policy`, and `otel_evaluate_spend`
+- Readiness note: `docs/directory-introspection-readiness.md`
+
+Do not claim a directory listing or proxy integration until the external directory or repo verifies it. README keywords are a signal, not proof of a working payment path.
+
+## Lightning Wallet MCP comparison
+
+Lightning Wallet MCP is a Bitcoin wallet MCP with directory-facing Glama badge work and x402 fallback positioning. That is a useful wallet product. AgentPay MCP is narrower and stricter for paid MCP spend control:
+
+- x402 payment-tool focus through `x402_pay`
+- policy checks before signing
+- non-custodial local key posture
+- explicit approval modes
+- daily and per-call caps
+- directory metadata meant for catalog introspection
+- audit rows that connect payments to agent tool calls
+
+If the buyer question is "give my agent a Bitcoin wallet," Lightning Wallet MCP may be the right comparison. If the buyer question is "let my agent pay x402 endpoints without runaway spend," AgentPay MCP is the sharper fit.
+
+## README checklist for paid MCP directories
+
+Keep these signals visible for Glama, Smithery, and other MCP catalogs:
+
+- stable npm badge
+- stable Glama badge or listing link
+- exact install command
+- Docker build path
+- MCP server name
+- tool count from live introspection
+- required payment tools
+- non-custodial key warning
+- approval and spend-cap summary
+- link to the latest proof artifact or PR comment
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpay-mcp",
-  "version": "4.1.6",
+  "version": "4.1.8",
   "mcpName": "io.github.up2itnow0822/agentpay",
   "description": "AgentPay MCP Server - Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments. Patent Pending.",
   "main": "dist/index.js",