DataCore A2A

DataCore A2A — MCP サーバー

英語 · ベトナム語

MCP クライアント（Claude Code、Claude Desktop、VS Code、Cursor…）が DataCore の データスキルをネイティブなツールとして使えるようにします。ベトナムの住所の正規化、住所の検証、 企業の検索、埋め込みの生成ができます。

MCP client (stdio) ──► datacore-mcp ──HTTPS──► DataCore gateway

依存関係はなく、Python 3.9 以降に対応しています。

クイックスタート

このサーバーはサービスではなく、クライアントです。呼び出しに必要な DataCore エンドポイントと 認証情報が必要です。どちらかが不足している場合、起動後に不足している変数を表示して終了します。

まず、datacore.vn のアカウントが必要です。

1. インストール

pip install datacore-a2a-mcp

まだリリースされていない時点で GitHub からインストールした場合、--upgrade では PyPI ビルドに 更新されません。先にアンインストールしてから、再度インストールしてください。

2. セッショントークンを取得する

datacore.vn にサインインし、gateway.datacore.vn への任意の呼び出しから token リクエストヘッダーをコピーします（DevTools → Network）。64 桁の 16 進数です。

curl に相当する方法はありません。POST /auth/login はパスワードを RSA で復号しますが、公開鍵を 公開するエンドポイントがないため、ログインを完了できるのは Web アプリだけです。認証情報ページができれば、 この手順は不要になります。

同じログインで取得できる jwt は無視してください。ゲートウェイはクライアントから渡された Authorization を 409 で拒否します。受け付けられるヘッダーは token です。

3. 認証情報を作成する

curl -s -X POST https://gateway.datacore.vn/mcp/credentials \
  -H "token: <64-character token>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"claude-code"}' | jq .

認証情報とともに、api_key、key_prefix、allowed_skills、spend_cap_vnd、 quota_period が 201 で返されます。

api_key はすぐにコピーしてください。返されるのは一度だけです。保存されるのはハッシュのみのため、 読み返す方法はありません。紛失した場合は、新しいものを作成してください。

ここで 409 が返された場合、すでに有効な認証情報を上限の 3 件まで保有しています。先に 1 件を 失効させてください（ クォータと制限を参照）。

4. クライアントに設定する

以下の 設定 を参照してください。

手順 2～3 を実行する Web UI はまだありません。現時点では curl を使います。管理ページができた後も、 これらのコマンドは引き続き使えます。

クォータと制限

無料プラン	認証情報ごとに月額 500,000 VND の利用額
1 回あたりの料金	デフォルトで 500 VND、約 1,000 回の呼び出し
リセット	毎月 1 日、Asia/Ho_Chi_Minh
認証情報	アカウントあたり有効なものは最大 3 件
認証情報の有効期間	90 日
委任の発行	認証情報ごとに 1 分あたり最大 10 回の交換

上限はアカウント単位ではなく、認証情報ごとに適用されます。認証情報が 3 件あれば、アカウントには それぞれ個別の上限が 3 つ設定されます。サービスは呼び出し回数ではなく VND で利用額を計測するため、 後からスキルごとに料金を設定しても、保存済みの上限を書き換える必要がありません。

認証情報はマシンや IP に紐付けられていないため、同じキーを別のコンピューターでも使用できます。 ただし、クォータは共有され、失効させると両方で使えなくなります。

認証情報の利用額を確認し、失効させるには、次のようにします。

curl -s https://gateway.datacore.vn/mcp/credentials/<id>/usage -H "token: <token>" | jq .
curl -s https://gateway.datacore.vn/mcp/credentials -H "token: <token>" | jq .
curl -X DELETE https://gateway.datacore.vn/mcp/credentials/<id> -H "token: <token>"

/usage は spent_vnd、spend_cap_vnd、quota_period、resets_at を報告します。 失効時は 204 が返され、自分のものではない ID の場合は 404 が返されます。この 2 つのケースは、 意図的に区別できないようになっています。

設定

変数	必須	意味
DATACORE_A2A_URL	はい	DataCore ゲートウェイのベース URL — 自分専用のエンドポイントを案内されていない限り、https://gateway.datacore.vn
DATACORE_API_KEY	はい¹	長期間有効な認証情報で、dck_<prefix>_<secret> 形式です。サーバーはこれを短期間有効な委任トークンと交換し、トークンを自動更新します
DATACORE_MANDATE	はい¹	手動で発行された AP2 委任トークンです。以前の方法で設定した呼び出し元のみが対象です — 以下を参照してください
DATACORE_SKILLS	いいえ	ツール一覧を絞り込むための、カンマ区切りのスキル ID。エンドポイントから返されるすべてを含める場合は * を指定します。空の場合はデフォルトの 4 つが使われます
DATACORE_TIMEOUT	いいえ	リクエストごとのタイムアウト（秒）。デフォルトは 30 です

