为什么需要它
「帮我加上加密支付」—— 没有事实来源的 AI, 给出的是能跑通演示、却在生产静默失败的代码。
- 字段名靠猜 —— 看起来合理, 实际不存在, 直到上线才报错。
- webhook 事件类型编造 —— 监听了一个永远不会触发的事件, 订单永远不发货。
- 签名校验写错 —— 用解析后的 JSON 而不是原始字节验签, 偶发失败且极难复现。
- 端点与字段来自线上实现本身, 不是训练数据里的旧版本。
- 集成指南直接点明那些坑: 验原始字节、只在 payment.settled 发货、两个游标字段要一起回传。
- 能亲自建一笔沙盒单跑通全流程, 而不是写完代码让你自己去试。
你只需要说一句
> 帮我给这个 Next.js 商店接上 USDC 收款, 先用沙盒跑通
agent 会自己查文档、确认你各条链的收款地址配好了没有、建一笔沙盒订单、模拟付款、验证 webhook 收到了 —— 然后才把集成代码交给你。
安装
两分钟, 三步
MCP 是开放协议。任何支持它的客户端都能接 —— 配置形状都一样, 只是文件位置不同。
- 1
拿一枚沙盒密钥
后台 → API 密钥, 创建一枚 sk_test_ 开头的沙盒密钥。零成本, 不碰真钱。
- 2
写进 MCP 配置
Claude Desktop 用 claude_desktop_config.json; Claude Code 用项目里的 .mcp.json; Cursor / Windsurf 在各自的 MCP 设置里, 形状完全一样。
- 3
重启客户端
重启后直接对 AI 说你想做什么。不需要 npm install —— npx 会自动拉取。
{
"mcpServers": {
"finality": {
"command": "npx",
"args": ["-y", "@finality/mcp"],
"env": {
"FINALITY_API_KEY": "sk_test_your_key_here"
}
}
}
}不配 FINALITY_API_KEY 也能用, 只是仅文档类工具可用 —— 适合先让 AI 读懂我们的接口再决定要不要接。
★ 务必从 sk_test_ 沙盒密钥开始。每个工具都会回报当前处于哪种模式, 所以你和 AI 永远清楚这一单是不是真钱。
能力清单
28 个工具
不是把 REST 端点机械包一层 —— 每个工具都带着「什么时候该用它、用错会怎样」的说明进到 AI 的上下文里。
从零到第一笔收款: 读文档、确认收款地址配好了、建单、模拟付款跑通全链路。
finality_docs
检索官方文档与 OpenAPI 规范, AI 的事实来源。
finality_integration_guide
按场景给出集成方案, 并点明该场景特有的坑。
finality_create_payment
建一笔收款单, 拿到收款地址与收银台链接。
finality_simulate_payment
沙盒模拟付款, 不花真钱跑通完整链路。
finality_payout_status
各链收款地址是否配好 —— 接入排查的第一站。不回显地址本身。
finality_x402_supported
实时查支持 x402 自动付款的链与代币, 链上实读。
安全模型
这个 MCP 动不了你的钱 —— 这不是一条政策, 是系统本身的性质。
finality 从不托管商户资金、不持有任何私钥。所以「AI 会不会把我的钱转走」这个问题, 在架构层面就不成立 —— 不是我们承诺不这么做, 是它做不到。
退款与提取: 故意不做成工具
后端只返回未签名交易, 必须你自己的钱包签名广播。让 AI「准备一笔退款」没有意义, 反而会让你误以为它能动钱。
改收款地址: 硬拒 API 密钥
改收款地址、管理 API 密钥这类操作需要登录态会话, 并有邮箱验证码或钱包签名的二次验证。MCP 持有的密钥调用它们只会被拒绝。
密钥不进对话
密钥只从环境变量读, 绝不接受 AI 通过参数传入 —— 否则它会进入对话上下文, 可能被记录或泄露。
★ 能做的只有三类: 建单查单 (不涉及资金转移)、只读报表、文档检索。建单是「写」操作但零资金风险 —— 它只生成一个收款地址, 钱是顾客付进你自己钱包的。