メインコンテンツへスキップ

​
スコープと役割の権限

コネクターはdidit:managementおよびdidit:verificationのスコープで動作します(3つ目のdidit:staffも公開されていますが、Didit社内スタッフのアカウントにのみ関係します)。両方の制限がすべての呼び出しに適用されます。トークンには承認したスコープが含まれ、その範囲内で何ができるかはコンソールでの役割によって決まります。実際のアクセス範囲は両者の共通部分となるため、didit:verificationのみを承認した場合、OWNERであっても管理系の機能は利用できません。 各ツールはバックエンドの1つの権限(read:sessions、write:workflows、delete:listsなど。ツールごとの権限はツールリファレンスに記載)に対応しています。サーバーは、トークンのイントロスペクションが返す組織の権限を用いてその権限を事前チェックします。この動作はMCP_PERMISSION_MODEで制御します。 MCPが役割を超えて権限を昇格させることはありません。あるツールで403が返された場合、それは役割にその権限がないことを意味しており、接続全体が失敗したわけではありません。

​
アプリと組織をまたぐスコープの解決

Diditの管理APIはアプリケーション単位でスコープが設定されています(/organization/{org}/application/{app}/…)。MCPはこのスコープを自動で解決します。
  • 組織とアプリが1つずつの場合 → 自動的に解決されるため、IDを渡す必要はありません。
  • 複数のアプリがある場合 → アプリ横断ツール(didit_session_search、didit_transaction_search、didit_case_search、didit_vendor_user_search、didit_vendor_business_search、didit_workflow_search、didit_analytics)は、1回の呼び出しですべてのアプリを集約し、各行にorganization_id/application_idのタグが付きます。
  • アプリ単位の一覧ツール(didit_session_list、didit_transaction_list、didit_case_list、didit_vendor_user_list、didit_vendor_business_list、didit_workflow_list)は、アプリを指定しない場合すべてのアプリを自動的に対象とするため、アプリが多数あっても単純な「セッションを一覧表示して」がそのまま機能します。1つのアプリに絞り込むには、organization_idとapplication_idを渡してください。
didit_context_getを使うと、すべての組織とアプリケーション(およびそのID)を1回の呼び出しで確認できます。各アプリケーションのmode(liveまたはsandbox)も返されるため、アプリケーション名から環境を推測しないでください。サンドボックスのアプリケーションでは、didit_session_createにsandbox_scenarioを渡して、課金されないテスト実行ができます。

​
ホスト型カタログの内容

ホスト型コネクターでは169個のツールを利用できます。このほかに17個のInvestigatorツールも一覧に表示されますが、これらは組織でInvestigatorが有効になっている場合にのみ動作します。さらに2つのツール、didit_org_top_up(Stripeチェックアウト)とdidit_org_reveal_application_api_key(生のシークレット)は、OAuthで認証されたすべての呼び出し元のtools/listから非表示になっています。アカウント設定用の5つのツール(didit_account_*)はリモートサーバーから完全に除外されており、リモートでは実行を拒否します。リモートコネクターがツールの引数として認証情報を受け取ることは決して許されないためです。ローカルのstdioサーバーではこれらすべてを利用でき、合計193個になります。 一覧に表示される各ツールには、MCPアノテーション(readOnlyHint、destructiveHint、openWorldHint、title)とoutputSchema、さらにその領域(Sessions、Workflows & Questionnaires、Transactions (AML)など)を示す_meta["anthropic/toolGroup"]ラベルが付いています。Claudeなどのクライアントは、これらのアノテーションを使ってコネクターのツールを読み取り専用、書き込み、破壊的操作のグループに分類します。

​
分岐ワークフロー

シンプルなワークフローは機能をフラットに並べたリストです。条件分岐ロジック（ステータスによる却下、抽出フィールドに基づくルーティング、一致結果によるステップの制御、Document AIリクエストの追加など）を扱う場合、MCPはDiditのノードグラフ（コンソールのビジュアルビルダーと同じ構造）を操作します。グラフは{ start_node, nodes }で構成され、各ノードはfeature、branch、status（終端）、action、webhookのいずれかです。分岐ルールは、kyc.extra_fields.professionのような抽出フィールドに対してfuzzy_match（文字列フィールド用。scoreで0〜100の類似度しきい値を指定）などの演算子をサポートします。また、DOCUMENT_AI機能ノードは書類（例: 資金証明）をリクエストします。

​
既存のワークフローを編集する (推奨)

実際のワークフローは大きな機能設定を持っています。OCRのdocuments_allowed許可リストだけで150 KB+になることがあり、さらにPOAリストや電話番号の国別リストも含まれます。そのため、グラフ全体を読み込んで再送信しないでください。代わりに、小さなオペレーションで編集します。
1

