Didit MCPサーバーのセルフホスティングガイド

主なポイント

• Didit Model Context Protocol (MCP) サーバーはMITライセンスの下でオープンソースです。公開GitHubリポジトリからビルドし、Docker、Node.js、またはヘッドレスstdioトランスポートで実行できます。
• セルフホスティングは、MCPプロセスがどこで実行されるかを変えるものであり、Diditへの到達方法を変えるものではありません。すべてのモードは、Bearerアクセストークンを持つDiditユーザーとして認証します。MCPツールにはアプリケーションAPIキーモードはありません。
• 完全なセルフホストカタログには121のツールが含まれています。ホストされているOpen Authorization (OAuth) エンドポイントは意図的に115を公開しています。現在のソースの例には、didit_context_get、didit_session_create、およびdidit_transaction_screen_walletが含まれます。
• HTTPエントリポイントはステートレスで、POSTリクエストを通じてMCPトラフィックを受け入れます。リクエストごとに新しいサーバーとトランスポートが作成されるため、ロードバランサーはセッションアフィニティを必要としません。
• コンテナおよびロードバランサーのチェックには/healthzを使用します。サービスを公開する前に、パブリックリソースURI、認証元、トークン検証モード、およびシークレットを明示的に設定してください。

ホストされているエンドポイントは便利ですが、すべてのチームにとって適切な運用選択肢ではありません。企業は、統合を独自のネットワーク境界内に保持したり、ランタイムイメージを制御したり、プライベートなエグレスレイヤーを通じてトラフィックをルーティングしたり、独自の可観測性および変更管理ポリシーを適用したりする必要がある場合があります。Didit MCPリポジトリは、別の製品インターフェースを作成することなく、そのデプロイモデルをサポートします。

このガイドはサーバーの運用にのみ焦点を当てています。カタログとツールの動作については、Didit MCPツールリファレンスを使用してください。マネージドエンドポイントに対するクライアント設定については、Claudeインストールガイドを使用してください。完全な技術リファレンスは、MCP概要および認証ドキュメントにあります。

HTTPまたはstdioエントリポイントの選択

リポジトリは、2つのエントリポイントを持つ1つの共有ツールカタログを構築します。dist/http.jsは、ステートレスなストリーマブルHTTP上でExpressリソースサーバーを実行します。これは、複数のMCPクライアント、コンテナ、またはユーザーによってアクセスされる共有サービスに最適な選択肢です。dist/index.jsはstdio上で実行され、1つのクライアントによって起動されるヘッドレスローカルプロセス向けです。

両方のエントリポイントは同じディスパッチロジックを呼び出し、バージョン5はMCPツールのみを公開します。MCPリソースやプロンプトは公開しません。両方ともダウンストリームリクエストをDiditユーザーとして認証します。違いは、そのユーザー認証情報がプロセスに到達する方法です。HTTPエントリポイントは呼び出し元のOAuth Bearerトークンを受信および検証し、stdioエントリポイントはDIDIT_ACCESS_TOKENからユーザーBearerトークンを読み取ります。

セルフホストとは、認証情報が不要という意味ではありません。MCPは依然としてDiditユーザーとして機能し、Diditはそのユーザーの組織の役割と権限をすべてのツール呼び出しに適用します。

Dockerでのビルドと実行

リポジトリには、Node 20に基づくマルチステージDockerfileが含まれています。ビルドステージでは開発依存関係をインストールし、TypeScriptをコンパイルし、開発パッケージを削除します。プロダクションステージは非ルートのnodeユーザーとして実行され、コンテナのヘルスチェックが含まれます。

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

コンテナを起動する前に、デプロイメントを識別するホストされたデフォルトを置き換えてください。最低限、MCP_RESOURCE_URIをクライアントがこのリソースサーバーに到達するパブリックオリジンに設定し、その後、トークンイントロスペクションに必要なOAuthクライアント認証情報を提供します。.envファイルをコミットするのではなく、シークレットはコンテナプラットフォームのシークレットマネージャーに保持してください。

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

TLS (Transport Layer Security) はイングレスまたはロードバランサーで終端し、MCP POSTリクエストをポート3000に転送し、Authorizationヘッダーを保持してください。外部から見えるMCP_RESOURCE_URIは、クライアントにアドバタイズされるリソースIDと一致する必要があります。異なるパブリックオリジンに対して、マネージドDidit URIをそのまま使用しないでください。

