Agentoracle

Tanilo MCP 服务

一种 MCP 服务，可将 Claude Desktop、Cursor、Windsurf 或任何其他 MCP 客户端连接到 Tanilo API：https://api.tanilo.io。

Tanilo 会在 AI Agent 采取行动前检查前提条件。此服务提供两项检查：合同价格检查和支出上限检查，以及两份状态文档。它调用的路由目前处于免费测试阶段，有速率限制，无需密钥。此服务不保存任何机密信息，也不会进行任何付款。

Tanilo 在 2026 年 9 月之前名为 AgentOracle。版本不高于 2.1.2 的版本以 agentoracle-mcp 发布；该软件包已停止维护。

本 README 介绍的是 3.1.0 版本。以下输出是通过针对实时 API 运行工具获取的：合同价格检查的日期为 2026-10-08，支出上限检查的日期为 2026-10-13。

---

安装

npx tanilo-mcp

Claude Desktop

打开 Claude Desktop 配置文件：

Mac： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

添加以下内容，然后重启 Claude Desktop：

{
  "mcpServers": {
    "tanilo": {
      "command": "npx",
      "args": ["-y", "tanilo-mcp"]
    }
  }
}

Cursor（Settings → MCP → Add Server）和 Windsurf（Settings → MCP Servers → Add）使用相同的 tanilo 配置块。

---

工具

check-contract-price

这份报价是否符合你提供的条款？在 Agent 接受报价前，contract_price_match 会将报价的单价与所提供条款中适用的条款进行比较，并在签名成功时为结果签名。

此过程不涉及模型：结果通过算术运算和精确比较得出，任何持有相同输入的人都可以重新计算。条款由你提供；Tanilo 不会保存或查询你的合同。结果有三种：已验证、已驳回，或附带原因的无法确定。已验证表示价格符合所提供的条款。是否付款由你的策略决定。

输入：offer（包含 unit_price、currency、unit，以及可选的 quantity、seller、sku、offered_at）和 terms（一个列表；每项包含 agreement_id、version、currency、unit，以及 price_per_unit 或 tiers，另可包含 seller、product_scope、effective_from、effective_to、supersedes）。价格和数量使用十进制字符串，例如 "2.00"。完整的输入规则、阶梯价格和修订条款说明见 https://tanilo.io/docs/contract-price-check。

该工具会返回检查结果和签名收据。以下是 2026-10-08 从实时 API 获取的文档示例输出（报价为每次调用 USD 2.00，所提供的条款为每次调用 USD 1.00），已精简：

{
  "verdict": "halt",
  "state": "contradicted",
  "outcome": "fail",
  "reason": "price_mismatch",
  "recommendation": "offer price differs from the applicable term among the supplied terms",
  "evidence": {
    "rule_id": "contract-price-match/v0.1",
    "terms_source": "caller_supplied",
    "expected": { "price_per_unit": "1.00", "currency": "USD", "unit": "call" },
    "offered": { "unit_price": "2.00", "currency": "USD", "unit": "call", "quantity": "1" },
    "difference_per_unit": "1.00",
    "offer_is": "above_term_price"
  },
  "check_mode": "deterministic",
  "canonical_sha256": "sha256-…",
  "kid": "tanilo-2026-10-ed25519-7d885da9",
  "jwks_url": "https://tanilo.io/.well-known/jwks.json",
  "receipt": { "payload": "…", "signatures": [ … ] }
}

对于 "terms": []，相同报价会得到 state 为 indeterminate、reason 为 no_applicable_term、verdict 为 halt。

有效签名可以证明哪些密钥为这些字节签名，以及这些字节自签名后未被更改。但它无法证明所提供的条款真实有效。你可以使用 tanilo-receipt-verify，针对 https://tanilo.io/.well-known/jwks.json 中的密钥集离线验证签名：

pip install tanilo-receipt-verify
python3 -c "import json; from tanilo_receipt_verify import verify; r = verify(json.load(open('receipt.json')), jwks_by_issuer={'https://tanilo.io/.well-known/jwks.json': json.load(open('jwks.json'))}); print(r.status, r.canonical_sha256)"

