Proof Holdings

@proof-holdings/mcp-server

proof.holdings API 用の MCP（Model Context Protocol）サーバーです。AI エージェントが検証を作成したり、証明を検証したり、アセットを管理したりするための 167 個のツールを提供します。

接続方法は 2 つあります

ホステッド — インストール不要です。 同じツールが HTTP 経由で https://api.proof.holdings/mcp から提供されます。HTTP トランスポートに対応した MCP クライアントやエージェントフレームワークであれば接続できます。設定で URL をリモート MCP サーバーとして追加してください（設定キーはクライアントによって異なります）。 ツールが初めてアカウントを必要としたときに、ブラウザーで認証が行われます。設定例：

{ "mcpServers": { "proof": { "type": "http", "url": "https://api.proof.holdings/mcp" } } }

⚠️ 1.1.0 より前のバージョンには委任ツールとキー不要のパブリックモードがなく、この README に記載されているものより古く、機能の少ないインターフェースを提供します。クライアントのバージョンが 1.0.0 に固定されている場合は、アップグレードするか、上記のホステッドサーバーを使用してください。GET /api/v1/mcp/connect は常に最新の手順を提供します。

ローカル — このパッケージです。 stdio サーバーとしてインストールして実行します：

npm install -g @proof-holdings/mcp-server

または、npx で直接実行します（インストール不要です）：

npx @proof-holdings/mcp-server

設定

変数	必須	デフォルト	説明
PROOF_API_KEY	いいえ	—	API キー（pk_live_... または pk_test_...）。指定しなくてもサーバーはパブリックモードで起動します。キー不要のツール（アカウントの初期設定、ログイン、証明および委任の検証）は動作し、それ以外のすべてのツールは api_key_required を返します。
PROOF_BASE_URL	いいえ	https://api.proof.holdings	API のベース URL

proof.holdings ダッシュボードから API キーを取得するか、サーバーに login で取得させることもできます（以下を参照）。

ターミナルからサインインする

npx @proof-holdings/mcp-server login

1. ログイン方法（Telegram、WhatsApp、SMS、メール）を選びます（--channel で指定するか、質問に回答します）。ターミナルにリンクと、スマートフォンでスキャンする QR コードが表示されます。SMS の場合は送信するテキストと番号が表示され、メールの場合はメールに記載されたコードの入力を求められます。
2. API キーの作成には、もう 1 回確認が必要です。できれば別のチャネルで確認してください。確認もターミナルで行います。
3. 新しいキーは ~/.proof-holdings/credentials に保存されます（自分だけが読み取り可能）。PROOF_BASE_URL で指定された API 用のキーとして保存されます。サーバーは次回の起動時からこのキーを使用するため、MCP クライアントのサーバーを再起動してください。
4. ターミナルで使用したサインインセッションは、その後サインアウトされます。サインアウトに失敗した場合は login がその旨を伝えます。ダッシュボードの Settings → Security → Signed-in devices からサインアウトしてください。

PROOF_API_KEY が設定されている場合、常に保存済みのキーより優先されます。また、ある API（たとえばステージング環境）用に保存されたキーが別の API に送信されることはありません。その場合、クライアント設定から env を省略してください：

{ "mcpServers": { "proof-holdings": { "command": "npx", "args": ["-y", "@proof-holdings/mcp-server"] } } }

コマンド	動作
login	サインインし、確認を行い、キーを作成して保存します。--test はテスト用キー（pk_test_）を作成します。--scopes a,b はキーの権限を制限します（デフォルト：フルアクセス）。--email [email protected] はメールでログインします。
status	サーバーが起動時に使用するキーと、その取得元を表示します。ネットワーク通信は行いません。
logout	このコンピューターから、この API 用に保存されたキーを削除します。

キーに有効期限はありません。再度ログインすると保存済みのキーは置き換えられますが、古いキーは失効しません。また、logout はローカルのキー情報を削除するだけです。使わなくなったキーは、ダッシュボード（API keys）または revoke_api_key ツールで失効させてください。login には対話型ターミナルと https:// の API が必要です（http は localhost の場合に限り使用できます）。

