ClawPay MCP — Non-custodial x402 Payment Layer for AI Agents

Name: ClawPay MCP — Non-custodial x402 Payment Layer for AI Agents
Author: up2itnow0822

本地服务

github.com/up2itnow0822金融数据82 天前更新

代码仓库

关于 ClawPay MCP — Non-custodial x402 Payment Layer for AI Agents

AgentPay MCP 是通过 stdio 提供钱包操作与 x402 支付的 MCP 服务，供 AI Agent 执行链上支付和相关操作。它从本地进程读取签名密钥，并以默认拒绝的支出策略限制资金转移。

主要功能

01钱包部署与信息查询
02x402 报价、支付和会话
03支出策略与预算检查
04代币查询、余额和转账
05兑换、USDC 跨链及托管

适用场景

01在策略限制内执行 x402 付款
02检查预算和钱包交易历史
03为 Agent 部署钱包并配置支出策略
04执行代币兑换或 USDC 跨链

MCP 相关

该 stdio MCP 服务将 Agent Wallet SDK 功能作为工具提供，涵盖钱包、支付、策略、代币、执行、信任和历史操作。签名密钥由调用方通过本地环境变量提供。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "clawpay": {
      "command": "npx",
      "args": [
        "-y",
        "clawpay-mcp"
      ],
      "env": {
        "AGENT_PRIVATE_KEY": "<AGENT_PRIVATE_KEY>",
        "BASE_RPC_URL": "<BASE_RPC_URL>"
      }
    }
  }
}

启动命令npx -y clawpay-mcp

需要配置的环境变量

AGENT_PRIVATE_KEY密钥Private key for the agent wallet (hex, without 0x prefix)

BASE_RPC_URLBase RPC URL (defaults to public Base mainnet)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmclawpay-mcp1.1.2stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
token_id	string	是	将拥有此钱包的 NFT 代币 ID（例如，"1"）
nft_contract_address	string	否	NFT 合约地址。默认使用 NFT_CONTRACT_ADDRESS 环境变量。
factory_address	string	否	工厂合约地址。默认使用 FACTORY_ADDRESS 环境变量。

详细介绍

AgentPay MCP

AgentPay MCP 是一个用于 x402 支付和钱包操作的 stdio Model Context Protocol 服务。它将 Agent Wallet SDK 函数作为 MCP 工具提供，并从本地进程环境中加载由调用方控制的签名密钥。

当前 npm 包为 agentpay-mcp v5.0.0。

无需资金即可开始

检查已安装的命令，无需加载钱包凭据：

npx -y agentpay-mcp --version
npx -y agentpay-mcp --help

使用 AgentPay Wallet Starter 验证无资金情况下允许、需要审批和被阻止的策略结果。

MCP 客户端配置

钱包工具会读取以下环境变量：

变量	钱包工具是否必需	含义
`AGENT_PRIVATE_KEY`	是	本地热钱包签名密钥
`AGENT_WALLET_ADDRESS`	是	已部署的 `AgentAccountV2` 地址
`CHAIN_ID`	否	`8453` 或 `84532`；默认为 Base 主网
`RPC_URL`	否	调用方选择的 Base RPC 端点
`FACTORY_ADDRESS`	用于部署	钱包工厂地址
`NFT_CONTRACT_ADDRESS`	用于部署	绑定到钱包的代币合约
`SESSION_TTL_SECONDS`	否	本地会话时长，以秒为单位

操作员安全变量。它们仅从服务环境中读取，无法通过 MCP 更改：

变量	默认值	含义
`AGENTPAY_POLICY_DAILY_LIMIT_ETH`	未设置	操作员 24 小时滚动限额（ETH 等值）
`AGENTPAY_POLICY_PER_TX_CAP_ETH`	未设置	操作员单笔交易上限（ETH 等值）
`AGENTPAY_POLICY_ALLOWED_RECIPIENTS`	未设置	以逗号分隔的操作员收款方允许列表
`AGENTPAY_ALLOW_UNPOLICED_SPEND`	关闭	`1` 允许在没有操作员策略的情况下转移价值，仅依赖链上限额
`AGENTPAY_X402_MAX_PAYMENT`	未设置	叠加于每次调用 x402 上限之上的 USDC 限额；设置后会拒绝非 USDC 的 x402 支付
`AGENTPAY_STATE_DIR`	未设置	用于存放 fsync'd 支出意图日志的目录；锁和带键结算会在重启后保留，并自动将日志压缩至其有效状态。该目录同一时间只能由一个进程持有（`spend-intents.lock`）。如果日志无法读取或 fsync'd，或者另一个正在运行的进程持有该目录，则会拒绝转移价值
`AGENTPAY_ALLOWED_PRIVATE_HOSTS`	未设置	以逗号分隔的主机列表，允许向其发出站请求并访问其私有地址
`AGENTPAY_ALLOW_PRIVATE_NETWORK`	关闭	仅用于开发：允许访问私有目标和使用纯 `http`

