VERIDEX

veridex-mcp

适用于 VERIDEX 的 MCP（Model Context Protocol）服务： 通过 BORME 按 CIF 验证西班牙企业，提供可解释的风险评分，并逐步完成 x402 支付流程。

配置完成后，任何 Agent（Claude Desktop、Cursor、VS Code、Claude Code……） 都可以发现并使用验证功能，无需你编写任何 HTTP 代码。

Agente  ──MCP (stdio)──▶  veridex-mcp  ──HTTPS──▶  https://api.veridexia.es/v1/verify
                              │
                              └── no firma pagos: entrega el reto x402 y espera
                                  un X-PAYMENT que produzca una wallet tuya

---

是什么，不是什么

它是 VERIDEX 公共 API 的轻量 MCP 客户端：提供三个工具、明确的类型、类型化错误，并解码 x402 支付请求，让 Agent 准确了解费用、网络、资产和收款地址。

它不是钱包。本服务不会签名、托管密钥或发送交易。它不能替你付款——这是刻意设计的：能够代表用户转移资金的 MCP 服务，就成了一个没有所有者的钱包。它会向 Agent 提供完整且准确的支付请求，并由你控制的钱包完成结算。

它也不会修改 API：它只是 api.veridexia.es 的纯消费者。

---

三个工具

工具	参数	费用	返回内容
verify_company_by_cif	cif（必填）、x_payment、idempotency_key	0.20 USDC（首次调用返回 402）	注册数据、BORME 中的状态、近期记录，以及可解释的 0–100 评分
get_veridex_info	—	免费	从 /.well-known/x402 读取的价格、网络、资产、收款地址和端点
health_check	—	免费	API 状态、运行时间，以及今日请求量和唯一 Agent 数

verify_company_by_cif

// Entrada
{ "cif": "A58818501", "x_payment": null, "idempotency_key": null }

// Salida (ok = true)
{
  "ok": true,
  "cif": "A58818501",
  "company": {
    "cif": "A58818501",
    "name": "…",
    "legal_form": "Sociedad Anónima",
    "status": "active",
    "status_label": "Activa sin incidencias",
    "province": "Málaga",
    "incorporation_date": "2015-10-02",
    "last_borme_deposit": "2025-08-09",
    "administrator": "…",
    "share_capital_cents": 4500000,
    "insolvency_published_on": null
  },
  "risk": {
    "value": 15,                    // 0 = más seguro, 100 = más arriesgado
    "band": "low",                  // low | medium | high | critical
    "reasons": ["…"],
    "signals": [{ "code": "status_active", "points": 15, "description": "…" }],
    "confidence": "high",
    "assurance": "high",            // cuánto se SABE, no cuánto de malo es
    "conclusive": true
  },
  "recent_acts": [{ "date": "2026-08-28", "section": "Sección Primera", "description": "…" }],
  "mock": false,
  "provenance": { "source": "prometiam", "fetched_at": "…", "from_cache": false, "confidence": "high" },
  "payment": null,
  "error": null,
  "guidance": ""
}

risk.assurance 是最容易被误解的字段：assurance: "none" 且 value: 0 表示我们对这家公司一无所知，而不是这家公司是安全的。出现这种情况时，服务会在 guidance 中明确说明。

---

安装

需要 Python 3.10+。

pip install -e mcp-server

这会以可编辑模式安装 veridex-mcp 包及其依赖项 （mcp>=1.9,<2 和 httpx），并提供 veridex-mcp 可执行文件。

检查是否可以启动：

veridex-mcp --version
python -m veridex_mcp --version     # equivalente, más portable en Windows

**Windows：**如果宿主使用指定的解释器启动服务，请使用 python -m veridex_mcp，并提供虚拟环境中 Python 的完整路径。这是确保启动正确进程的 最可靠方式。

环境变量

