Veriko

Veriko MCP

この MCP サーバーは Veriko を ChatGPT、Cursor などの MCP クライアントに接続します。たとえば、Banxico の CEP で支払いを確認したり、前回の検証結果を調べたり、証明書をダウンロードしたりするようアシスタントに依頼できます。

M2M の公開操作 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 はプランのクォータを消費し、リクエストが受け付けられると差し引かれます。エージェントのループによって月間クォータが数分で使い切られる可能性があるため、そのことは各ツールの説明にも記載されています。その他のカタログは、検証を消費せずに照会、エクスポート、ダウンロードを行います。

プロファイル

VERIKO_MCP_PROFILE には core、all、1 つのファミリー、またはカンマ区切りの複数ファミリーを指定できます。

プロファイル	公開されるツール
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 レスポンスのバイト数を測定しています。トークン数は 1 トークンあたり 3.6 バイトとして見積もった値であり、実際にトークン化したものではありません。プロファイル同士を比較するための目安です。

プロファイル	ツール数	tools/list のバイト数	推定トークン数
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 で、必要に応じてファミリー単位で拡張します。

アーキテクチャ

• API への唯一のトランスポート層として、公式 JavaScript SDK を使用します。 コードでは @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。