内容
# @three-ws/agentcore-payments-mcp
用于 three.ws Agent Payment Sessions 的 MCP 服务器 — 在不暴露私钥的情况下控制代理 x402 的支出。
## 概念
> 代理不持有钱包。它提出支出。治理强制执行策略。
**支付会话** 是一个预算信封，您可以从 three.ws 积分中一次性资助。您将会话令牌交给代理；代理通过此服务器调用付费 x402 端点。平台的钱包签署每笔交易。会话的允许列表、每笔交易的上限和总预算在服务器上原子强制执行 — 代理永远不会过度消费。
## 快速开始
```bash
# 配置
export THREE_WS_SESSION="__Host-sid=<your-session-cookie>"
export PAYMENT_SESSION_TOKEN="pss_<session-id>_<random>"
# 运行
npx @three-ws/agentcore-payments-mcp
```
MCP 客户端配置（`~/.cursor/mcp.json`, Claude Desktop, 等）：
```json
{
"mcpServers": {
"three-ws-payments": {
"command": "npx",
"args": ["-y", "@three-ws/agentcore-payments-mcp"],
"env": {
"THREE_WS_SESSION": "__Host-sid=...",
"PAYMENT_SESSION_TOKEN": "pss_..."
}
}
}
}
```
## 环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `THREE_WS_SESSION` | 会话管理工具必填 | 用于创建/列出/取消会话的浏览器会话 cookie (`__Host-sid=...`) |
| `PAYMENT_SESSION_TOKEN` | `pay_with_session` 默认必填 | 创建会话时返回的令牌；在未提供内联令牌时作为默认令牌传递 |
| `THREE_WS_BASE` | 否 | 基础 URL（默认：`https://three.ws`） |
| `THREE_WS_TIMEOUT_MS` | 否 | 请求超时（毫秒）（默认：30000） |
## 工具
### `create_payment_session`
从您的积分中创建一个新的会话。
```json
{
"budget_usd": 10.00,
"label": "研究代理 — 六月冲刺",
"expiry_seconds": 86400,
"max_per_tx_usd": 0.50,
"allowed_hosts": ["api.example.com", "data.provider.io"],
"network": "solana"
}
```
返回 `{ session, token }`。**令牌仅显示一次 — 立即存储。**
### `pay_with_session`
使用会话令牌支付 x402 端点费用。平台钱包签署；强制执行会话的策略。
```json
{
"url": "https://api.example.com/data",
"method": "GET",
"session_token": "pss_...",
"idempotency_key": "run-42-fetch-data"
}
```
返回 `{ ok, paid, result, payment, session }`，包含交易哈希、浏览器链接和更新的预算。
如果省略 `session_token`，则使用 `PAYMENT_SESSION_TOKEN` 环境变量。
### `check_payment_session`
检查会话的预算、状态和最近的支付。
```json
{ "session_id": "...", "include_executions": true }
```
### `list_payment_sessions`
列出经过身份验证的用户的所有会话，并附带聚合统计信息。
```json
{ "status": "active", "limit": 20 }
```
### `cancel_payment_session`
取消会话，并将未使用的预算退回至您的积分。
```json
{ "session_id": "..." }
```
## 网络支持
| 会话 `network` | 平台支付方 | USDC 合约 |
|---|---|---|
| `solana`（默认） | `X402_AGENT_SOLANA_SECRET_BASE58` | Solana 主网 USDC |
| `base` | `X402_EVM_AGENT_PRIVATE_KEY` | Base 主网 USDC（0x8335…） |
## 与 `@three-ws/x402-mcp` 集成
`@three-ws/x402-mcp` 中的现有 `pay_and_call` 工具现在直接接受 `session_token`：
```json
{
"url": "https://api.example.com/endpoint",
"session_token": "pss_...",
"confirm": true
}
```
这会通过 `/api/pay/execute` 路由支付，而不是本地签名 — 会话治理策略适用。
## 会话生命周期
```
创建（从积分中扣除预算）
└─ 活动 → pay_with_session 调用针对预算的支出
├─ 耗尽（预算完全消耗）
├─ 过期（TTL 到期 — cron 退款剩余预算）
└─ 取消（手动 — 立即退款剩余预算）
```
## 安全属性
- **无密钥暴露**：会话令牌是一个有时间限制的、HMAC 签名的授权。泄露它允许攻击者花费最多剩余预算的主机 — 没有更多。
- **原子预算强制执行**：并发支付使用 SQL `UPDATE … WHERE remaining >= amount RETURNING` — 两个同时请求永远不会集体过度消费。
- **允许列表**：如果设置了 `allowed_hosts`，则治理在签名之前拒绝任何不在列表上的主机请求。
- **每笔交易上限**：`max_per_tx_usd` 防止单笔大额支付耗尽整个预算。
- **SSRF 保护**：所有 x402 目标 URL 在支付签名之前都会针对公共 IP 允许列表和 DNS 解析的服务器端进行验证。
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
该软件是专有的 — 参见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