变量	默认值	用途
VERIDEX_API_URL	https://api.veridexia.es	指向本地后端或自行部署的服务
VERIDEX_API_KEY	(未定义)	为未来的高级版预留。不需要：付费端点不要求凭据，付款本身就是凭据
VERIDEX_TIMEOUT_SECONDS	30	每次 HTTP 请求的超时时间

---

配置宿主

Claude Desktop

编辑配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "veridex": {
      "command": "python",
      "args": ["-m", "veridex_mcp"],
      "env": {
        "VERIDEX_API_URL": "https://api.veridexia.es",
        "VERIDEX_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

如果想使用已安装的可执行文件，而不是模块：

{
  "mcpServers": {
    "veridex": {
      "command": "veridex-mcp",
      "args": [],
      "env": { "VERIDEX_TIMEOUT_SECONDS": "30" }
    }
  }
}

完全退出 Claude Desktop（包括托盘图标），然后重新打开。MCP 服务会在启动时运行；工具图标会显示在文本框旁边。软件包根目录中的 claude_desktop_config.json 文件提供了可直接复制的示例。

Cursor

全局配置位于 ~/.cursor/mcp.json，也可以按项目配置在 .cursor/mcp.json 中：

{
  "mcpServers": {
    "veridex": {
      "command": "python",
      "args": ["-m", "veridex_mcp"]
    }
  }
}

VS Code

VS Code 1.102+ 使用 .vscode/mcp.json（键名是 servers，不是 mcpServers）：

{
  "servers": {
    "veridex": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "veridex_mcp"]
    }
  }
}

你也可以从命令面板中通过 MCP: Add Server 运行它。若想在没有 Agent 参与的情况下查看工具，可以使用 veridex-mcp --transport streamable-http 和 MCP Inspector 进行检查。

---

x402 支付流程详解

x402 是一种基于 HTTP 的支付协议：无需 API 密钥，而是按请求付费。首次调用付费资源时，会返回 HTTP 402 Payment Required，并附带一个挑战，准确说明费用、收款方和资产。使用钱包完成该挑战后，在 X-PAYMENT 请求头中携带结果重新发送请求，资源便会返回内容。

使用此 MCP 服务时，流程分为四个步骤：

1. Agent 查询价格（免费）

调用 get_veridex_info，该工具会读取 https://api.veridexia.es/.well-known/x402。返回内容如下：

{
  "network": "base",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "asset_symbol": "USDC",
  "asset_decimals": 6,
  "pay_to": "0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3",
  "price": "0.20 USDC"
}

2. Agent 不带支付信息调用 verify_company_by_cif

API 返回 402：

POST /v1/verify HTTP/1.1
Host: api.veridexia.es
Content-Type: application/json

{"cif": "A58818501"}

HTTP/1.1 402 Payment Required
X-PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MSwiYWNjZXB0cyI6W3…   ← reto en base64
Content-Type: application/json

{
  "error": "payment_required",
  "detail": "payment required: retry with the X-PAYMENT header",
  "price_eur_cents": 20,
  "amount_atomic": 200000,
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "base",
  "pay_to": "0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3",
    "maxAmountRequired": "200000",
    "resource": "/v1/verify",
    "description": "Verificación de empresa española por CIF",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 300
  }]
}

保留 6 位小数时，200000 相当于 0.20 USDC。

这不是错误。 这是支付流程的前半部分，服务会将其作为正常结果（ok: false）返回，并包含完整的 payment 字段，而不是抛出异常：

{
  "ok": false,
  "cif": "A58818501",
  "payment": {
    "x402_version": 1,
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "pay_to": "0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3",
    "amount_atomic": 200000,
    "price_eur_cents": 20,
    "resource": "/v1/verify",
    "max_timeout_seconds": 300,
    "accepts": [/* … */],
    "payment_header": "X-PAYMENT",
    "payment_required_header_value": "eyJ4NDAyVmVyc2lvbiI6MSwiYWNjZXB0cyI6W3…",
    "instructions": "Payment required: 200000 atomic units of 0x8335… on base to 0x2bDc… This MCP server cannot sign or send payments. Have a wallet you control build an x402 payload for this exact challenge, then call verify_company_by_cif again with the same cif and the payload in the 'x_payment' argument (sent as the X-PAYMENT header)."
  },
  "error": { "code": "payment_required", "http_status": 402, "retryable": false }
}