其中，receipt.json 存放工具的 receipt 对象，jwks.json 存放密钥集。

check-spend-cap

此报价是否在你提供的上限内？在 Agent 确认购买之前，spend_cap 会精确地将报价的单价乘以数量，并将总额与你提供的剩余上限进行比较。签名成功时，它会为结果签名。

你需要提供上限和 already_spent。此检查不会检索预算余额、维护实时余额或预留资金。结果有三种：已验证、已否定，或无法判定并附带原因。已验证的结果表示报价总额在剩余上限内。是否付款由你的策略决定。

输入：offer（unit_price、currency，以及可选的 quantity、offered_at、seller、sku）和 cap（amount、currency、scope，取值为 per_purchase 或 per_period；若为 per_period，还需提供 already_spent 和包含 from、to 的 period；cap_id 可选）。claim_hash 和 agent_id 为可选项，格式与 check-contract-price 相同。格式详见文档页面：https://tanilo.io/docs/spend-cap-check。

工具会返回检查结果和签名收据。以下是 2026-10-13 为文档示例实时捕获的内容（三次调用，报价均为 USD 12.50，上限为 USD 100.00，其中已支出 USD 70.00），经删减：

{
  "verdict": "halt",
  "state": "contradicted",
  "outcome": "fail",
  "reason": "cap_exceeded",
  "recommendation": "offer total exceeds the remaining cap the caller supplied",
  "offer_total": "37.50",
  "remaining": "30.00",
  "excess": "7.50",
  "cap_already_exhausted": false,
  "evidence": {
    "rule_id": "spend-cap/v0.1",
    "cap_source": "caller_supplied",
    "offer_total": "37.50",
    "remaining": "30.00",
    "excess": "7.50",
    "cap_already_exhausted": false,
    "offer_sha256": "sha256-…",
    "cap_sha256": "sha256-…",
    "steps": [ … ]
  },
  "check_mode": "deterministic",
  "canonical_sha256": "sha256-…",
  "kid": "tanilo-2026-10-ed25519-7d885da9",
  "jwks_url": "https://tanilo.io/.well-known/jwks.json",
  "receipt": { "payload": "…", "signatures": [ … ] }
}

将 "already_spent": "62.50" 设为此值时，同一报价恰好达到上限：state 为 verified，remaining 为 37.50，excess 为 null，verdict 为 act。

请像验证 check-contract-price 的收据那样，使用你已验证属于 Tanilo 的密钥集来验证收据签名。有效签名可证明签名内容通过所选密钥验证且未被篡改。但它不能证明所提供的上限真实、已获批准或仍然有效，也不能证明该购买已获授权。

check-health

返回 API 的状态文档（GET /health）：服务状态、当前路由及其价格、已退役的路由和速率限制。

get-manifest

返回 API 的发现文档（GET /.well-known/x402-manifest.json）。其中不列出任何可付费资源：付费研究路由已于 2026-10-04 退役。

---

此服务不会做什么

• 它目前还没有用于 Tanilo 理赔检查的工具（POST /evaluate）。该路由在 Beta 期间免费，可直接调用；请参阅 https://tanilo.io/pricing。
• 它不会付款、持有钱包或读取任何密钥。早期版本中的 x402 付款代码已移除。
• 它不会自行验证签名；请按上述方式使用 tanilo-receipt-verify。

开发

npm install
npm run build
npm test          # starts the built server over stdio and calls the live API (free beta route)

将 TANILO_PYTHON 设置为已安装 tanilo-receipt-verify 的 Python；测试也会离线验证返回收据的签名。将 TANILO_API_BASE 设置为其他主机，以便让服务连接到该主机（仅用于测试）。

---

链接

• tanilo.io — 网站和文档
• tanilo.io/docs/contract-price-check — 此服务提供的检查
• tanilo.io/docs/spend-cap-check — 支出上限检查
• tanilo.io/trust — 密钥，以及签名能证明和不能证明的内容
• tanilo-receipt-spec — 收据格式
• tanilo-receipt-verify — 离线签名检查

联系：[email protected]

采用 MIT 许可证。TK Collective LLC。