特定と確認

didit_workflow_search { workflow_id }は、すべてのアプリを横断してワークフローを見つけます。didit_workflow_get_graphは、大きな設定を要約した状態で構造を返します（オーバーフローすることはありません。生の値が必要な場合はinclude_config: trueを渡します）。didit_workflow_get_field_definitionsは、分岐に使えるフィールドと有効な演算子を一覧表示します。
2

オペレーションで編集

didit_workflow_edit_graphは、set_next、set_node、set_branches、merge_node_configといった少数の小さなオペレーションを受け取ります。MCPは完全なグラフをサーバー側で取得し、オペレーションを適用して検証し、ドラフトを自動作成して保存します。許可リストはバイト単位でそのまま保持され、リクエストを経由することはありません。検証に失敗するとapplied: falseが返されます（何も保存されません）。
3

レビューと公開

publishする（コンソールまたはdidit_workflow_publish経由）まで、レビュー可能なドラフトのままです。公開中のバージョンには一切手が加えられません。
たとえば、本人確認の後に既存のパイプラインに合流する分岐を挿入する場合、送信するのは次の内容だけです。OCRノードのnextを新しい分岐に付け替え、分岐、終端のDeclinedノード、DOCUMENT_AIステップ（そのnextは元の後続ステップを指す）を追加します。他の10個のノードとその許可リストには手が加えられません。
「本人確認の後、却下された場合は却下する。職業が『Software Engineer』にほぼ一致（80%以上）する場合は資金証明をリクエストする。その後は続行する。」 → 1つのbranchノード: kyc.status == Declined → Declinedステータスノード。kyc.extra_fields.profession fuzzy_match “Software Engineer” スコア80 → DOCUMENT_AI資金証明ノード → そして、パイプラインに戻るそれ以外のパス。
分岐には必ず明示的な「それ以外」が必要です。 キャッチオール（どの条件にも一致しない場合に進むパス）は、rulesが空の分岐でなければなりません（例: { "id": "else", "rules": [], "goto": "<liveness>" }）。分岐ノードの単なるnextは使えません。MCP（およびバックエンド）は分岐ノードのnextを自動的に「それ以外」の分岐に変換するため、「それ以外」が見えない曖昧なエッジとして分岐が表示されることはありません。
新規ワークフローをゼロから作成するには、didit_workflow_validate_graphの後にdidit_workflow_set_graph（完全なグラフ）を使用するか、didit_workflow_build_graphを使ってシンプルな機能仕様から保存せずに完全なグラフを組み立てます。シンプルなdidit_workflow_createでも、この同じノードグラフとして保存されます。MCPはfeaturesリストを、自動判定ステータスで終わる連結された機能ノードとして組み立てるため、機能が実際に実行されます（デフォルトでは公開されます。未公開のままにするにはstatus: "draft"を渡します）。完全なJSON構造については、ワークフローの作成 → 分岐とノードベースのワークフローを参照してください。

​
MCPによるNFCスキップ理由の分岐

新しいグラフの場合は、次のように依頼します。
「本人確認の後にNFCを行うドラフトワークフローを作成してください。nfc.skip_reasonがDEVICE_WITHOUT_NFCまたはDOCUMENT_WITHOUT_CHIPの場合はセッションをレビュー中にし、それ以外の場合は承認してください。明示的な『それ以外』の分岐を残し、保存前にグラフを検証してください。」
エージェントはdidit_workflow_get_field_definitions、didit_workflow_validate_graph、didit_workflow_set_graphの順に呼び出す必要があります。既存のワークフローの場合は、次のように依頼します。
「ワークフロー26d33c04…を編集してください。NFCノードの後で、既知の7つのnfc.skip_reason値のいずれかに該当する場合はレビュー中にルーティングし、既存のNFC成功パスを明示的な『それ以外』として保持してください。ドラフトとして保存し、公開はしないでください。」
エージェントはdidit_workflow_search、didit_workflow_get_graph、didit_workflow_get_field_definitions、didit_workflow_edit_graphの順に呼び出す必要があります。編集ツールは小さなオペレーションをサーバー側で適用するため、無関係なノードや大きな許可リストは保持されます。7つの値、equals/inルール、null時の動作、順序どおりに並べた完全なグラフについては、ワークフローの作成 → NFCが実行されなかった理由で分岐するを参照してください。

​
機能設定と許可リスト

