Dashboard Builder MCP サーバー

AI クライアントが Dashboard Builder でデータセットを検出し、ダッシュボードを作成できるようにします。

通常の API クライアントとして HTTP 経由で Next.js アプリと通信するため、アプリ内のすべての権限ガード、依存関係ポリシー、検証ルールが引き続き適用されます。メインアプリケーションには何も変更はありません。

2 つの方法で実行できます:

ホステッドが通常のデプロイ形態であり、このドキュメントの対象です。ローカルモードはサーバー自体の開発や、ユーザーごとのアイデンティティ用で、DEVELOPMENT.md に記載されています。

ユーザー向け: ホステッドサーバーへの接続

デプロイした担当者から URL と ゲートキー の 2 つが必要です。クローンするものも、指定するファイルも、.env もありません。

これを claude_desktop_config.json(Claude Desktop)または .mcp.json(Claude Code)に追加します:

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers は トップレベル のキーで、preferences の兄弟です — preferences の中にネストさせないでください。Claude Desktop をシステムトレイから終了して再度開いてください。ウィンドウを閉じるだけでは不十分です。

2 つの X-Dashboard-* ヘッダーがあれば、サーバーは初回使用時に自動的にあなたとしてログインし、セッションが期限切れになるたびに再ログインします — 他に何もする必要はなく、すべての呼び出しは あなた として動作します: あなたの権限、あなたの監査証跡。トレードオフとして、ダッシュボードのパスワードがこの設定ファイルに保存され、各リクエストとともに(HTTPS 経由で)送信されます。パスワードに ASCII 以外の文字が含まれる場合は、代わりに以下の curl バインドを使用してください — HTTP ヘッダーはそれらを確実に運びません。

代替案: curl で一度バインドし、パスワードを設定ファイルに置かない

2 つの X-Dashboard-* ヘッダーを省略し、代わりにキーを一度バインドします — パスワードはその 1 回のログインにのみ使用され、どこにも保存されません。サーバーは結果のセッショントークンのみを保持します。ブラウザが Cookie を保持するのとまったく同じです:

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

ヘッダー方式との違い: セッションチェーンが最終的に期限切れになった場合はこのコマンドを再実行します。一方、ヘッダー方式では自動的に再バインドされます。どちらの場合も、同じ Authorization ヘッダーを使用した DELETE /auth/bind でキーのサインアウトが行われます。

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

キーがバインドされていない場合、ツール呼び出しはバインド手順を説明するエラーで失敗します — または、サーバーがレガシーサービスアカウントで設定されている場合は、その共有アイデンティティにフォールバックします。

mcp-remote はローカルで実行されサーバーに転送する小さなブリッジであるため、ユーザーのマシンに Node がインストールされている必要があります。それさえも避けるには、Claude Desktop の Settings → Connectors → Add custom connector で URL を直接指定でき、ローカルに何も必要ありません — その方法は静的キーではなく OAuth を想定しており、利用可否は Desktop のバージョンによって異なります。

Related MCP server: MCP SQL Server Data Warehouse Connector

サーバーのデプロイ

server.js が起動ファイルです。Next.js の server.js のように PORT で待ち受け、すべての MCP リクエストの前に API キーゲート を置くため、認証されていない呼び出し元はダッシュボードシステムに到達する前に拒否されます。

エンドポイント: POST /mcp(ゲート付き)、POST /auth/bind と DELETE /auth/bind(ゲート付き — 呼び出し元キーのダッシュボードアイデンティティをバインドまたはアンバインド)、および GET /health(オープン、プラットフォームのヘルスチェック用)。それ以外はすべて 404 を返します。

環境変数

必須 — これらがないとサーバーは起動しません

キーは openssl rand -hex 24 で生成します。コロンの前のラベルはログとレート制限バケットに表示されます。シークレット自体は決してログに記録されません。1 人を失効させるには、そのエントリを削除して再起動します — さらに ~/.dashboard-mcp/sessions/ の下にあるセッションファイルも削除して、バインドされたアイデンティティも破棄します。

各キーはその後、所有者が POST /auth/bind を介してダッシュボードアカウントにバインドします — 上記のユーザーセクションを参照してください。ダッシュボードの資格情報はサーバーの環境には存在しません。

オプションのレガシーフォールバック — 共有サービスアカウント

設定すると、バインドされていないキーは失敗する代わりにこの共有アカウントとして動作します — バインドが期限切れになったキーも、再バインドされるまで同様です。移行中に便利です。新しいデプロイでは省略して、すべての呼び出し元が自分のアイデンティティを持つようにしてください。

強く推奨

DASHBOARD_MCP_PERSIST_SESSION はデフォルト(true)のままにしてください: バインドはキーごとに 1 ファイルで保存され、再起動後も維持されます。false に設定するとバインドはメモリ内のみに保持されるため、再起動のたびに — そしてマルチワーカーホストの各ワーカーも — 独自の再バインドが必要になります。