Node.jsで直接ビルドと実行

プラットフォームがすでにNodeランタイムを管理している場合は、コンテナなしで同じHTTPエントリポイントを使用してください。パッケージはプライベートであり、npmを通じて配布されていないため、公開されているパッケージを実行しようとするのではなく、リポジトリをクローンしてください。

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

プロセスはコンテナと同じ環境変数を読み取ります。プロセススーパーバイザーの下で実行し、デプロイメント環境を通じてシークレットを注入し、必要なエンドポイントのみをルーティングします。MCPリクエストはPOST /mcpに送られます。このサービスは、MCPセッションやサーバーが開始するストリームを維持しないため、このルートでのGETおよびDELETEを意図的に拒否します。

Node.jsはリポジトリの.envファイルを自動的に読み込みません。dist/http.jsを起動する前に、シェルで値をエクスポートするか、サービスマネージャーを通じて注入するか、プラットフォームの環境ファイルサポートを使用してください。また、npm startはstdioエントリポイントを起動することに注意してください。HTTPの場合はnode dist/http.jsまたはnpm run start:httpを使用してください。

stdio経由でヘッドレス実行

ローカルエージェント、ビルドランナー、または分離されたシングルクライアントプロセスの場合、stdioエントリポイントを使用します。環境を通じてユーザーアクセストークンを提供し、MCPクライアントにプロセスのライフサイクルを任せます。

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

このトークンはユーザーBearer認証情報であり、アプリケーション認証情報ではありません。シークレットとして保存し、シェル履歴やログに残さないようにし、アクセスポリシーに従ってローテーションしてください。1つのデプロイメントが常に1つの組織またはアプリケーション内で動作する場合、MCP_DEFAULT_ORGとMCP_DEFAULT_APPがそのデフォルトスコープを提供できます。それ以外の場合は、ツールは明示的な引数または認証されたリクエストコンテキストからスコープを解決できます。

stdioにはアプリケーションAPIキーモードは依然としてありません。セルフホストHTTPとセルフホストstdioはどちらもユーザー範囲のDiditコンソールエンドポイントを呼び出すため、アプリケーションキーはユーザーBearerトークンの代わりにはなりません。

完全な環境インターフェースの設定

現在のsrc/config.tsは以下の変数をサポートしています。ほとんどのデプロイメントでは、本番Didit APIおよび認証のデフォルトを維持し、トポロジに必要なリソースID、検証設定、およびシークレットのみをオーバーライドする必要があります。

共有およびstdio変数

• DIDIT_ACCESS_TOKEN: ヘッドレスstdioモードのユーザーBearerトークン。デフォルトなし。
• DIDIT_API_BASE_URL: 検証APIベース。デフォルトはhttps://verification.didit.me/v3。
• DIDIT_AUTH_BASE_URL: 認証APIベース。デフォルトはhttps://apx.didit.me/auth/v2。
• MCP_DEFAULT_ORGおよびMCP_DEFAULT_APP: シングルテナントデプロイメント用のオプションの組織およびアプリケーションのデフォルト。

HTTPリソースサーバー変数

• MCP_PORT: リッスンポート。デフォルトは3000。
• MCP_RESOURCE_URI: パブリックリソースサーバーURI。デフォルトはhttps://mcp.didit.me。
• MCP_AUTHORIZATION_SERVER_ORIGIN: 認証サーバーオリジン。デフォルトはhttps://business.didit.me。
• MCP_TOKEN_VERIFY_MODE: デフォルトはintrospection。認証サービスがローカル署名検証に適したJSON Web Tokens (JWT) を発行する場合はjwks。
• MCP_OAUTH_CLIENT_IDおよびMCP_OAUTH_CLIENT_SECRET: デフォルトなし。RFC 7662イントロスペクションのHTTP Basic認証情報として使用されます。
• MCP_OAUTH_INTROSPECT_URL: デフォルトはhttps://apx.didit.me/auth/v2/introspect/。
• MCP_SCOPES_SUPPORTED: スペース区切りのディスカバリスコープ。デフォルトはdidit:management didit:verification。

認証メタデータの上書き

