mspbots-fleet-mcp

MSPbots Fleet Platform API 用の MCP サーバー — fleetdm 上に構築されたマルチテナントコンソールで、ホストインベントリ、オンデマンドスクリプト、保存済みの osquery クエリを MCP クライアントに公開します。

姉妹サービスである mspbots-agent-mcp と同じ設計に従います: ステートレス、認証情報を保存しない、Model Context Protocol (Streamable HTTP/SSE トランスポート) を介したリクエストごとのヘッダー認証。

どのような場合に使用しますか

この MCP は、サードパーティ統合ではなく、MSPbots の内部製品 (デバイスフリート管理) をラップします。典型的な使用例:

• 「このテナントにはどのホストがあり、どのホストがオフラインですか?」→ mspbotsfleet_list_hosts

• 「このノートパソコンを Production にタグ付けして」→ mspbotsfleet_set_host_labels

• 「このマシンは古いようだ、更新を強制して」(非同期) → mspbotsfleet_refetch_host

• 「そのサーバーでログ収集スクリプトを実行して」→ mspbotsfleet_run_script

• 「今すぐ全 Windows ホストのディスク使用量を知りたい」→ mspbotsfleet_create_query で保存クエリを作成し、次に mspbotsfleet_run_query を実行

• 「新しいノートパソコンのバッチが登録されたので、宣言したものをクレームしよう」→ mspbotsfleet_claim_hosts

• 「このデバイスをオフボーディングするので、自テナントのものとして追跡を停止する (ただし Fleet には残す)」→ mspbotsfleet_release_host

Related MCP server: Rancher MCP Server

ツール

すべてのツールの認証情報はリクエストヘッダー (X-MSP-Token / X-MSP-Tenant-Id / X-MSP-Host) から取得されます。ツールのパラメータにトークンを渡す必要はありません。

ホスト

ホストは API では作成できません。マシンに fleetd がインストールされて登録されると自動的に表示され、その後、このテナントが宣言済みの識別子 (ホスト名/シリアル番号/UUID) に基づいて所有権をクレームします。mspbotsfleet_claim_hosts を参照してください。

ホスト一覧はフル取得後にメモリ内でフィルタ・ソート・ページングされます。Fleet 側のデータは15秒キャッシュされ、所有情報はキャッシュせずにリアルタイムで DB を照会します。 claim_hosts は {claimed, waiting, rejected} を返します。waiting は宣言済みだがまだ Fleet のホストが表われない状態、rejected は識別子が別テナントに宣言済みであることを示します。

スクリプト

create_script/update_script は {id, name} のみ返します。タイムスタンプなどの他のフィールドは mspbotsfleet_get_script/mspbotsfleet_list_scripts で取得してください。

保存済みクエリ

SQL 検証規則: 単一の SELECT または WITH … SELECT のみ許可され、末尾のセミコロンは自動的に除去されます。本文に ; があれば直接拒否されます。これらの検証はバックエンドで行われ、本サービスでは重複検証しません。

クイックスタート

Docker (推奨)

docker compose up --build

サーバーは http://localhost:8080 で起動します。

ローカル (uv)

uv sync
python -m mspbots_fleet_mcp

ヘルスチェック

curl http://localhost:8080/health
# {"status": "ok"}

ヘルスチェック エンドポイントには認証情報は不要です。

認証パラメータの説明 (Authentication)

/mcp へのすべてのリクエストには、次の HTTP ヘッダーを含める必要があります (MCP 呼び出し側から提供 — mspbots-agent-mcp / ticketqa-mcp と同様):

この3つのヘッダーのいずれかが欠けていると 401 Unauthorized を返します。

下流の Fleet API 自体は認証失敗 (トークンの欠落/署名エラー/権限不足) に対して常に 403 を返します。401 ではありません — 401 はこのサービスのレイヤー (ゲートウェイヘッダーの欠落) でのみ返ります。

環境変数

MCP エンドポイント

POST http://localhost:8080/mcp

MCP クライアントは次のように接続します:

• トランスポート: http (Streamable HTTP / SSE)

• ヘッダー: X-MSP-Token、X-MSP-Tenant-Id、X-MSP-Host (すべて必須)

テスト例 (Test Example)

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-MSP-Token: <token>" \
  -H "X-MSP-Tenant-Id: <tenant-id>" \
  -H "X-MSP-Host: https://agent.mspbots.ai" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "mspbotsfleet_list_hosts", "arguments": { "status": "online", "per_page": 10 } }
  }'

⚠️ このリポジトリは公開リポジトリです。実際の token / tenant id などの機密情報をコミットするファイルの内容に書き込まないでください。上記の <token> / <tenant-id> は単なるプレースホルダーです。