Dashboard Builder MCP サーバー

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

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

実行方法は 2 つあります:

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

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

デプロイした担当者から 2 つのものが必要です:URL と ゲートキーです。クローンするものはなく、指定するファイルもなく、.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-* ヘッダーを省略し、代わりにキーを一度バインドします — パスワードはその単一のログインにのみ使用され、どこにも保存されません。サーバーは結果のセッショントークンのみを保持します。ブラウザが 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 の 設定 → コネクタ → カスタムコネクタを追加 で URL を直接受け付け、ローカルに何も必要としません — その方法は静的キーではなく OAuth を想定しており、利用可否は Desktop のバージョンによって異なります。

サーバーのデプロイ

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

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

環境変数

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

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

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

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

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

強く推奨

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

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

オプション

その他のチューニング変数 — セッションファイルのパス、リクエストタイムアウト、レスポンス上限、ダッシュボードの kind id の上書き — は .env.example 内にインラインで文書化されています。.env.example はモードごとに整理され、サーバーが読み取るすべての変数を列挙しています。

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

バインドはキーごとに 1 ファイルで保存され、別のワーカーによってインメモリトークンがローテーションされたワーカーは、勝ったワーカーがすでに更新したそのファイルを読み直すことで回復します。失敗が発生し得るのは、2 つのワーカーが同時に同じトークンを更新する瞬間です。負けたワーカーは次の試行で回復し、最悪の場合はキーを再バインドする必要があります。MCP トランスポート自体はステートレスであるため、リクエストはどのワーカーに届いても問題ありません。

Plesk のセットアップ

ドメインの 追加 nginx ディレクティブ に追加します:

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)があれば、その再バインド

コンテキストの節約。 ツールサーフェス全体で約3.6 KB（13の説明とサーバー指示）しか消費しないため、読み込んだままにしておくコストが低く抑えられます。レスポンスは生の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エンドポイントが偶然に存在することは決してあってはなりません。キーはSHA-256ダイジェストとして timingSafeEqual で比較され、ログに記録されるのはラベルのみです。

既知の制限

• ウィジェット種類カタログはコピーです。 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 にルーティングし、アカウントの権限を読み取り専用に保ってください。