内容
# circle-agent-stack-mcp
MCP 服务器，用于 [Circle's Agent Stack](https://developers.circle.com/agent-stack)。 创建钱包、设置消费策略、发送 USDC 以及支付 x402 定价的端点 — 所有这些都来自工具调用。
```bash
npx circle-agent-stack-mcp
```
## 工具列表
| 工具 | 功能描述 |
|---|---|
| `circle_wallet_create` | 创建代理钱包（开发/托管/智能） |
| `circle_wallet_list` | 列出带有 USDC 余额的钱包 |
| `circle_balance` | 钱包余额 + 最近 10 笔交易 |
| `circle_policy_set` | 设置每日上限、x402 上限、允许/阻止列表 |
| `circle_transfer_usdc` | 向链上地址发送 USDC |
| `circle_x402_pay` | 支付 x402 定价的端点并返回其响应 |
## 快速入门
您需要安装并认证 Circle CLI：
```bash
npm install -g @circle-fin/circle-cli
circle login
export CIRCLE_API_KEY=your_key_here
```
### Claude Desktop
```json
{
"mcpServers": {
"circle": {
"command": "npx",
"args": ["-y", "circle-agent-stack-mcp"],
"env": {
"CIRCLE_API_KEY": "your_key_here"
}
}
}
}
```
### Claude 代码
```bash
claude mcp add circle -- npx -y circle-agent-stack-mcp
```
## 示例
```
您：创建一个名为 eva-treasury 的开发钱包，设置 5 美元每日上限和 0.10 美元 x402 上限，
然后从 https://signals.example.co/btc 的 x402 端点获取今日的 BTC 信号。
Claude：
→ circle_wallet_create("eva-treasury", type="dev")
{ wallet_id: "wal_abc123", address: "0x..." }
→ circle_policy_set("wal_abc123", daily_cap_usdc=5, x402_cap_usdc=0.10)
{ status: "applied" }
→ circle_x402_pay("wal_abc123", "https://signals.example.co/btc", max_price_usdc=0.10)
{ signal: "LONG", confidence: 0.72, price_paid_usdc: 0.05 }
今日 BTC 信号：LONG（72% 置信度）。支付 0.05 美元。
```
## 自主托管与 x402 付费墙
`http-server.ts` 在 x402 付费墙后封装了相同的工具 — 代理按调用付费（以 USDC 而非 API 密钥）。如果您想将 Circle 工具公开为付费服务，则此功能很有用。
```bash
CIRCLE_PAYOUT_ADDRESS=0x... npm run start:http
```
要在本地测试 x402 流程，请在 `examples/x402-demo-server.mjs` 中运行演示服务器。
## 工作原理
v0.1 版本使用 Circle CLI 执行所有操作。这将身份验证处理从此存储库中分离出来，并在工具表面验证之前避免重新实现 API 客户端。v0.2 版本将切换到通过 `@circle-fin/circle-sdk` 的直接 HTTP 连接。
## 安全
您的 Circle API 密钥具有消费权限。始终：
- 在启用自动支付之前设置 `daily_cap_usdc`
- 从 `type="dev"` 钱包开始，而不是主网
- 在生产环境中审查 `allowlist`
- 不要提交 `CIRCLE_API_KEY`
## 路线图
- [ ] `circle_nanopayment_stream` — 流式 x402 支付，用于每代币计费
- [ ] `circle_skills_list` / `circle_skills_call` — Circle Skills 市场
- [ ] 直接 HTTP API 模式（v0.2）— 删除 CLI 依赖
- [ ] 多链 — EURC，CCTP 跨链转账
## 相关链接
- [Circle Agent Stack 文档](https://developers.circle.com/w3s/agent-stack)
- [x402 协议](https://x402.org)
- [模型上下文协议](https://modelcontextprotocol.io)