¹ いずれか一方が必須です。両方が設定されている場合は、DATACORE_MANDATE が優先されます。

DataCore から案内された URL を使用してください。別のエンドポイントでは認証情報が認識されず、401 が返されます。

DATACORE_API_KEY を使う理由

委任トークンの有効期間は 15 分です。DATACORE_API_KEY を使うと、現在のトークンの有効期限が切れる 1 分前にサーバーが新しいトークンを要求するため、トークンの期限切れを理由に設定ファイルを書き換える必要はありません。委任トークンはプロセスメモリ内に保持され、どこにも書き込まれません。それでも呼び出しに対して 401 が返された場合、サーバーは強制的にトークンを 1 回更新し、失敗を報告する前にちょうど 1 回だけ再試行します。

DATACORE_MANDATE も引き続き使えますが、更新は行われません。これは、認証情報が導入される前に設定したユーザー向けです。有効期限が切れたら手動で置き換え、MCP サーバーを再起動してください。

Claude Code

claude mcp add datacore-a2a -s user \
  -e DATACORE_A2A_URL=https://gateway.datacore.vn \
  -e DATACORE_API_KEY=<YOUR_API_KEY> \
  -- datacore-mcp

<YOUR_API_KEY> を、手順 3 の api_key に置き換えてください。形式は dck_<8 hex chars>_<secret> です。

-s user を指定すると、すべてのプロジェクトに登録されます。プロジェクト単位の .mcp.json よりこちらをおすすめします。このファイルはコミットされがちで、API キーは 90 日間有効なベアラー認証情報だからです。

Claude Desktop

以下のブロックを設定にマージしてください。ファイルを置き換えないでください。このファイルにはアプリの設定が保存されています。