如果未设置至少一个 AGENTPAY_POLICY_* 变量，且未设置 AGENTPAY_ALLOW_UNPOLICED_SPEND=1，所有会转移价值的工具都会拒绝支出。

MCP 配置示例：

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "agentpay-mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "<secret-reference-or-local-key>",
        "AGENT_WALLET_ADDRESS": "0x<deployed-wallet-address>",
        "CHAIN_ID": "84532",
        "AGENTPAY_POLICY_PER_TX_CAP_ETH": "0.01",
        "AGENTPAY_POLICY_DAILY_LIMIT_ETH": "0.1",
        "AGENTPAY_X402_MAX_PAYMENT": "1",
        "AGENTPAY_STATE_DIR": "<writable-private-directory>"
      }
    }
  }
}

请勿提交真实的签名密钥。如果客户端或操作系统提供了密钥管理机制，请使用该机制。先在 Base Sepolia 上开始，再使用 Base 主网。

工具分组

src/index.ts 中的工具注册表提供以下分组：

分组	示例
钱包	`deploy_wallet`、`get_wallet_info`、`queue_approval`
支付	`send_payment`、`x402_quote`、`x402_pay`、x402 会话工具
策略	`set_spend_policy`、`check_budget`、OTel 预算工具
代币	查询、自定义代币注册、余额和转账
执行	Swap、USDC 跨链桥和 mutual-stake 托管
信任	ERC-8004 身份、信誉和 UAID 验证
历史记录	用于钱包合约事件的 `get_transaction_history`

工具架构和处理程序位于 src/tools/ 下。

安全边界

这些边界比功能列表更重要：

服务会将 AGENT_PRIVATE_KEY 读入本地 Node.js 进程，并使用 viem 签名。请保护该进程、环境和 MCP 客户端配置。
支出策略默认拒绝。操作员策略来自 AGENTPAY_POLICY_* 环境变量，只加载一次，且无法通过 MCP 更改或清除。若未设置该策略，除非操作员设置 AGENTPAY_ALLOW_UNPOLICED_SPEND=1，否则会拒绝资金转移。
set_spend_policy 只能收紧策略。每次调用都会为其作用范围添加一层；任何提高限额、移除约束或扩大允许列表的请求都会被拒绝，且先前各层会保留其滚动窗口记账。放宽策略需要操作员重启。所有策略状态仍保存在进程内，重启后会重置。
x402_pay 和 x402_session_start 要求提供 max_payment_eth 和 pay_to。资产始终会被绑定：默认使用链上的 USDC，除非 asset 指定其他资产；也可以绑定 network。如果 402 指定了其他收款方、资产或网络，指定了零地址，或扣款金额（本金加 0.77% 协议费）超过上限，则会在任何钱包写入操作之前拒绝该请求。 AGENTPAY_X402_MAX_PAYMENT 是 USDC 上限；设置后会拒绝非 USDC 付款。请先使用 x402_quote 查看报价条款。
如果付款已结算，但响应未送达——响应失败，或付款请求收到任何非 2xx 状态码——则对该主机（任何路径、端口或名称写法）以及该收款方（无论位于哪个主机）的所有新 x402 付款都会被锁定，直至操作员完成核对。锁定会在调用钱包之前写入，因此即使发生崩溃也不会丢失。
由调用方选择的出站请求（x402、报价、会话、OTel kill 回调）使用安全传输：仅允许 https（kill 回调仅在主机位于 AGENTPAY_KILL_CALLBACK_ALLOWED_HOSTS 时可使用 http），拒绝私有、环回、链路本地和元数据目标，只解析一次 DNS，并将套接字固定到已验证的地址，不自动重定向，响应正文上限为 2 MiB（渲染后为 1 MiB）。
send_payment、send_token、swap_tokens、bridge_usdc、create_escrow、 x402_pay 和 x402_session_start 均在支出意图中运行。相同的重试请求会重放；idempotencyKey 可区分金额相同的付款；广播后结果不明时，会锁定该意图且不设定时器。除非由 AGENTPAY_STATE_DIR 将锁定状态写入日志，否则锁定仅在进程内有效。请使用 agentpay-mcp spend-intents list 和 resolve <id> settled|unsettled 进行核对；这属于本地 CLI，而非 MCP 工具。 <id> 是 list 为每个意图打印的 shell 安全 id: 句柄。 settled（资金已转移）会清除锁定，并永久停用带键意图的 idempotencyKey；不带键的意图没有可停用的键，因此相同的新请求会成为一笔新付款（请使用 idempotencyKey 确保重试安全）。unsettled（资金未转移）会清除锁定，以便重试付款。同一时间只能有一个进程使用某个状态目录：执行 resolve 前请先停止服务（服务运行时，list 会显示只读快照），并为每个服务指定独立的 AGENTPAY_STATE_DIR。
idempotencyKey 不得包含控制字符、不可见格式字符或换行分隔符；打印密钥时会进行转义，使其不会在 shell 中生效。
send_payment 从代币注册表或代币合约获取小数位数；若 token_decimals 不同，则会在签名前拒绝请求。
仅当钱包所有者直接在 AgentAccountV2 上配置限额时，链上限额才会生效。应用策略不会写入这些合约限额，只有在所有者密钥与 Agent 密钥分开保存时，超限交易才会成为人工审核关卡。
get_transaction_history 会读取链上钱包事件；对于未限定范围的 all 查询，还会列出由此服务进程发起的 x402 结算（已付款响应的最终 URL，可能因重定向而不同于 402 发布方、方法、金额、代币、收款方、交易哈希、重放次数）。这些 x402 收据表示付款已广播（已返回交易哈希），并不表示收据已确认。收据仅保存在内存中，最多保存 256 条，重启后会丢失。在区块范围查询中不会列出这些收据。这不是 MCP 请求日志：它不会记录链上操作前被拒绝的尝试或只读调用。
运行时钱包配置目前支持 Base 主网和 Base Sepolia。不支持的链 ID 会在 src/utils/client.ts 中以安全失败方式处理。
兑换、跨链桥、托管和付款工具可能会转移资金并消耗 Gas。请使用受限金额并配合独立的钱包限额进行测试。详细的控制映射和已知限制请参阅 docs/security-posture.md。

