Veriko

Veriko MCP

此 MCP 服务可将 Veriko 连接到 ChatGPT、Cursor 或其他 MCP 客户端：你可以让助手 例如检查 Banxico 的 CEP 中的一笔付款、告诉你之前的验证结果，或下载凭证。

它涵盖 70 项公开机器对机器操作中的 68 项。助手在这里能做的事情与 API 密钥 能做的相同，但永久删除验证除外：此操作无法撤销，因此不会作为工具提供。

立即试用

需要 Node.js 20 或更高版本。

git clone https://github.com/veriko-mx-labs/veriko-mcp.git
cd veriko-mcp
npm ci
npm run build

现在已有一个可执行服务器，位于 dist/index.js。无需 API 密钥即可查看它的响应；公共计划配置文件不需要凭证：

VERIKO_MCP_PROFILE=plans VERIKO_MCP_MAX_RISK=read node dist/index.js

该进程会通过 stdin 等待 MCP 消息；通常由客户端启动它，而不是你手动启动。下面是主机配置，其中包含你刚刚构建的副本的绝对路径：

{
  "mcpServers": {
    "veriko": {
      "command": "node",
      "args": ["/ruta/a/veriko-mcp/dist/index.js"],
      "env": {
        "VERIKO_API_KEY": "veriko_...",
        "VERIKO_MCP_PROFILE": "core",
        "VERIKO_MCP_MAX_RISK": "write"
      }
    }
  }
}

可在 app.veriko.mx 获取密钥。密钥绝不会作为工具参数传递：服务器只会从 VERIKO_API_KEY 读取密钥，因此模型正在读取的页面中注入的文本无法索取该密钥。

哪些操作会消耗额度

veriko_validate_direct 和 veriko_validate_ocr 会消耗计划额度，并在请求被接受时扣除。它们各自的说明中都有提示，因为 Agent 循环可能在几分钟内耗尽每月额度。其余目录中的工具只会查询、导出或下载，不会消耗验证额度。

配置文件

VERIKO_MCP_PROFILE 接受 core、all、一个类别或以逗号分隔的多个类别。

配置文件	提供的工具
core	验证、列出、查询和下载 CEP
validations	完整的验证流程
webhooks	端点和投递记录
catalog	银行、SPEI 日历、BIN 和 Banxico 状态
beneficiaries	列表和批量导入
usage	使用量、限制和导出
account	个人资料和重试策略
dashboard	运营摘要
plans	公共计划
insights	汇总指标
finance	摘要、预览和下载
billing	当前订阅
all	可用的 68 个工具

配置文件决定模型能看到哪些类别。风险则由 VERIKO_MCP_MAX_RISK 独立控制：

• read：仅允许查询和下载；
• write（默认）：包括验证和常规更改；
• destructive：增加删除、取消、密钥轮换和确认导入操作。

提供各配置文件所需的开销

在模型调用任何工具之前，提供工具就会占用上下文。以下数据来自服务器本身：使用 npm run measure:catalog 测得 tools/list 响应的字节数。Token 数按每个 token 3.6 字节估算，并非实际分词结果，仅用于比较各配置文件。

配置文件	工具数	tools/list 字节数	估算 Token 数
core	5	6,645	~1,846
validations	14	15,761	~4,378
webhooks	10	18,945	~5,263
catalog	5	2,845	~790
beneficiaries	14	10,343	~2,873
usage	7	3,756	~1,043
account	3	1,953	~543
dashboard	1	557	~155
plans	2	1,017	~283
insights	4	2,337	~649
finance	7	6,470	~1,797
billing	1	503	~140
all	68	64,477	~17,910

使用 Node 22 和 destructive 风险级别测量，以免隐藏工具。all 的开销是 core 的 9.7 倍；因此默认配置文件为 core，需要时再按类别扩展。

架构

• 使用官方 JavaScript SDK 作为通往 API 的唯一传输层。 代码通过 @veriko-mx/sdk-runtime 导入它，这是一个稳定的别名， 可在不重写服务的情况下切换分发来源。
• SDK runtime 随 MCP tarball 一同提供。
• 根据配置文件和风险公布工具。
• 下载内容以 veriko://artifact/... 资源的形式返回；绝不以文本中的 base64 形式返回，也不会自动写入工作区。
• 在调用 SDK 前验证规范的 base64 和公开限制：OCR 凭证（图像或 PDF） 为 12 MB，受益人导入为 20 MB。stdio 传输支持完整导入最大大小的数据。
• 如果存在，错误会使用 error.code、状态、指针、requestId 和 retryAfter；API 中可翻译的文本不作为约定。

幂等性

如果传入 idempotencyKey，则保留该值。如果未传入，服务会根据 operationId 和规范参数计算 veriko_mcp_v1_<sha256>。对于二进制输入， 使用内容哈希，而不是本地路径。同一操作会生成相同的键；更改相关数据则会生成不同的键。

开发

npm install
npm run check
npm run check:surface
npm run measure:catalog

check:surface 会将完整目录与 SDK 的公开 spec 进行比较，并固定其 SHA-256。 目录未公布的操作（删除验证记录）会单独声明在 NOT_EXPOSED_OPERATIONS 中。新增、移除或隐藏操作，使用不同于 API 密钥的身份验证方案，或任何约定变更，都会导致此检查失败。同步工作流会将新的约定 PR 保留为草稿，附带已运行的 CI，并在正文中概述变更，以便在接受前进行审查。

测试不会使用真实 API。test/server.test.ts 使用虚假 SDK 在内存中连接 MCP 客户端和服务。

传输方式

发布的入口为 stdio。核心位于 createVerikoServer()，不依赖传输方式，因此未来的 Streamable HTTP 可以复用目录、策略、错误和资源。远程端点需要按用户进行身份验证，且不会被视为与本地软件包等效。

安全

请参阅 SECURITY.md。切勿创建包含 API 密钥、真实有效载荷、凭证、账号号码或未清理响应的 issue。

许可证

MIT。