MCP_ALLOWED_HOSTS と MCP_ALLOWED_ORIGINS は オプション です — サーバーはこれらなしでも実行され、API キーゲートは引き続き適用されます。どちらかを設定すると、トランスポートの DNS リバインディング保護が有効になります。両方とも未設定のままにすると、起動ログにその旨が明示的に表示されます。

オプション

その他の調整変数 — セッションファイルのパス、リクエストタイムアウト、レスポンス上限、ダッシュボード種別 ID の上書き — は .env.example にインラインで文書化されており、モード別に整理され、サーバーが読み取るすべての変数がリストされています。

マルチワーカーに関する注意

バインドはキーごとに 1 ファイルで、別のワーカーによってメモリ内トークンがローテーションされたワーカーは、そのファイルを再読み取りして復旧します。このファイルは勝者となったワーカーがすでに更新しています。障害ウィンドウは、2 つのワーカーが同時に同じトークンを更新する瞬間です。敗者は次の試行で復旧し、最悪の場合はキーを再バインドする必要があります。MCP トランスポート自体はステートレスであるため、リクエストはどのワーカーにも着地できます。

Plesk のセットアップ

ドメインの Additional nginx directives に追加:

proxy_buffering off;
proxy_read_timeout 300s;

MCP は Server-Sent Events として応答し、nginx はデフォルトでプロキシされたレスポンスをバッファリングします。proxy_buffering off がないと、リクエストは失敗するのではなくハングしているように見えます。これは午後を無駄にする紛らわしい方法です。

Node ポートはパブリックファイアウォールの外に保ってください。Plesk の nginx がそこにプロキシし、X-Forwarded-For を設定します。これにより、ログに記録されるクライアント IP が信頼できるものになります。

アクセスとアイデンティティ

ゲートキーは アクセス を制御します。アイデンティティは バインド から得られます。キーは呼び出し元をゲートの先へ通し、そのキーにバインドされたセッションがダッシュボードに誰が見えるかを決定します — その人の権限、その人の監査証跡。この 2 つは意図的に分離されています: キーのシークレットをローテーションするとバインドが失われ(セッションはキーのダイジェストの下にファイルとして保存されます)、キーの失効はアカウントに触れることなくアクセスを削除します。

バインドはブラウザのログインと同じように機能します。POST /auth/bind はアプリの実際の /api/auth/login を一度実行し、パスワードは交換後に破棄され、ローテーションするリフレッシュトークンセッションのみが保持されます — キーごとに 1 ファイル、モード 0600。アプリはリフレッシュトークンを使用のたびにローテーションするため、漏洩したセッションファイルはすぐに無効になります。パスワードは保存されないため、長期的に漏洩するものはありません。トレードオフ: リフレッシュチェーンが期限切れまたは破損した場合、そのキーは 1 回の curl で再バインドされます。

安定したリクエストごとの資格情報(メインシステムの ApiKey、または OAuth)があれば、その再バインドさえも不要になりますが、メインアプリケーションの変更が必要です。この設計は意図的に何も変更を必要としません。

ローカルでの開発または実行

自分のマシンでサーバーを実行する場合 — 開発用、またはホスティングなしのユーザーごとのアイデンティティ用 — は、DEVELOPMENT.md に別途文書化されています。

ツール

チェーンは次のとおりです: データソース(HTTP API または Excel アップロード)→ データセット(変換ワークフローを持つ整形されたビュー)→ ダッシュボードウィジェット。ツールは 3 つの段階すべてをカバーします。

test_datasource は、アプリがデータソースの作成/編集権限の背後にゲートし、上流エンドポイントを呼び出すため書き込みセットに含まれます — ただし、何も永続化しません。

設計ノート

コンテキストの規律。 ツール全体の表面積は約7 KB（24の説明とサーバー指示）なので、ロードし続けても安価です。レスポンスは生のJSONではなくコンパクトなテキストで、すべてのリストには省略された内容の明示的な注記が付きます。get_dashboard は意図的にウィジェット設定を省略します。設定が必要な場合は、IDで1つのウィジェットを要求します。

段階的開示。 チャート設定には約59のフィールドがあります。それをツールの説明に入れると、すべてのリクエストでクライアントのコンテキストを支配してしまうため、describe_widget_kind がオンデマンドでコントラクトを提供します: フィールド名、型、注記、最小限の動作例、そして — 有用な部分 — 自分のワークスペースにある同種の既存ウィジェットから収集した実際の設定です。すでにレンダリングされる形をコピーする方が、フィールド名から発明するより優れています。