从 4.x 升级

v5.0.0 是一次有破坏性变更的安全版本。升级前：

设置运营方策略（AGENTPAY_POLICY_*），或明确通过 AGENTPAY_ALLOW_UNPOLICED_SPEND=1 选择退出；否则所有支出都会被拒绝。
对每次 x402_pay 和 x402_session_start 调用传入 max_payment_eth 和 pay_to。先使用 x402_quote 查看条款。
不要再依赖 set_spend_policy 来提高或清除限额。
将任何 http 或私有网络 x402 端点迁移到 https，或通过 AGENTPAY_ALLOWED_PRIVATE_HOSTS（生产环境）或 AGENTPAY_ALLOW_PRIVATE_NETWORK=1（仅限开发环境）允许该端点。
在长期运行的服务上设置 AGENTPAY_STATE_DIR。

docs/security-remediation-2026-10.md 将每项发现对应到其修复方案和测试。

技术证明索引

该仓库通过带版本的文档保存更深入的互操作性和买方安全证据：

docs/agentpay-buyer-flow-parity.md 涵盖类型化支付错误和买方流程行为。
docs/paid-mcp-gateway-hardening.md 涵盖默认拒绝控制和配额范围。
docs/agentpay-five-tool-parity-proof.md 记录五工具一致性检查。
docs/agentpay-escrow-reputation-boundary.md 定义托管和信誉边界。
docs/paid-mcp-proxy-discovery-readiness.md 记录发现就绪证据。
docs/x402-chain-neutral-gateway-profile.md 定义打包的链无关配置。
docs/x402-dynamic-paid-mcp-manifest-drift.md 记录检查过时付费工具元数据的方法。
docs/mcp-registry-listing-proof.md 和 llms.txt 提供目录元数据。
docs/smithery-paid-mcp-installation.md 和 examples/smithery-paid-mcp-installation 说明打包后的 Smithery 路径，但不声称已有实时列表。
docs/paid-provider-health-proof.md 定义提供方健康状况证据。
docs/hosted-x402-proxy-verification.md 定义托管代理预检。
docs/x402-native-vs-stripe-proxy.md 区分本地支出控制与托管代理计费。
docs/dependency-pin-policy.md 定义支付关键软件包的发布门槛。

AgentPay 将 viem 精确固定在 2.57.4。

目录比较是针对 [email protected] 进行的；本 README 顶部的软件包版本为当前发行版。

验证干净检出

npm ci
npm run build
npm run typecheck
npm test
npm run lint
npm run security
npm run smoke:clean-install

CI 工作流与定期的每日审查和修复工作流彼此独立。定期审查失败不代表产品测试结果，修复成功也不能替代 CI。

支持与披露

通过 GitHub issue 队列提交产品缺陷。
通过 SECURITY.md 报告安全问题。
贡献规则见 CONTRIBUTING.md。

License

MIT. See LICENSE.

支持 Markdown

登录后评论

基本信息

作者: up2itnow0822
语言: node
版本: 1.2.0
传输方式: stdio
收录时间: 2026年3月5日
最近更新: 2 天前
官方 Registry: io.github.up2itnow0822/clawpay-mcp

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。