conduit-mcp

複数の SaaS インテグレーションを3つのメタツールの背後に持つリモートMCPサーバーです。100を超えるツールをすべてのクライアントに公開する代わりに、サーバーはlist_integrations、find_tools、invoke_toolを公開します。クライアントはタスクの説明からカタログを検索し、一致するツールスキーマを取得し、正確な名前で呼び出します。管理ポータルはプラグイン、APIキー、ロール、使用状況を管理します。

同梱インテグレーション: HaloPSA、Hudu、CIPP、NinjaRMM、QuickBooks Online。

構成

Related MCP server: MCPHub

実行方法

Node.js >= 22 と corepack 経由の pnpm が必要です（バージョンは package.json の packageManager に固定されています）。

corepack enable
scripts/setup.ps1    # or setup.sh: frozen-lockfile install + full workspace build
pnpm dev

pnpm dev は concurrently で1つのターミナルですべてを実行し、出力はプロセスごとにプレフィックス付けされます: azurite (インメモリ テーブルストレージ)、sdk + server の tsc ウォッチャー、API サーバー、next dev。Ctrl+C で一機を停止します。pnpm serve はウォッチャーを省略し、ビルド済みの API と静的 Web エクスポートのみを配信します。

• ポータル: http://localhost:3000 (next dev、API 呼び出しを :4000 にプロキシ)

• API + MCP: http://localhost:4000 (/healthz、/mcp)

設定が何もない場合、サーバーは未構成のまま起動し、ポータルには entra アプリのセットアップ手順を案内するブートストラップセットアップウィザードが表示されます。スキップするには、.dev.env.example を .dev.env にコピーし、ENTRA_TENANT_ID / ENTRA_CLIENT_ID / BOOTSTRAP_ADMIN_OID を事前に設定しておきます。pnpm dev は起動時にそれを読み込みます。

リポジトリ全体のチェック: pnpm lint、pnpm typecheck、pnpm test、pnpm build。

しくみ

MCP サーフェス。 /mcp は streamable HTTP で通信します。リクエストは entra のベアラートークンまたは conduit API キーで認証されます。OAuth だけをサポートするクライアントのために、サーバーは認可を entra にプロキシします（認可サーバーメタデータと動的クライアント登録）。セッションとイベンストリームはテーブルストレージに永続化されるため、再接続後もストリームは維持されます。

カタログとメタツール。 すべてのプラグインツールは検索可能なカタログ (minisearch) にインデックスされます。find_tools は一致するツールスキーマを一目返し、invoke_tool は完全名で実行して使用状況を記録します。権限は検索結果と呼び出しの両方をフィルタリングするため、プリンシパルは自分の権限が許可したツールだけを見ることができます。

プラグイン。 プラグインは conduit.plugin.json マニフェスト（id、entry、シークレット、ポータル設定 UI、公開ルート）を持つソースディレクトリです。loader は読み込み時に esbuild でエントリをホストの SDK に向けてバンドルし、ツールをカタログに登録し、ポータルルートを /api/plugins/:pluginId の下にマウントします。packages/plugins 内のパッケージは自動的にシードされ、追加はポータルから Git 経由でインストールできます。docs/writing-plugins.md では、SDK に対するプラグインの作成と、カスタムプラグインのインストール方法について説明しています。

認証モデル。 プリンシパルは entra ユーザーか API キーです。ロールは統合ごとの権限（読み取り専用またはフルアクセス、さらに個別ツールまで）を持ち、リクエストごとに解決されます。ポータルアクセスは別のレイヤーであり、ポータルのロールが MCP ツールのアクセス権を拡大することはありません。BOOTSTRAP_ADMIN_OID が最初の管理者をシードします。

ストレージとシークレット。 azure table storage がすべての状態（config、プラグインレジストリ、ロール、APIキー、使用状況、MCPセッション）を保持し、ローカルでは azureite が代役を務めます。シークレットは AZURE_KEYVAULT_URL が設定されている場合は key vault に格納され、それ以外は平文の env vars 環境変数になります。

ポータル。 静的エクスポートされた next.js で、本番では API サーバー自身が配信します (apps/web/out)。ローカルのウォッチモードでは代わりに next dev が実行されます。

デプロイ

Dockerfile は、Web エクスポートを内包した自己完結型サーバーイメージをビルドします。CI (.github/workflows/deploy.yml) はテストを実行し、main にプッシュがあるたびに ghcr.io/<owner>/<repo>:<sha> をビルドしてプッシュします。初回の公開時のみ: パッケージはデフォルトでは private のため、リポジトリ設定 > パッケージで public に変更してください。そうすれば App Service がレジストリの資格情報なしで取得できます。

infra/main.bicep（サブスクリプションスコープ）はリソースグループ、App Service、ストレージ、Key vault をプロビジョニングします。entra アプリ登録は次の2通りのどちらかで行われます。

セットアップウィザード（bicep を一度実行）。 entra のパラメータを空のままデプロイしてポータルを開くと、bootstrap ウィザードがデバイスコードでサインインし、Graph を使ってアプリ登録を作成し、テナント ID・クライアント ID を設定ストレージに書き込みます。セットアップが完了するまで /api/setup/* は認証なしで使え、最初にサインインした人が管理者になります（trust-on-first-use）。セットアップ完了後、セットアップゲートはそれらのエンドポイントに 404 を返します。

スクリプト経由（bicep を run に実行）。 セットアップ画面を開かず、server は設定済みの状態で起動します。entra スクリプトには 1 回目の実行の出力（リダイレクト URI 用の webapp URL、クライアントシークレット用の key vault 名）が必要です。bicep 自体はアプリ登録を作成できないため、2回目の実行で id をアプリ設定として反映しています。

# 1. infra, entra params blank. operatorObjectId grants the KV write step 2 needs
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid>

# 2. app registration + client secret into key vault
#    PS7, az login as a user with Application.ReadWrite.OwnedBy, -DryRun to preview
./infra/scripts/setup-entra-app.ps1 -DisplayName "conduit-mcp" \
  -ProdUrl <webAppUrl output> -KeyVaultName <keyVaultName output>

# 3. same deployment plus the ids the script printed
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid> \
     entraTenantId=<tenant-id> entraClientId=<client-id>

アプリ設定を変更するとコンテナが再起動します。起動時、config store に ID を種取得します（空欄のみを埋め、config put が権威を保持します）。

継続的デプロイ（オプトイン）。 ワークフロー用に OIDC フェデレーションを作成し、AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID のシークレットと AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP の変数を設定します。そしてリポジトリ変数 AZURE_DEPLOY=true を設定します。すると main へのプッシュ後に webapp が pushes しされたばかりのイメージをポイントします。

ポータル内更新。 管理画面では、レジストリのイメージが実行中のビルドと異なるかどうかを表示し（CI が git sha をイメージに焼き込んでいます）、アプリを再起動して取得できます。再起動には bicep がマネージド ID に付与した「再起動専用」のカスタムロールを使用するため、このロールが存在する前に作成されたデプロイでは、ボタンを動かすには bicep の再実行が必要です。