ジオメトリはサーバーが担当。 モデルは2Dパッキングが不安定です。add_widget は size ヒント（small、medium、large、full）を受け取り、12カラムのグリッド上で最初の空き・非重複セルを自身で見つけます。arrange_dashboard は auto モードでダッシュボード全体を再パックします。

APIの後ではなく、前に失敗する。 ウィジェット設定はアプリによって不透明なJSONとして保存されるため、キーのスペルミスはエラーではなく空白のウィジェットを生成します。add_widget はまず設定を種類のコントラクトに対して検証します — 必須キー、有効な集計名、集計が必要とする場合の field の存在 — そして不足しているものの具体的なリストを返します。

ウィジェットはUIが作成するものと一致する。 アプリのパレットは、レジストリの種類の defaultConfig で新しいウィジェットをシードします（config === undefined ? def.defaultConfig : config）。add_widget はそれを反映します: 種類のデフォルトは呼び出し元が提供するものの下にレイヤーされるため、MCPで作成されたチャートは、レンダラーがフォールバックしなければならない疎な設定ではなく、手動で作成されたものと同じ paginationMode と maxPoints のベースラインを持ちます。検証されるのはマージされたオブジェクトです。

再送ではなくマージ。 PATCH /widgets/:id は設定オブジェクトを丸ごと置き換えます。update_widget はデフォルトでキーを既存の設定にマージするため、1つの設定を変更してもすべてを再送する必要はありません。

起動時はフェイルクローズ。 HTTPサーバーは少なくとも1つの MCP_API_KEYS エントリがないと起動を拒否し、24文字未満のキーを拒否します。認証されていないMCPエンドポイントが偶然に存在することは決してあってはなりません。キーは timingSafeEqual でSHA-256ダイジェストとして比較され、ラベルのみがログに記録されます。

シークレットはサーバー側に留まる。 describe_datasource はアプリの /schema エンドポイントを読み取りますが、これには認証情報は含まれません。update_datasource はマージ対象の完全な保存済み設定を必要とします — ツール実行内でそれを取得し、authConfig、保存済みヘッダー、ボディをモデルのコンテキストにレンダリングすることなく、マージ結果を送り返します。

保存前に検証。 ワークフローエンベロープは微妙に間違えやすいため、フローは次のとおりです: get_dataset includeWorkflow で動作するエンベロープをコピーし、編集し、validate_dataset_workflow を実行し（サーバー側で実行し、何も永続化せずにステップごとの行数、出力フィールド、null数を報告）、その後 update_dataset で保存します。

既知の制限

• ウィジェット種類カタログはコピーです。 src/catalog/widget-kinds.ts は src/features/dashboard/widgets/registry.ts をミラーしています — 各種類の defaultConfig と、種類ごとの設定インターフェースを含みます。アプリのレジストリはクライアントコンポーネントでありReactをインポートするため、ここではインポートできません。ウィジェット種類にフィールドが追加されたり、defaultConfig の値が変更された場合は、カタログも更新してください。そうしないと、MCPで作成されたウィジェットがUIで作成されたものから乖離します。

• カタログのカバレッジは高いが完全ではありません。 文書化された設定フィールドと実際の設定フィールド: table 18/21、stat 22/25、chart 39/59、select 9/12、text 16/17。省略されているのは主に見た目のバリエーション（円/折れ線/棒グラフのスタイルオプション、右側軸のオーバーライド）と、highlightBindings に置き換えられたレガシーなインタラクションキーです。describe_widget_kind が返すライブの例がそれらの参照です。フィールドは core / display / interaction にグループ化され、データコントラクトが最初に読めるようになっています。

• バインディングはリフレッシュチェーンとともに期限切れになります。 キーのセッションは、アプリが回転するリフレッシュトークンを維持している限り続きます。期限が切れると、呼び出しは修正内容を示すエラーで失敗し、キーの保持者は1つのcurlで再バインドします。期限切れのないIDには、メインシステムの src/lib/api-guard.ts に ApiKey を配線する必要がありますが、これは行われていません。

• 書き込みは直接です。 アプリには変更ドラフトと承認のワークフロー（ChangeDraft、ApprovalRequest）があります。これらのツールは、サインイン中のアカウントの権限で直接書き込みます。AIが作成したダッシュボードを公開前にレビューする必要がある場合は、書き込みツールを /api/change-drafts にルーティングし、アカウントの権限を読み取り専用に保ってください。

• Excelデータソースはここでは読み取り専用です。 作成または更新にはマルチパートのファイルアップロードが必要であり、MCPのテキストフローには適合しません。これらは list_datasources、describe_datasource、preview_datasource には引き続き表示されます。作成と更新はUIで行ってください。

• 削除ツールはありません。 データソースの削除は、その上に構築されたすべてのデータセットにソフト削除をカスケードするため、削除はUIでの人間の操作に留まります。delete_widget が公開されている唯一の破壊的ツールです。