• DIDIT_AUTH_ISSUER: デフォルトはMCP_AUTHORIZATION_SERVER_ORIGIN。
• DIDIT_OIDC_DISCOVERY_URL: OpenID Connect (OIDC) ディスカバリドキュメント。デフォルトは認証オリジンと/.well-known/oauth-authorization-serverを組み合わせたもの。
• DIDIT_JWKS_URL: JSON Web Key Set (JWKS) エンドポイント。デフォルトはhttps://apx.didit.me/auth/config/jwks/。
• DIDIT_OIDC_AUTHORIZE_URL: デフォルトは認証オリジンと/authorizeを組み合わせたもの。
• DIDIT_OIDC_TOKEN_URL: デフォルトは認証オリジンと/api/auth/oauth-tokenを組み合わせたもの。
• DIDIT_OIDC_REGISTRATION_URL: デフォルトは認証オリジンと/api/auth/oauth-registerを組み合わせたもの。

不透明なアクセストークンにはintrospectionを使用します。サーバーは、MCP_OAUTH_CLIENT_IDとMCP_OAUTH_CLIENT_SECRETを使用して、設定されたイントロスペクションエンドポイントにそれらを送信します。jwksは、認証サービスがこのクライアント向けに署名済みJWTアクセストークンを発行するように設定されている場合にのみ使用します。サーバーはその後、DIDIT_JWKS_URLに対して署名を検証します。検証モードを変更しても、異なるIDモデルが作成されるわけではありません。検証されたプリンシパルはDiditユーザーのままです。

MCPクライアントは、認証フロー中にDidit Business ConsoleでDynamic Client Registration (DCR) を使用できます。このクライアント登録は、イントロスペクションリクエストを認証するリソースサーバーのMCP_OAUTH_CLIENT_IDおよびMCP_OAUTH_CLIENT_SECRETとは別です。クライアント登録がそれらを置き換えることができると仮定するのではなく、適切なDiditデプロイチャネルを通じてこれらのサーバーサイド認証情報をプロビジョニングしてください。

ヘルスチェックとステートレススケーリング

HTTPプロセスはGET /healthzを公開し、status、service、versionを含むJSONを返します。Dockerイメージはすでに15秒の起動期間の後、30秒ごとにこれをチェックしています。Kubernetesのレディネス、Application Load Balancerのターゲットグループ、または外部のアップタイムプローブにも同じエンドポイントを使用できます。

curl -fsS http://localhost:3000/healthz

MCPルートは設計上ステートレスです。認証されたPOSTごとに、プロセスはセッション生成が無効になった新しいサーバーとストリーマブルHTTPトランスポートを作成し、呼び出し元の検証済み認証情報をリクエストごとのコンテキストを通じて転送し、ディスパッチを完了し、トランスポートを閉じます。後のリクエストが同じレプリカ上で見つける必要のあるインメモリセッションはありません。

ここで、ステートレスとはMCPトランスポートとリクエストライフサイクルを指します。検証セッション、ワークフロー、ケース、その他のビジネスレコードは、Diditのアップストリームサービスに永続化されます。

その結果、水平レプリカはスティッキーセッションを必要としません。どの正常なインスタンスでも次のPOSTを処理でき、ローリングデプロイメントは通常のインフライトリクエスト処理以外のセッションドレインを必要としません。キャパシティプランニングは、リクエストの同時実行性、ダウンストリームのDidit APIのレイテンシ、および通常のタイムアウトと再試行ポリシーに焦点を当てるべきです。

サービス公開前の検証

• ロードバランサーと同じネットワークパスから/healthzが成功することを確認します。
• 認証されていないMCPリクエストがツール出力ではなく認証チャレンジを受け取ることを確認します。
• PKCE (Proof Key for Code Exchange) を使用してOAuth 2.1フローを完了し、didit_context_getを呼び出して、期待される組織とアプリケーションが表示されることを確認します。
• ディスカバリーエンドポイントまたはトークン検証を変更する前に、高度なMCPドキュメントを確認してください。
• サポートされているマネージドインターフェースと現在のリンクについては、Didit MCP開発者ページを使用してください。

セルフホスティングが不要になった場合、マネージドエンドポイントは上記のランタイムおよびOAuthリソースサーバーの操作を不要にします。Claudeユーザーは、Diditコネクターディープリンクで追加できます。プロセスを実行するかDiditが実行するかにかかわらず、コアとなるルールは同じです。MCP操作はアプリケーションAPIキーとしてではなく、Diditユーザーとして認証されます。