循环重试毫无用处：每次尝试返回的挑战都相同。因此，retryable 为 false。

3. 使用你控制的钱包完成挑战

资金在此处流转，而本服务会特意避开这一环节。钱包（你的用户所用的钱包，或你使用的 x402 提供商）会针对这一特定挑战构建并签署支付载荷——网络、资产、地址和金额都必须一致——然后将其序列化为 base64。

// Lo que la wallet produce (esquema "exact" sobre Base):
{ "x402Version": 1, "scheme": "exact", "network": "base",
  "payload": { "signature": "0x…", "authorization": { /* … */ } } }
//              ↓  base64
//   "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZSIsInBheWxvYWQiOnsi…"

4. Agent 携带支付信息重新发送请求

使用同一工具和同一 CIF，并在 x_payment 中提供 base64 载荷：

{
  "cif": "A58818501",
  "x_payment": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3Qi…",
  "idempotency_key": "verif-A58818501-2026-10-04"
}

服务会将其作为请求头发送：

POST /v1/verify HTTP/1.1
Content-Type: application/json
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3Qi…
Idempotency-Key: verif-A58818501-2026-10-04

{"cif": "A58818501"}

现在就可以了：

{ "ok": true, "company": { "name": "…", "status": "active", "…": "…" },
  "risk": { "value": 15, "band": "low", "…": "…" }, "recent_acts": [/* … */] }

idempotency_key 很有用。 如果连接在支付发送后立即中断，重用同一个键进行重试会返回原始结果，而不会重复扣款。

无需 Agent 的替代方式： 使用 curl 执行相同流程，适合调试：

# 2. 获取挑战
curl -sS -X POST https://api.veridexia.es/v1/verify \
  -H 'Content-Type: application/json' -d '{"cif":"A58818501"}'
# 4. 携带支付信息
curl -sS -X POST https://api.veridexia.es/v1/verify \
  -H 'Content-Type: application/json' \
  -H "X-PAYMENT: $X_PAYMENT" \
  -d '{"cif":"A58818501"}'

哪些情况会收费，哪些不会

情况	是否收费？
找到企业（200）	是
CIF 格式有效但没有记录（404）	不收费 — 在收费前就会处理
数据源不可用（503）	不收费 — 重试免费
CIF 格式错误（422）	不收费 — 搜索前就会拒绝
缺少支付信息或支付无效（402）	不收费（暂时）

---

示例：Claude Desktop 验证一家公司

按上述配置重启 Claude Desktop 后，实际对话如下：

你： 验证 CIF 为 A58818501 的公司，并告诉我它是否有风险。

Claude 调用工具并收到 402：

Claude： 验证费用为 0,20 USDC，使用 Base 网络，需支付至 0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3。我无法自行签名或发送付款： 此 MCP 服务没有钱包。

要完成验证，请使用你自己的钱包结算此挑战，然后将生成的 base64 载荷粘贴到这里：

{ "x402Version": 1, "accepts": [ {
    "scheme": "exact", "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x2bDc11AEB751EC845aE5fED5bbf7c73BF6D0C4E3",
    "maxAmountRequired": "200000", "resource": "/v1/verify"
} ] }

如果你愿意，可以告诉我，我会说明如何使用你的钱包完成操作。

你： 给你：eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZSIsInBheWxvYWQiOnsi…

Claude 再次调用 verify_company_by_cif，将该值传入 x_payment，收到 200 并回复：

Claude： 公司已验证。