OS	設定ファイルのパス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "datacore-a2a": {
      "command": "<PATH_TO_DATACORE_MCP>",
      "env": {
        "DATACORE_A2A_URL": "https://gateway.datacore.vn",
        "DATACORE_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

2 つの <...> の値はどちらも自分で入力する必要があります。JSON にはコメントを記述できないため、ファイル内に入力内容を示すものはありません。

プレースホルダー	入手先
<PATH_TO_DATACORE_MCP>	which datacore-mcp（macOS/Linux）または where datacore-mcp（Windows）。/home/you/.local/bin/datacore-mcp や C:\Users\you\AppData\Roaming\Python\Scripts\datacore-mcp.exe のようなパスです
<YOUR_API_KEY>	手順 3 の api_key。形式は dck_<8 hex chars>_<secret> です

絶対パスである必要があります。デスクトップアプリはシェルの PATH を引き継がないため、コマンド名だけでは通常起動に失敗します。python -m datacore_mcp.server も使えます。その後、アプリを完全に終了してください。ウィンドウを閉じるだけでは不十分です。

ログは stderr に出力され、アプリによって設定ファイルと同じ場所にある logs/ ディレクトリに保存されます。

ツール

ツールの一覧はここにハードコードされているのではなく、エンドポイントから生成されます。そのため、DataCore がスキルを追加した場合は、サーバーを再起動するだけで新しいツールを確認できます。

デフォルトでは、実際のバックエンドに接続された次の5つのスキルが公開されます。

ツール	スキル ID	機能
address_normalize	address.normalize	ベトナムの住所を省／県／坊に正規化します
address_validate	address.validate	住所を行政データと照合します
company_search	company.search	会社名または税コードで企業を検索します
company_graph	company.graph	企業の関係性（代表者、省、業種、その他グラフに含まれる情報）を返します
company_embeddings	company.embeddings	テキストの埋め込みベクトルを生成します

すべてのツールが受け取る必須引数は、任意のテキスト文字列である text のみです。これ以外のプロパティは受け付けません。すべてのツールは読み取り専用（readOnlyHint: true）です。書き込み、削除、作成は行われず、同じ入力には同じ結果が返されます。

DataCore のほかの2つのスキル（company.financial-sankey、company.news）は、現在モック／決定論的なデータを返すため、意図的に公開されていません。DATACORE_SKILLS="*" を設定するとツールとして一覧に表示されますが、フリーティアの認証情報では呼び出せません。許可リストに含まれるのは上記の5つのスキルのみなので、すべての呼び出しが 403 を返します。認証情報の作成時に追加のスキルをリクエストしても、エラーにはなりません。リクエストは通知なく5つのスキルに絞り込まれます。

company.graph は以前、このリストに含まれていませんでした。現在は実際の関係性を読み取るため、このリリースより前に作成された認証情報には含まれていません。許可されるスキルは認証情報の発行時に各認証情報へ書き込まれます。利用するには、新しい認証情報を作成してください。

例

3つの異なるツールを呼び出すプロンプトの例です。

1. 住所を正規化する — 「この住所を省／県／坊に正規化してください： So 1 Ly Thai To, Hoan Kiem, Ha Noi」
2. 企業を検索する — 「税コード 0100109106 の企業を探し、現在も営業しているか教えてください」
3. 埋め込みを生成する — 「この業種の説明文の埋め込みを生成し、ベクトルの次元数を教えてください：電子機器の卸売」

セキュリティモデル

このサーバーは、DataCore が検証できるように、X-AP2-Mandate ヘッダーでマンデートをそのまま渡し、独自の認可ヘッダーは宣言しません。クライアントが自分自身を認可する理由はありません。受け取ったものを転送するだけで、許可または拒否の判断はすべて DataCore 側に委ねられます。

API キーはマンデートとの交換時に X-Datacore-Credential で送信され、Authorization では送信されません。DataCore のゲートウェイは Authorization を自身のために確保しています。呼び出し元を認証した後、このヘッダーに署名を付与して挿入するため、これを含むリクエストはすべて 409 と空のレスポンスボディで拒否されます。手動で /mandate/issue を呼び出し、メッセージのない 409 が返ってくる場合は、これが理由です。

API キーはベアラー認証情報です。これを持つ人は誰でも、マンデートと交換し、上限に達するまで許可されたスキルを呼び出せます。パスワードと同じように扱ってください。値を入力した .mcp.json をコミットしないでください。また、クライアントが対応している場合は、キーを直接記述せず、シークレットマネージャーから読み込んでください。漏えいした場合は、DELETE /mcp/credentials/<id> でただちに失効させてください（クォータと制限を参照）。すでに発行されたマンデートは、残りの15分間は引き続き有効です。即時失効リストはありません。

マンデートはその逆で、有効期間は15分、プロセスメモリ内にのみ保存されます。ディスクには書き込まれず、ログにも記録されません。確認する必要もありません。

発行は認証情報ごとに1分あたり10回までに制限されているため、このエンドポイントを使ってキー空間を総当たりすることはできません。不明なキー、失効済みのキー、期限切れのキー、誤ったシークレットなど、どの拒否理由でも同じ 401 メッセージが返されます。

このパッケージは、トークンを一部であってもログに記録せず、送信した text もログに記録しません。これは、マシン上で実行されるプロセスについての保証です。サービス側については別の話であり、PRIVACY.mdに、保存される情報が明記されています。

トラブルシューティング

ログはstderrに出力され、[datacore-mcp] が先頭に付加されます。stdout は JSON-RPC チャネルです。

症状	よくある原因
すぐに終了し、MISSING required environment variable と表示される	DATACORE_A2A_URL が設定されていません
すぐに終了し、MISSING authentication と表示される	DATACORE_API_KEY も DATACORE_MANDATE も設定されていません
DATACORE_API_KEY が無視されているように見える	認証情報が導入される前の 0.1.0 を使用しており、DATACORE_MANDATE のみが読み込まれています。アップグレードしてください：pip install -U datacore-a2a-mcp
すべての操作で 401 が返る	認証情報が失効しているか、90日を過ぎているか、DATACORE_A2A_URL が発行元のエンドポイントではありません。DATACORE_MANDATE の場合：マンデートの期限が切れており、更新されません。有効なキーを探るためにエンドポイントが使われないよう、意図的にすべて同じメッセージが返されます。原因を見分けるには、GET /mcp/credentials を呼び出して、対象の認証情報がまだ ACTIVE かどうかを確認してください
手動で /mandate/issue を呼び出すと 409 が返る	キーを Authorization に指定しています。X-Datacore-Credential に指定してください。このパッケージは正しく処理します。手動で呼び出した場合にのみ発生します
認証情報の作成時に 409 が返る	有効な認証情報をすでに3つ保持しています。先に1つ失効させてください
429	1つの認証情報に対して、1分間に10回を超えるマンデート交換が行われています。このパッケージは1時間に約4回更新するため、これは何かがループしていることを意味します
402	今月のその認証情報の上限に達しています。毎月1日にリセットされます
403	スキルが認証情報の許可リストに含まれていません。無料プランで利用できるのは上記の4つのスキルのみで、その対象を拡大することはできません
400	リクエストの形式が正しくないか、スキル ID がエンドポイントに登録されていません
404	該当するルートがありません。DATACORE_A2A_URL を確認してください
502 / 503	そのスキルのバックエンドが応答していません
ツールがまったく表示されない	DATACORE_SKILLS によってすべてがフィルターされたか、エンドポイントにスキルが登録されていません

セキュリティ上の問題の報告

[email protected]。セキュリティ上のバグについて、公開の Issue を作成しないでください。

認証情報が漏えいしたと思われる場合は、今すぐ報告してください — 有効期限が切れるまで待たないでください。サービス側で対応できるよう、把握する必要があります。

プライバシー

PRIVACY.mdを参照してください。 要約すると、このパッケージはお使いのマシン上で実行され、何も保存せず、お客様が設定した DataCore エンドポイント以外には何も送信せず、委任トークンをログに記録することもありません。

ライセンス

MIT — LICENSEを参照してください。