機能ノードのconfigは、そのノードが受け付ける内容を制限します。didit_workflow_get_feature_config_schemaは、各機能が受け取るすべてのキーを型とデフォルト値とともに返します。また、2つのカタログツール（didit_workflow_get_id_verification_methods_catalog、didit_workflow_get_kyb_registry_catalog）は、設定が依存するサーバー側の情報を提供します。標準のOCR許可リストは、国ごと → 書類ごと → オブジェクトという構造です: { "<ISO3>": { "<CODE>": { "enabled": 1 } } }（例: { "ESP": { "P": { "enabled": 1 } } }）。MCPは検証の前により扱いやすい形式を標準形式に変換するため、この構造を手書きする必要はありません。 PROOF_OF_ADDRESSのpoa_languages_allowedも同じ考え方で、言語の配列（["es"]）またはマップ（{ "es": 1 }）を渡せます。これらの指定方法は、MCPに機能設定を渡すすべての場所に適用されます。対象はdidit_workflow_createの機能、およびset_graph / edit_graph / validate_graphのノードconfigです。

​
レスポンスの形式 (V3コントラクト)

すべてのツールは、基盤となるRESTエンドポイントのJSONをそのまま返します。知っておくべき点は2つあります。
  • 同期ツール (ワークフロー、請求、単体のverify_*、リスト管理) は最終結果をその場で返します。同じターン内で結果に基づいて処理してください。
  • セッションの作成は非同期です。didit_session_createはユーザーが手続きを完了するためのurlを返し、判定はWebhookで送信されるか、didit_session_get_decisionで取得できます。
判定のキーは常に複数形の配列で、各エントリにnode_idが含まれます (id_verifications[]、liveness_checks[]、face_matches[]、aml_screenings[]、poa_verifications[]、phone_verifications[]、email_verifications[]、database_validations[]、reviews[]、およびKYBのregistry_checks[]、document_verifications[]、key_people_checks[])。データモデルと検証ステータスを参照してください。

​
Webhookの処理

エージェントからポーリングするのではなく、Webhookで最終的な判定をバックエンドに配信させてください。
  1. エージェントがlabel、公開HTTPSのurl、webhook_version: "v3"、subscribed_events (通常は["status.updated", "data.updated"]) を指定してdidit_webhook_createを1回呼び出します。レスポンスでは署名用シークレットが伏せられており、didit_webhook_getとdidit_webhook_listでも同様です。コンソールのWebhooksからコピーし、DIDIT_WEBHOOK_SECRETとして保存してください。
  2. バックエンドは、すべての配信で正規のX-Signature-V2ヘッダーを検証します。手順はshortenFloats → sortKeys → JSON.stringify (Unicodeはエスケープしない) → HMAC-SHA256 → timingSafeEqualです。abs(now − X-Timestamp) > 300秒の場合は拒否してください。
  3. event_idで重複を排除します。5 秒以内に2xxを返し、重い処理はキューに移してください。
  4. Diditは5xx / 404の場合に最大2回再試行し (約1分後、次に約4分後)、その後は配信を破棄します。失敗した配信はコンソールのDeliveriesタブから再送できます。
エージェントが行うのは受信側の接続設定だけで、エージェント自身が待ち受けることはありません。仕様の全体はWebhookを参照してください。

​
トランスポートとエンドポイント

このエンドポイントは新旧両方のプロトコル世代に対応しています。すべてのメッセージで2026-07-28以降のプロトコルバージョンを固定するクライアントは、initializeハンドシェイクを省略してserver/discoverを呼び出せます。それより前のクライアント (Claude Code、Cursor、SDKベースのクライアント) はすべて、標準のStreamable HTTPハンドシェイクを変更なしで使用します。CORSは開放されているため、ブラウザベースのクライアント (Claude Webコネクタ、MCP Inspector) もクロスオリジンで/mcpとディスカバリードキュメントにアクセスできます。JSONボディの上限は25 MBで、15 MBのbase64ファイル入力に十分な大きさです。

​
トラブルシューティング