• 名称： MOCK TECNOLOGIAS SA — 股份有限公司，马拉加
• 状态： 正常，无异常（BORME 最近一次存档：2025-08-09）
• 成立日期： 2015-10-02 · 资本： 45.000 €
• 风险： 15/100（低风险等级），高置信度，结论明确
  • status_active（+15）：公司状态正常，未发现已公布的异常
• 近期事项： 2026-08-28，第一分部 — 变更注册地址
• 来源： prometiam（实时响应，未缓存）

未发现破产公告或已记录的不利信号。

如果 CIF 不存在，Claude 不会收取任何费用，并会如实说明：

Claude： CIF A58818501 格式有效，但在 BORME 和所有已配置的数据源中都未找到记录。未收取任何费用。你想让我检查一下 CIF 是否拼写正确吗？

---

错误目录

所有失败都会以包含 ok: false 和类型化 error 的普通结果返回——绝不会作为异常返回，这样 Agent 就能读取 error.code、做出判断并采取行动，而不会被打断当前轮次。

error.code	HTTP	是否可重试？	含义
payment_required	402	否（原样重试）	缺少付款。包含完整挑战的 payment。不更改付款信息直接重试无效
not_found	404	否	CIF 有效，但没有记录。未收取费用
source_unavailable	503	是	数据源发生故障。未收取费用
invalid_request	422	否	CIF 格式错误（一个字母、7 位数字和一个校验字符，例如 A46103834）
authentication_error	401 / 403	否	VERIDEX_API_KEY 已被拒绝。付款端点不需要密钥：最快的办法是移除密钥
rate_limited	429	是，等待后重试	当前调用方的配额已用尽
transport_error	(无)	是	无法连接 API（DNS、TLS、超时）。http_status 为 null
upstream_error	任意	5xx 时可重试	此客户端未处理的响应；原始代码保存在 error.details.api_code 中
malformed_response	200	否	200 响应不符合约定。包含 error.details.raw_response

状态始终包含 guidance：一条用祈使句写成的指引，明确说明下一步操作，便于模型遵循。

---

开发

cd mcp-server
python -m venv .venv
.venv/Scripts/activate          # Windows;  source .venv/bin/activate en Unix
pip install -e ".[dev]"

pytest                          # 101 tests, sin red: todo va por httpx.MockTransport
pytest -v tests/test_server.py

结构：

mcp-server/
├── pyproject.toml
├── README.md
├── LICENSE
├── claude_desktop_config.json
├── src/veridex_mcp/
│   ├── __init__.py      versión del paquete
│   ├── __main__.py      python -m veridex_mcp
│   ├── main.py          argparse, logging a stderr, arranque
│   ├── config.py        Settings desde el entorno
│   ├── models.py        los tipos de cada resultado (→ outputSchema)
│   ├── errors.py        jerarquía de errores tipados
│   ├── client.py        transporte HTTP + decodificación del reto x402
│   └── server.py        las tres herramientas MCP
└── tests/
    ├── conftest.py      API mockeada con payloads reales
    ├── test_client.py   un test por cada respuesta posible de la API
    ├── test_server.py   mapeo de errores + protocolo MCP real
    └── test_main.py     arranque, transporte y la regla de stderr

所有日志都写入 stderr。 对 stdio 传输而言，stdout 就是 JSON-RPC 通道： 一次 print() 就会破坏消息帧，导致主机报告解析错误，却不指出真正原因。这是 MCP 服务“连接成功但什么也不做”最常见的原因，因此 main.configure_logging() 明确配置日志，而不是交由 basicConfig() 处理。

发布到 PyPI

pyproject.toml 已准备就绪（名称 veridex-mcp，MIT 许可证，license-files）：

python -m build
twine check dist/*
twine upload dist/*

---

许可证

MIT。完整文本随软件包一同提供，位于文件 LICENSE 中。

VERIDEX · https://api.veridexia.es · 发现清单： https://api.veridexia.es/.well-known/x402