VERIDEX

veridex-mcp

VERIDEX 向けの MCP（Model Context Protocol）サーバーです。 BORMEに基づいてスペイン企業をCIFで検証し、説明可能なリスクスコアを提示します。さらに、x402の支払いサイクルを段階的に処理します。

設定すると、あらゆるエージェント（Claude Desktop、Cursor、VS Code、Claude Code…）が、HTTPを1行も書かずに検証を見つけて利用できます。

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クライアントです。3つのツール、明示的な型、型付けされたエラーを備えています。さらに、x402の支払い要求をデコードするため、エージェントは正確な金額、ネットワーク、アセット、送金先アドレスを把握できます。

できないこと： ウォレットではありません。このサーバーは署名も、鍵の保管も、トランザクションの送信もしません。ユーザーに代わって支払うことはできません。これは意図的な設計です。ユーザーに代わって資金を移動できるMCPサーバーは、所有者のいないウォレットになってしまいます。このサーバーが行うのは、完全かつ正確な支払い要求をエージェントに渡し、ユーザーが管理するウォレットで決済できるようにすることです。

APIを変更することもありません。api.veridexia.es の純粋な利用者です。

---

3つのツール

ツール	引数	費用	返される内容
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の状態、稼働時間、今日のリクエスト数とユニークエージェント数

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 は最も誤解されやすいフィールドです。value: 0 の assurance: "none" は、この企業について何もわからないという意味であり、この企業は安全であるという意味ではありません。このような場合、サーバーは 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へのフルパスを指定して python -m veridex_mcp を使用してください。これが正しいプロセスを起動する最も確実な方法です。

環境変数

変数	デフォルト	用途
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 を使用します（キーは mcpServers ではなく servers です）。

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

コマンドパレットから MCP: Add Server を選んで実行することもできます。エージェントを介さずにツールを確認したい場合は、veridex-mcp --transport streamable-http と MCP Inspector を使って確認してください。

---

x402 決済フローの手順

x402 は HTTP 上の決済プロトコルです。API キーの代わりに、リクエストごとに支払います。 決済対象のリソースへの最初の呼び出しでは、金額、送金先、資産を正確に示す「チャレンジ」とともに、HTTP 402 Payment Required が返されます。ウォレットでそのチャレンジを決済し、結果を X-PAYMENT ヘッダーに含めてリクエストを再送すると、リソースからコンテンツが返されます。

この MCP サーバーでのフローは4 つの手順です。

1. エージェントが価格を問い合わせる（無料）

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. エージェントが支払いなしで 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 です。

これはエラーではありません。 決済サイクルの前半にあたり、サーバーは例外ではなく、完全な payment フィールドを含む通常の結果（ok: false）として返します。

{
  "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. エージェントが支払いを添えて呼び出しを再送する

同じツール、同じ CIF を使い、base64 ペイロードを x_payment に指定します。

{
  "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 を指定する価値はあります。 支払いを送信した直後に接続が切れた場合、同じキーを再利用すれば、二重に請求されることなく、元の結果が再試行時に返されます。

エージェントを介さない方法： 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 を含む通常の結果として返されます。例外として返されることはありません。そのため、エージェントはターンを中断されることなく error.code を読み取り、判断して動作できます。

error.code	HTTP	再試行可能？	意味
payment_required	402	いいえ（そのままでは）	支払いがありません。完全なチャレンジを含む payment が返されます。支払いを変更せずに再試行しても意味がありません
not_found	404	いいえ	CIF は有効ですが、登録がありません。請求は行われていません
source_unavailable	503	はい	データソースで障害が発生しました。請求は行われていません
invalid_request	422	いいえ	CIF の形式が正しくありません（英字 1 文字、数字 7 桁、チェック文字 1 文字。例：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() を 1 回使うだけでフレーミングが壊れ、ホストには実際の原因が示されない解析エラーが報告されます。これは 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