19. MCP サーバー (AI アシスタント連携)

MCP(Model Context Protocol) サーバーは、Claude などの AI アシスタントが Platform の現場データを自然言語で問い合わせ、診断することを可能にする通路です。アシスタントがタグ値を読み取り、アラームのコンテキストを収集し、資産階層を走査し、確認処理(ack)まで行います。

REST API を代替するものではありません — 同じ V5 サービス層を同じ JVM 内で呼び出し、認証・監査・レート制限も /api/v5/* のものをそのまま使用します。

項目	値
エンドポイント	`POST https://<server>/api/v5/mcp`
伝送	Streamable HTTP, stateless — セッションを作成しないため再起動に安全です
スペック	MCP 2025-11-25 安定版
提供	ツール 32種 · リソース 7種 · プロンプト 3種 · 自動完結 · 進捗率 · Elicitation

接続方法

ステップ 1 — `api_key` 発行

MCP は別途認証体系を設けず、V5 API キーをそのまま使用します。管理者が発行した api_token と交換します。

curl -s -X POST "https://<server>/api/v5/auth" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"token":"<api_token>"}'
# 200: { "data": { "api_key": "..." }, "meta": { "status": "OK" }, "errors": null }

成功判定は «HTTP 200» ではありません

meta.status が OK であり、data.api_key が空でない場合に成功となります。また、503 は資格情報が間違っているという意味ではありません — トークンストレージに到達できず、判定自体が行われていない状態です。応答ごとの修正箇所については開始하기 §1.8 に表形式で記載されています。

トークンの役割が ADMIN または API である必要があります

MCP は読み取り呼び出しまですべて POST で送信します。V5 フィルタは POST·PUT·DELETE·PATCH を ADMIN/API 役割にのみ許可するため、トークンの役割が USER の場合、読み取りツールさえも 403 で拒否されます。読み取り専用で利用する計画であっても、トークン自体は ADMIN/API として発行してください。

ステップ 2 — クライアントへの登録

# Claude Code
claude mcp add --transport http plantpulse "https://<server>/api/v5/mcp" \
  --header "X-API-Key: <api_key>"

// Claude Desktop — .mcp.json
{
  "mcpServers": {
    "plantpulse": {
      "type": "http",
      "url": "https://<server>/api/v5/mcp",
      "headers": { "X-API-Key": "<api_key>" }
    }
  }
}

X-API-Key の代わりに Authorization: Bearer <api_key> も使用可能です。認証に失敗すると、401 と共に WWW-Authenticate: Bearer ヘッダーが返されます。

ブラウザから接続するクライアントは Origin 登録が必要です

DNS リバインディングを防ぐため、Origin ヘッダーをホワイトリストで検査します。Claude Desktop · Claude Code のように Origin を送信しないネイティブクライアントは常に許可されますが、ブラウザベースのクライアントは AI_MCP_ALLOWED_ORIGINS に登録する必要があります。 デフォルト値は空であり、登録前はすべて 403 となります。

ツール 32種

読み取り 31種 + 書き込み 1種(acknowledge_alarm) です。削除・制御・設定変更ツールは設計段階から存在しません。

ツール	機能	必須引数
`search_entities`	名称・ID・説明でドメインオブジェクトを検索(名称 → ID)。ID がない場合にまず呼び出します	`query`
`list_latest_tag_values`	タグ現在値	`tag_ids`
`get_tag_history`	タグ期間履歴	`tag_id`, `from`
`get_asset_snapshot`	設備前タグスナップショット	`asset_id`
`list_alarms`	アラーム一覧	—
`acknowledge_alarm`	アラーム確認 — 事由(`comment`)必須、監査に残ります	`alarm_seq`, `comment`
`get_alarm_context`	アラーム原因診断セット	`alarm_seq`
`list_alarm_suppressions`	非表示アラーム(非表示・抑制・サービス除外)	—
`get_alarm_performance`	アラームシステム性能 — `GET /alarm/performance` と同等の値	`scope_type`, `scope_id`
`get_edge_status`	エッジゲートウェイ 1台の状態	`edge_id`
`list_edge_status`	エッジゲートウェイ一覧	—
`get_edge_connection_history`	エッジ健全履歴(日別区間)	`edge_id`, `date`
`list_opc_connections`	OPC 収集接続一覧	—
`get_asset_tree`	設備階層ツリー	`asset_id`
`get_asset_by_external`	MES · EAM 番号で階層ノードを検索	`external_system`, `external_id`
`get_site_overview`	サイトオントロジー概要	`site_id`
`trace_asset_relations`	関係追跡 — 上流・下流影響	`entity_id`
`query_knowledge_graph`	オントロジー SPARQL 問い合わせ	`sparql`
`list_asset_documents`	設備添付文書	`asset_id`
`get_asset_timeline`	設備イベントタイムライン	`asset_id`
`list_work_orders`	ワークオーダー一覧	—
`get_work_order_kpi`	ワークオーダー詳細 + KPI	`order_id`
`get_work_order_by_external`	MES · ERP 番号でワークオーダーを検索	`external_system`, `external_id`
`get_asset_kpi`	設備期間 KPI 要約(状態・アラーム・OEE)	`asset_id`, `from`
`get_asset_schedule`	設備・サイトカレンダー(交代・停止・休日)	`asset_id`
`list_maintenance_orders`	整備オーダー(呼出・修理・部品・ISO コード)	`scope_id`
`get_maintenance_summary`	整備要約(部位・故障モード・待機/修理・反復)	`scope_id`
`get_maintenance_order_by_external`	CMMS 番号で整備オーダーを検索	`external_system`, `external_id`
`get_connection_health`	設備階層健全ロールアップ	—
`get_current_time`	サーバー現在時刻	—
`get_eql_reference`	コンソール入力欄の EQL 参照(構文・イベント種類・関数・例)	`surface`
`validate_eql`	EQL コンパイル検査(デプロイせず)	`surface`, `eql`

整備行のキーは V5 整備オーダーと同じです — maintenance_order_id(文字) · maintenance_kind_code · status_code · failure_record_seq · maintenance_plan_id(文字) · failure_mode_code · maintainable_item_code です。maintenance_order_id は MAINTENANCE_ORDER_000001 または旧行の数字文字列("12")であるため、数値として扱わないでください。

深刻度値は ERROR · WARN · INFO です

get_connection_health 画面ラベルに見える critical/major/minor は表示用バケットです。list_alarms(severity=) フィルタには正準値を使用する必要があります。

リソース 7種

アシスタントがツールを呼び出す前に「何があるか」を走査する読み取り専用通路です。

pp://sites · pp://ontology/{site_id} · pp://assets/{site_id}/tree · pp://uns/{site_id} · pp://catalog/{store}/tables · pp://catalog/{store}/{table}/schema · pp://domain-graph

{store} は metastore · eventstore · analytics のみ許可します。

プロンプト 3種

名称	手順
`diagnose-asset`	資産障害診断 — アラーム → コンテキスト → タグ履歴 → 接続 → 下流影響 → 原因候補
`shift-briefing`	交代ブリーフィング — 健全 → アラーム → オーダー/KPI → 引継要約
`alarm-triage`	アラーム分類 — 一覧 → 優先順位 → 推奨 → (承認時) 確認処理

設定 — `pp.mm_config` の `AI_MCP_*`

設定ファイルではありません

正本は PostgreSQL pp.mm_config 表です。plantpulse-ai.properties は削除され、読み取りパスもなくなりました — プロパティリファレンスを参照してください。

キー	デフォルト値	意味
`AI_MCP_ENABLED`	`true`	`false` の場合、`/api/v5/mcp` が 404 を返します
`AI_MCP_ALLOWED_ORIGINS`	(空値)	ブラウザクライアント Origin ホワイトリスト(カンマ区切り)
`AI_MCP_TREE_MAX_NODES`	`2000`	ツリー応答ノード上限
`AI_MCP_TREE_DEFAULT_DEPTH`	`2`	`get_asset_tree` デフォルト深さ
`AI_MCP_TREE_MAX_NODE_TAGS`	`100`	ノード1つに載せるタグ数
`AI_MCP_TREE_ONTOLOGY_MAX_CHARS`	`200000`	オントロジー応答文字数上限
`AI_MCP_TREE_ONTOLOGY_DEFAULT_DEPTH`	`3`	`trace_asset_relations` デフォルト深さ
`AI_MCP_TREE_ONTOLOGY_MAX_TAGS`	`500`	オントロジー応答全体のタグ行予算

値を変更する方法は1つです — 設定画面(/config/index)または pp.mm_config を修正すること。MCP はリクエストごとにキャッシュを読み取るため、再起動は不要です。

🔴 PP_AI_MCP_* 環境変数は機能しません

初回起動か否かに関わらず同様です。環境変数を表に転記していたシーダーと ${PP_AI_*} 置換層は 2026-09-18 に廃止されました。 設定してもエラーなく静かに無視されます — 「設定したのに機能しない」というトラブルが最も検出しにくいため記載します。行が存在しないキーは、上記表のデフォルト値で読み込まれます。

監査と安全策

認証・レート制限・監査は /api/v5/* フィルタチェーンをそのまま経由します。
acknowledge_alarm は独自監査を残します(行為者 MCP)。事由が欠けている場合はアシスタントに再問い合わせして補完させ、その機能がないクライアントには「事由必須」と通知します。
一般変更監査フックからは除外されます。読み取りまで全て POST であるため、フックをかけると毎回の呼び出しが変更として誤記録されるためです。
トークン伝達パスは存在しません — 同じ JVM サービス層を直接呼び出すため、受け取った資格情報を他のシステムに転送する経路自体が存在しません。

併せて参照

開始하기 · エンドポイント全一覧 · Asset サービス

接続方法​

ステップ 1 — api_key 発行​

ステップ 2 — クライアントへの登録​

ツール 32種​

リソース 7種​

プロンプト 3種​

設定 — pp.mm_config の AI_MCP_*​

監査と安全策​

併せて参照​