内容
# valta-mcp
[](https://github.com/Billionaire664/valta-mcp/actions/workflows/ci.yml)
[](./LICENSE)
适用于 [Valta](https://valta.co) 的 MCP（模型上下文协议）服务器，用于 AI 代理的财务治理。通过 MCP 工具公开 Valta 的支出门控和审计跟踪，允许任何兼容 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）直接调用它们。
## 这是什么 - 以及这不是什么
该服务器是 Valta 的实际托管 REST API 的薄包装。它不实现任何支出逻辑、限制或哈希本身 - 这里的每个工具调用都是对 `https://valta.co/api/v1/...` 的直接调用，实际的执行（支出门控、审计链）发生在那里。该存储库是协议适配器，而不是执行引擎。
**重要，请在使用此功能之前阅读：** 大多数这些工具都是建议性的，而不是强制性的。工具描述告诉模型“在花费之前调用此工具”是指导，而不是保证。例如，`valta_request_spend` 仅控制通过它路由的支出 - 它不会拦截或阻止通过其他工具、API 或 webhook 发生的支出。
**一个工具不同：`valta_proxy_request`。** 与其要求模型在其他地方花费之前进行检查，此工具实际上是支出 - 代理声明出站调用的成本，并通过 Valta 路由实际调用，Valta 会根据钱包限制检查它，如果批准，则使用您自己的存储凭证进行实际请求。如果它被阻止，则实际提供商永远不会被联系。 这是真正的代码级保证，而不是荣誉系统 - 但仅适用于 Valta 已配置为代理的特定服务（目前：**Stripe、Serper、Polygon**）。通过此代理以外的其他渠道发生的任何支出（代理自己的独立 API 密钥、webhook、此服务器不知道的工具）都超出这些工具的可见或阻止范围。有关更多信息，请参见下面的[设计说明](#设计说明)。
## 安装
```bash
npm install -g valta-mcp
```
或直接运行而无需安装：
```bash
npx valta-mcp
```
## 配置
在 [valta.co/dashboard](https://valta.co/dashboard) → 设置 → API 密钥 → 创建密钥处获取 API 密钥。
将其添加到 MCP 客户端的配置中（例如 Claude Desktop 的 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"valta": {
"command": "npx",
"args": ["valta-mcp"],
"env": {
"VALTA_API_KEY": "sk_valta_your_key_here"
}
}
}
}
```
## 工具
| 工具 | 功能 |
|---|---|
| `valta_check_balance` | 读取代理的钱包余额和限制 |
| `valta_request_spend` | 请求支出的授权 - 由实际支出门控批准或拒绝 |
| `valta_create_wallet` | 创建具有可选支出限制的新命名钱包 |
| `valta_freeze_agent` | 终止开关 - 冻结代理的钱包，阻止进一步支出 |
| `valta_unfreeze_agent` | 恢复冻结代理的钱包 |
| `valta_get_audit_trail` | 读取支出决策的哈希链接审计跟踪 |
| `valta_list_wallets` | 列出帐户上的所有命名钱包 - 使用此工具在检查余额/支出之前发现钱包名称 |
| `valta_transfer_funds` | 在两个代理钱包之间直接转移 USDC |
| `valta_list_agents` | 列出帐户上的所有代理 |
| `valta_get_agent` | 获取单个代理的详细信息 |
| `valta_run_agent` | 触发代理运行任务 |
| `valta_get_agent_run` | 检查特定代理运行的状态/结果 |
| `valta_list_policies` | 列出帐户上配置的支出政策 |
| `valta_set_policy` | 创建新的支出政策（每日上限、每笔交易上限） |
| `valta_proxy_request` | 通过 Valta 的支出门控出口代理向连接的服务（Stripe、Serper、Polygon）发出实际出站调用 - 事先声明成本，只有获得批准时才到达实际提供商，失败时自动退款 |
| `valta_list_proxy_requests` | 列出出口代理处理的所有调用的收据 - 允许、阻止、退款或待批准，以及原因 |
`src/index.ts` 中的每个工具描述都明确说明了它强制执行的内容和不执行的内容 - 在将其应用于涉及实际资金的任何内容之前请阅读这些。
## 设计说明
**为什么没有“不可绕过的系统”。** 该项目的早期草案曾考虑过发布一个系统提示指令块，声称使支出门控“不可绕过”。但这种说法站不住脚，原因有两个：
1. **MCP 服务器不控制主机的系统提示。** Claude Desktop、Claude Code、Cursor 等主机各自拥有自己的系统提示。MCP 服务器提供工具，在某些情况下，还提供有限的 `instructions` 字段 - 它无法将绑定、全局强制执行的规则注入到对话中。
2. **系统提示是模型的请求，而不是代码级约束。** 即使主机显示服务器指令，代理仍然可以被提示注入、越狱或完全通过它不知道的另一个工具路由。声称相反将是正是这个项目试图解决的漏洞 - 信任模型自我监管是 Valta 的支出门控最初构建的失败模式。
**实际提供保证的内容和不提供的内容。** 该服务器中现在有两种不同级别的强制执行，这很重要：
- 通过调用 `valta_request_spend` 授权的支出确实会针对实际限制进行检查 - 但前提是代理选择首先调用它。漏洞在于通过代理可以访问的其他渠道发生的支出。
- 通过 `valta_proxy_request` 路由的支出在实际调用发生之前会进行检查 - 没有步骤允许代理跳过检查并仍然进行支付，因为支付触发调用和检查是同一操作。这关闭了上述漏洞，但仅适用于服务器已配置为代理的服务（目前：**Stripe、Serper、Polygon**）- 将其扩展到新的服务意味着添加该提供商特定身份验证方案的实际凭证处理逻辑，而不是翻转配置标志。
如果用例需要对上述未列出的服务提供硬保证，则需要将该服务添加到 Valta 的代理门控中 - 请提出问题或提交 PR。
## License
MIT.