クライアントのセットアップ

以下をMCPクライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "proof-holdings": {
      "command": "npx",
      "args": ["-y", "@proof-holdings/mcp-server"],
      "env": {
        "PROOF_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

クライアント別の設定ファイルの場所：

クライアント	設定ファイル
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Cursor	プロジェクトルートの .cursor/mcp.json
Claude Code	claude mcp add proof-holdings -- npx -y @proof-holdings/mcp-server を実行します
Windsurf	~/.codeium/windsurf/mcp_config.json

グローバルインストール後も、スコープ付きの npx -y @proof-holdings/mcp-server コマンドを使用してください。コマンド名だけを指定すると、PATH または npm レジストリ内で npx によって検索されるため、他者のパッケージが実行される可能性があります。

ツール（167個）

グループごとの合計は正確です。以下の表には、すべてのツールではなく、特によく使うと思われるツールを掲載しています。MCPクライアント独自の tools/list が最新の完全な一覧であり、このサーバーはその一覧を返します。

検証とリクエスト（28個）

ツール	説明
create_verification	検証チャレンジを作成します
get_verification	検証状況を取得します
submit_verification_code	検証コードを送信します
trigger_verification	検証チェックを開始します
wait_for_verification	完了するまでポーリングします
create_multi_channel_verification	1つの電話番号で最大3つのチャネルを使用し、最初に完了したものを採用します
create_verification_request	複数アセットのリクエストを作成します
get_request_by_reference	参照IDでリクエストを検索します

ドメインとDNS（23個）

ツール	説明
add_domain	検証するドメインを追加します
verify_domain	チャレンジレコードを確認し、証明を発行します
connect_cloudflare	Cloudflareに接続し、レコードを自動で書き込みます
verify_domain_with_credentials	保存済みの認証情報を使って管理権限を証明します
setup_domain_email	ドメインからのメール送信を設定します

アカウント、設定、請求（37個）

ツール	説明
get_platform_summary	アカウントの概要を1回の呼び出しで取得します
get_usage	対象期間のクォータと使用状況を取得します
search	アカウント全体を検索します
create_account	新しいアカウントを初期設定します（キーは不要です）
create_api_key	スコープ付きAPIキーを作成します
list_assets	検証済みアセットとその証明ハンドルを一覧表示します

HITLの承認と同意（22個）

ツール	説明
create_hitl	人による承認の設定を作成します
create_confirmation	人に承認リクエストを送信します
wait_for_confirmation	人が承認または拒否するまでポーリングします
create_authorization	連絡を受けることへの同意を人に求めます
revoke_authorization	同意を撤回します

サークルとProof of Me（15個）

ツール	説明
create_circle	信頼できる連絡先のサークルを作成します
add_circle_member	連絡先を追加します
invite_circle_member	1回限りの登録リンクを送信します
create_identity_challenge	複数のチャネルをまたいだ本人確認を実行します

公開プロフィール（12個）

ツール	説明
create_profile	公開プロフィールを作成します
claim_username	公開ユーザー名を取得します
update_public_proofs	プロフィールに表示する証明を選択します

テンプレートとWebhook（11個）

ツール	説明
list_templates	プロジェクトのメッセージテンプレートを一覧表示します
render_template	変数を使ってテンプレートをレンダリングします
list_webhook_deliveries	Webhookの配信履歴を一覧表示します
retry_webhook_delivery	失敗したWebhook配信を再試行します

委任と証明（10 個のツール）

ツール	説明
create_delegation	証明済みのドメインからのアーティファクトを承認します
revoke_delegation	委任を取り消します
verify_delegation	アーティファクトが、申告されたドメインによって承認されているか確認します
validate_proof	署名済みの証明トークンを検証します（鍵は不要です）
get_proof_status	公開ハンドルを使って証明のステータスを読み取ります
list_revoked_proofs	失効リストを読み取ります（鍵は不要です）

サインインとセッション（9 個のツール）

ツール	説明
start_login	サインインを開始します（鍵は不要です）
wait_for_login	サインインが完了するまでポーリングします
get_current_user	現在のセッションのユーザーを確認します
render_auth_link	ユーザーが開くサインインリンクを生成します

テストモード

テストモードの API キー（pk_test_*）を使用すると、実際の検証を作成せずに API を操作できます。テストモードのキーはダッシュボードで入手できます。

トランスポート

このパッケージには 2 種類のトランスポートが含まれています。

• stdio（デフォルト。npx -y @proof-holdings/mcp-server の実行で起動します） — サーバーは stdin/stdout を介して通信します。プロセスごとにユーザーは 1 人です。クライアントがローカルで起動する場合に使用します。
• Streamable HTTP（node dist/remote.js） — 多数のユーザーが URL を使ってネットワーク経由で接続するリモートサーバーです。インストールは不要です。接続は ANONYMOUS として開始されます。アカウントの初期設定、ログイン、証明と委任の検証といった、鍵を必要としない機能は認証情報がなくても利用できます。アカウントが必要なツールは、認可サーバーを示す WWW-Authenticate チャレンジとともに 401 を返します。標準準拠のクライアントはこのチャレンジに従ってサインインします。401 が返るのはツール呼び出しに対してであり、ANONYMOUS 接続の単独の initialize や tools/list に対してではありません。実際のクライアントで測定したところ、匿名のハンドシェイクを拒否すると、ユーザーにはログインへの案内ではなく接続タイムアウトとして受け取られます。ハンドシェイク時に拒否されるのは、次の 3 つの場合に限られます。提示されたトークンを解決できない場合（この場合、クライアントが更新するために 401 を返します）、リクエストの認証情報が指定されたセッションと一致しない場合、そして initialize とともに鍵を必要とするツール呼び出しを紛れ込ませた初回のバッチです。サインイン済みのクライアントは、付与された API キーを Authorization ヘッダーで送信します。認証情報を読み取る場所はここだけであり、クエリパラメーターから読み取ることはありません。また、接続ごとに専用のサーバーと HTTP クライアントが割り当てられるため、あるユーザーのキーやセッションが別のユーザーに渡ることはありません。/mcp は POST（すべての JSON-RPC メッセージ）と DELETE（セッションの終了）を受け付けます。それ以外のすべてのメソッドは、任意の単独 GET イベントストリームも含め、リクエストに含まれるセッションや認証情報にかかわらず、Allow: POST, DELETE とともに 405 を返します。このサーバーは通知をプッシュしないため、ストリームを利用しなくてもクライアントに不都合はありません。また、これにより Node 26 組み込みの fetch を使うクライアントも動作します。エッジへの HTTP/2 接続でストリームを開いたままにすると、次のリクエストが送信されなかったためです。PORT（デフォルトは 3100）、MCP_MAX_SESSIONS（デフォルトは 100）、MCP_SESSION_TTL_MS（デフォルトは 30 分。サーバーが受け付けた最後の POST、つまり 400 未満の応答を返した POST から計算します。作業が始まる前に拒否された POST は、拒否の原因がこちら側（本文が 4MB を超過）でもトランスポート側（本文が解析不能または空、未対応の mcp-protocol-version、2 回目の initialize）でも、TTL を延長しません。拒否されたメソッドも同様です。公式クライアントは、期限切れによるセッション一掃から自動復旧しません。SDK 1.27.1 で測定したところ（イベントストリームがまだ提供されていた時点の測定であり、それ以降は再測定していません）、次のツール呼び出しは unknown_session で失敗し、ホストがサーバーに再接続するまで復旧しません。この点を考慮して TTL を設定してください。これはメモリ上限と引き換えに再接続が必要になる仕組みであり、透過的に処理されるものではありません）； /healthz は現在のセッション数を報告します。

委任（_meta）

サーバーカード（server.json）には、名前空間付きの _meta キー holdings.proof/delegation の下に、Proof of Delegation の公開情報を含めることができます。

{
  "_meta": {
    "holdings.proof/delegation": { "token": "<delegation JWT>" }
  }
}

このトークンは、proof.holdings が発行する ES256 JWT で、次の一点のみを証明します。**principal ドメインの管理者が、記載されたスコープについて delegate アーティファクトを承認したことです。**サーバーが安全、監査済み、または推奨されているという意味ではありません。検証者は発行者の JWKS に対して署名を確認し、principal と delegate を自身で解決した事実と照合します。別のパッケージにコピーされたトークンは、delegate が本物のアーティファクトを指しているため、この照合に失敗します。詳細は委任 — API リファレンスをご覧ください。

カードが公式 MCP レジストリを通じて公開される場合、同じエントリーは _meta["io.modelcontextprotocol.registry/publisher-provided"] の下にネストされます。参照する側は、両方の場所を確認してください。

メンテナー向け：エントリーはフェイルクローズ方式の公開ツールによって書き込まれ、手動では書き込みません。pkg:npm/@proof-holdings/mcp-server 用の委任を発行した後、リポジトリのルートから実行してください。

npm run delegation:publish -- --target mcp --token <jwt>
# or mint + publish in one step (needs PROOF_API_KEY):
npm run delegation:publish -- --target mcp --mint \
  --control-proof ph_ctl_<32hex> --scope proof-verification

このツールは、principal: proof.holdings を指定してこのパッケージを正確に示していないクレームを含むトークンを拒否します（これは、--target a2a が再生成前に A2A エージェントカード自身の url に対して行うチェックと同じです）。server.json に加えて、--target mcp はウェブサイトカードのソース（web/src/lib/geo/mcp-delegation-publication.json）を書き込み、/.well-known/mcp/server-card.json と /.well-known/mcp.json を再生成するため、web/node_modules がインストールされている必要があります。どちらのターゲットでも、ソースファイルの書き込み後にカード再生成の手順が失敗した場合は、コマンドを再実行してください。トークンはすでに検証済みで、再生成は冪等です。ウェブサイトカードが参照者に届くのは、次回のウェブサイトのデプロイ後です。

他者の委任を検証する（verify_delegation）

このサーバーは委任を公開するだけでなく、検証も行います。verify_delegation ツールは、参照検証ツール（@proof-holdings/delegation-verifier）を使って別のサーバーのカードを検証します。API キーは不要です。検証は公開情報のみを対象に実行されます。

{
  "card": { /* the MCP server.json or A2A agent card you fetched */ },
  "delegate": { "type": "purl", "value": "pkg:npm/postmark-mcp" },
  "expected_principal": "postmarkapp.com"
}

どちらのピン留めも必須であり、それぞれ異なる攻撃を防ぎます。

• delegate は、あなたが解決したアーティファクト ID、つまりこれからインストールするパッケージや呼び出すエンドポイントでなければなりません。検証対象のカードからコピーしてはいけません。公開されたトークンはベアラーアーティファクトであるため、同じカード内のフィールドと照合すると、別の場所から貼り付けられたトークンを承認してしまいます。
• expected_principal は、そのアーティファクトの背後にあると期待するドメインです。発行者はアーティファクトを何にも結び付けないため、どのドメイン所有者でも、他者のパッケージを指定した本物の署名付き委任を発行できます。このピンがなければ、判定が意味するのは「あるドメインがこれを主張している」ということだけです。

すでに信頼しているすべてのものを再確認する（verify_delegations）

verify_delegation は、「リクエストしたので、今この1件は有効か」を確認します。エージェントがすでに35件のアーティファクトを解決して検証している場合、1回の呼び出しで1件ずつ再検証する方法では対応しきれません。verify_delegations なら、API キーなしで最大50件を1回の呼び出しでまとめて確認できます。

{
  "items": [
    { "card": { /* ... */ }, "delegate": { "type": "purl", "value": "pkg:npm/postmark-mcp" }, "expected_principal": "postmarkapp.com" },
    { "token": "<jwt>", "delegate": { "type": "url", "value": "https://example.com/mcp" }, "expected_principal": "example.com" }
  ]
}

各項目には、verify_delegation が要求するものとまったく同じ形式（card と token のどちらか一方、delegate、expected_principal、任意の required_scopes）を指定し、それぞれ独立して検証します。項目間で状態は共有されず、何も永続化されません。また、ある項目の失敗が別の項目の結果に影響することもありません。失効は必ず確認されます（このツールに check_status: false はありません。一括再確認の目的は、変更点を把握することだからです）。

このツールが意図的に行わないことが2つあります。

• インストール済みのものを検出しません。 各アーティファクトの card または token を、あらかじめ手元に用意しておく必要があります。DNS ポインターの解決は行わず、呼び出し元から渡された URL も取得しません。これは verify_delegation がすでに定めている信頼境界であり、意図的に狭く保たれています（メインリポジトリの src/services/delegationPointer/resolve.ts に記載された未対応事項を参照してください。このツールはその範囲外です）。
• 継続的には実行されません。 各呼び出しは、その時点での単発の確認です。実行間隔、スケジューラー、プッシュ通知はありません。最新の結果が必要なときは、いつでも再度呼び出してください。

results[] の各結果には、4種類のいずれかの outcome が含まれます。

結果	意味
confirmed_valid	委任が検証されました。verify_delegation の verified: true と同じ意味です。
confirmed_invalid	明確な否定判定です。失効、停止、期限切れ、プリンシパルまたはデリゲートの不一致、付与されていないスコープ、あるいは不正な形式または信頼できない、もしくは署名に問題のあるトークンが該当します。
no_claim_found	アーティファクトに委任情報が一切公開されていません。これは不在を示すものであり、非難を意味するものではありません。
unconfirmed	発行者に接続できなかった、または現時点で確信を持てる回答を得られなかった状態です（たとえば、JWKS またはステータスエンドポイントに接続できない場合）。これを不正な判定として扱ってはいけません。「失効」ではなく「後でもう一度確認する」という意味です。

各結果には checked_at も含まれます。これは、その項目の確認が完了した時点の ISO タイムスタンプであり、呼び出し全体で共通のタイムスタンプではありません。これにより、「ローカルで確認済み」を、「その時点でこちらに接続して確認済み」であるかのように、確認方法を明示せずに示すことを防ぎます。

⚠️ リリース順序（メンテナー向け）

package.json では @proof-holdings/delegation-verifier が実行時依存関係として宣言されているため、このパッケージをアップロードする前に、指定されたバージョン範囲がレジストリで解決可能になっている必要があります。

範囲を変更するリリースでは、毎回 @proof-holdings/delegation-verifier を @proof-holdings/mcp-server より先に公開してください。 すべてのドキュメントに記載されたクライアントは npx 経由でこのサーバーを起動するため、依存関係をレジストリで解決できないままリリースすると、verifier が公開されるまで、すべてのユーザーで npx @proof-holdings/mcp-server が E404 で失敗します。target: all を指定して .github/workflows/publish-packages.yml を実行すると、ステップの順序によって公開順が保証されます。ターミナルから手動で公開する場合、順序を保証するものは docs/runbooks/npm-release.md しかありません。

verifier とサーバーを同時に開発するだけなら、公開は不要です。代わりに、兄弟パッケージをリンクしてください。

npm run verifier:link   # cd mcp && npm install ../packages/delegation-verifier --no-save

このリポジトリでは、Vitest のエイリアスを使って node_modules ではなく verifier のソースを参照するため、テストスイートでリンクは不要です。そのため、新しくクローンした状態でもテストは成功し、ビルドなしで未コミットの verifier の変更を取り込めます。このエイリアスは、兄弟パッケージの verifier が存在することを条件とします。このパッケージだけを含む公開ミラーでは、テストスイートは npm ci でインストールされた verifier を使って実行されます。

要件

• Node.js >= 18.0.0
• キーが必要なツールを使うには proof.holdings の API キーが必要です。サーバーはキー不要のツールであれば、キーなしで起動して応答します。上記の「設定」を参照してください。

リンク

• proof.holdings — 製品ウェブサイト
• API ドキュメント — REST API リファレンス
• ダッシュボード — アカウントと API キーを管理します

ライセンス

MIT