その組織におけるあなたの役割に、ツールが必要とする権限がありません (例: READERが書き込みを試みた場合)。必要な権限はmissing_scopeエラーに示されます。すべてのツールが失敗する場合は、再接続するかLog in with Diditをやり直してください。(MCPはBearer/OAuthのみに対応しており、x-api-keyはすべてのツールで拒否されるため、APIキーでは403は解決しません。)
破壊的なツールは、クライアントでの確認が必要です。呼び出しを承認するか、ツールの確認プロンプトが自動的に拒否されていないか確認してください。didit_session_delete、didit_session_batch_delete、didit_org_reveal_application_api_keyは、さらにツールの引数にconfirm: trueが必要です。指定しない場合、何も実行される前に呼び出しが拒否されます。
複数のアプリケーションを持っている可能性があります。*_searchツール (すべてを横断して検索します) を使うか、didit_context_getを実行して目的のorganization_id / application_idを渡してください。
一部のクライアント (Windsurf、Zed) はmcp-remoteブリッジ経由で接続します。設定にnpx -y mcp-remote@latest https://mcp.didit.me/mcpが含まれていることを確認してください。クライアントを開き直すと、OAuthハンドシェイクが再度トリガーされます。
サーバーが接続されていること (ほとんどのクライアントはステータスドットを表示します) と、Log in with Diditを完了したことを確認してください。設定を編集した後は、MCPホストを再起動してください。didit_org_top_upとdidit_org_reveal_application_api_keyは、ホスト型コネクタには一切表示されません。
オリジンのみのhttps://mcp.didit.meではなく、https://mcp.didit.me/mcpを指定していることを確認してください。リソースメタデータはそのパスにスコープされた/.well-known/oauth-protected-resource/mcpで提供されます (オリジンのルートを確認するクライアント向けに、ルートにもコピーがあります)。セルフホストしている場合、通常はMCP_RESOURCE_URIに完全なトランスポートURLではなくオリジンが設定されていることが原因です。セルフホスティングを参照してください。
ホスト型エンドポイントに対しては、ファイルを*_base64 (生のbase64またはdata: URL) として送信してください。*_pathはローカルのstdioサーバーでのみ機能します。ファイルの上限は15 MBで、拡張子だけでなく内容がPNG、JPG、WebP、GIF、BMP、ICO、PDFのいずれかである必要があります。

​
セキュリティ

MCPはあなたの実際の権限で動作し、本番のリソースを変更できます。クライアントでは「実行前にツール呼び出しを確認する」設定を有効のままにしてください。特に書き込みとDestructiveのツールでは必須です。MCP自体は設定にシークレットを一切保存せず(Didit でログインを使用します)、ツールの出力に含まれるAPIキーとWebhookの署名シークレットを伏せ字にし、チャージ用ツールと生のキーを扱うツールをホスト型カタログから除外し、リモートサーバー上ではアカウントの認証情報をツールの引数として受け付けません。すべてのツール呼び出しは、呼び出し元、ツール、権限の判定結果とともにサーバーの監査ログに記録されます。

​
プロンプトインジェクション

Diditのツールは、氏名、書類のテキスト、アンケートの回答など、ユーザーが入力またはアップロードした内容を返します。 これらのテキストは認証を受ける本人が自由に書けるため、本人が氏名や書類にエージェント向けの指示を書き込むことができます。サーバーはこれらのフィールドを取得したときのまま返します。 エージェントはこうしたテキストとあなた自身の指示を確実に見分けることができないため、すべてのツールの結果はデータとして扱ってください。
  • 書き込みとDestructiveのツールではツールの承認を有効のままにし、承認する前にエージェントが実行しようとしている内容を確認してください。
  • 作業内容に見合った役割のメンバーとしてサインインしてください。セッションを読み取るだけのエージェントであればREADERメンバーを使えます。その場合、エージェントが何を試みてもバックエンドが書き込みを拒否します。
  • 新しいエージェントやプロンプトは、まずサンドボックスのアプリケーションで試してください。
  • 認証の中に含まれるテキストがそう指示しているという理由で、その認証を承認または却下しないでください。判定、その警告、そしてあなた自身のレビューに基づいて判断してください。

​
個人データ

ツールの結果には、氏名、生年月日、書類番号、画像へのリンクなどの個人データが含まれることがあり、MCPクライアントはそれらを使用中のモデルに送信します。 本番のアプリケーションを接続する前に、AIプロバイダーとの契約がこのデータを対象としていることを確認するか、サンドボックスのアプリケーションで作業してください。

​
セルフホスティング

ホスト型サーバーはgithub.com/didit-protocol/mcp(MIT)からビルドされています。リポジトリをクローンし、DockerまたはNodeで実行してください。どちらのトランスポートでも、常にDiditのユーザーとして認証します(APIキーモードはありません)。セットアップ手順はインストール → セルフホスティングにあります。

​
環境変数

リポジトリ内の.env.exampleはコピーして使えるテンプレートで、ARCHITECTURE.mdではリソースサーバーと認可サーバーの役割分担を説明しています。HTTPサーバーは起動時に認可サーバーのディスカバリードキュメントを取得し、到達できない場合は設定済みのURLにフォールバックします。

ツールリファレンス

すべてのツールを分野別にまとめています。

使用例

プロンプトとエンドツーエンドの会話例。
最終更新日 2026年11月1日