MCP ツールマップ

質問（チャット）の AI と自動化が呼び出せるツールは MCP サーバー 7 か所から来ます。どのサーバーが何を担うのか、そしてツールがあるのになぜ AI が使わないのかをここで整理します。

                              묻기(코파일럿) 의 AI
                                       │
   ┌────────────┬────────────┬─────────┼──┬────────────┬────────────┬────────────┐
   ▼            ▼            ▼            ▼            ▼            ▼            ▼
 플랫폼 통합   시계열 인사이트   RAG       문서 이해      비전       디지털 스레드     공학 계산
 /api/v5/mcp  insight_ 39개  rag_ 2개  document_ 2개  vision_ 5개  thread_ 4~9개   eng_ 4개
   22개
 «공장의 실제  «파형을 보고   «문서에서   «PDF·표를     «사진을     «무엇이 언제     «공식으로
   데이터»      판단»         찾는다»     읽는다»       본다»       일어났고 무엇과    계산한다»
                                                                  이어졌나»

コパイロットはこれらのサーバーを直接接続しません。2026.10 再リリース(2026-10-20) から MCP ゲートウェイ（plantpulse-mcp-gateway-api、内部 7160）一つがプラットフォーム · 内蔵サーバー · オペレーターが接続した外部サーバーのツールをまとめて提供し、コパイロットはそのアドレス一つだけを見ます。内蔵サーバーはゲートウェイがインストール時に自ら登録します。

最初にオンにしておくツール — ゲートウェイポリシー

ツールが最初に検出されたときにオンにするかオフにするかは MCP ゲートウェイのポリシー が決めます。オン/オフを変更する場所は AI 管理コンソール › MCP ゲートウェイ › ツール です → AI 管理コンソール — MCP ゲートウェイ

サーバー	最初に検出されたとき
プラットフォーム統合 MCP	すべてオン
時系列インサイト `insight_`	34 種オン — 39 種のうち書き込み 1 つ（`trigger_feature_pipeline`、オンにできない）と `forecast_order_completion` · `autonomy_status` · `get_oee_losses` · `get_spc_chart` の 4 つはオフ → 時系列インサイトツール
デジタルスレッド `thread_`	9 種オン — 読み取りツールすべて
エンジニアリング計算 `eng_`	4 種オン — 4 つすべて
RAG `rag_`	2 種オン — `rag_search`（文書検索） · `rag_list_documents`
文書理解 `document_`	2 種オン — `document_understand` · `document_profiles`
ビジョン `vision_`	5 種オン — `vision_read_meter` · `vision_inspect` · `vision_ocr` · `vision_analyze` · `vision_classify`
オペレーターが接続した外部サーバー	オフ — ツールごとに説明を読んでオンにします

一覧は名前で記載されています。内蔵サーバーに 新しいツールが追加されるとオフのまま 入ってきます。
管理者が一度変更した値はゲートウェイ DB に残り、起動やバージョンアップで上書きされません。
🔴 チャットの文書検索は rag_search の一本道です。 このツールがオフになっているかアカウントに許可されていなければ、マニュアル・図面・手順の質問に「文書検索ツールがオフになっているか、このアカウントに許可されていません」と答えます。
🔴 これだけオンにしておくのは ツール検索がオンになっている ことが前提です。ゲートウェイが質問ごとに合うツールを 20 個（予算）まで選んでモデルに載せ、名前 → ID を探す search_domains と文書検索 rag_search は予算に関係なく常に別途載せます（許可されたアカウントの場合）。検索設定 で検索をオフにすると、モデルは質問ごとにオンのツール 70 種余りをすべて受け取ります。
検索はツール名・説明に加えて 検索語 で選びます。ツールの説明が英語なので韓国語の質問をツールにつなぐ語で、単語検索にだけ使われモデルには見えません。出所はこのインストールの上書き › サーバー宣言 › ゲートウェイ既定値（プラットフォーム統合 MCP）の順に優先されます。外部 MCP サーバーはツールの _meta["io.plantpulse/search_terms"] に {"ko": ["알람 확인 처리"]} のように宣言できます。ツール 1 つにつき言語 4 つ、全言語合わせて 8 個・64 文字までで、超えると丸ごと破棄します → AI 管理コンソール — ツール検索語

旧版（再リリース 8 まで）はコパイロットがオン/オフを持っており、時系列インサイトは get_attention_ranking など数個だけをオンにしていました。再リリース(2026-10-20) に上げるとその値は 移行されず、上記のポリシーで再スタートします。旧版で意図的にオフにしていたツールがあれば、アップグレード後に再度オフにしてください。

理由は 2 つです。

AI にツールを数十個渡すと選択に失敗します。
使わないツールの説明がリクエストのたびにトークンを消費します。

そのため、オンにするツールをポリシーで決めておき、オンにしたものの中でも検索が質問ごとに絞り込みます。

新しく接続した外部サーバーはオフのまま、誰にも許可されていない状態で始まります

ゲートウェイに外部サーバーを追加してツールを読み込んでも、AI も自動化も何ひとつ使えません。 サーバーをオンにし、ツールごとにオンにし、権限で呼び出し元（コパイロット）に許可する必要があります。外部ツールの説明はモデルのプロンプトにそのまま入るため、読んでからオンにしてください。

「ツールがあるのに AI が使わない」の最初の確認ポイントがここです → AI 管理コンソール — MCP ゲートウェイ

書き込みツールは有効にできません

状態を変更するツールは自動的に除外され、ポリシー上ブロックされます。例外はアラーム確認（ack_alarm） 1 つだけで、それも対象設備の範囲まで確認したうえで初めて通過します。設備を制御したり設定を変更したりする手段は一切ありません。

プラットフォーム統合 MCP — 22 個

工場の実データです。Platform（server-web）が /api/v5/mcp で提供し、api_key で認証します。

軸	ツール	機能
時刻	`get_current_time`	サーバーの現在時刻
構造	`search_domains`	名前で検索して ID を解決する（たいていここから始める）
構造	`get_asset_tree`	資産階層ツリー
構造	`get_ontology`	サイトオントロジー概要
構造	`query_ontology`	資産関係グラフの探索
構造	`query_sparql`	オントロジー SPARQL クエリ
構造	`get_asset_documents`	設備に紐づく文書一覧
接続	`get_edge_status`	Edge ゲートウェイ状態
接続	`get_edge_health_history`	Edge ヘルス履歴（日付別区間）
接続	`list_connections`	OPC 収集接続一覧
タグ	`get_tag_values`	タグ現在値
タグ	`get_tag_history`	タグの期間履歴
アラーム	`list_alarms`	アラーム一覧
アラーム	`get_alarm_context`	アラーム原因診断バンドル
アラーム	`ack_alarm`	アラーム確認処理 — 🔴 唯一の書き込みツール
設備	`get_asset_snapshot`	設備の全タグスナップショット
設備	`get_asset_timeline`	設備イベントタイムライン
設備	`get_asset_stats`	設備の期間ビジネス統計
生産	`list_orders`	ワークオーダー一覧
生産	`get_order_metrics`	ワークオーダー詳細・KPI
生産	`get_asset_kpi`	設備のオーダー別 KPI（OEE/EMS/RAM）
ロールアップ	`get_health`	資産階層ヘルスロールアップ

名前を ID に変換することがほぼ常に最初のステップです

人は「3 ラインのコンプレッサー」と言い、ツールは ID を受け取ります。search_domains がその間をつなぎます — AI が見当違いの設備を選んだなら、たいていこの段階で分かれています。

使い方は MCP サーバー管理、オントロジーツールの詳しい使い方はオントロジーにあります。

時系列インサイト — insight_ 39 個

波形を見て判断する側です。異常検知・予測・過去照合・設備総合・アラーム統計・プロファイル、そして 2026.10 からは AI 発見 · 注意設備 · 生産分析（オーダー完了予測 · OEE ロス · 管理図）。

→ 時系列インサイトツール全一覧

RAG — rag_ 2 個

ツール	機能
`rag_search`	関連文書をハイブリッドモードで検索し、回答と出典を出す。出典ごとの `reference_id` が回答本文の `[n]` と対になります
`rag_list_documents`	索引済み文書の一覧

見つからない場合は «失敗» として返ります

検索が何も取得できなかった場合、rag_search は success: false · retrieved: false と code（NO_CONTEXT · EMPTY_ANSWER） · reason を返し、answer を載せません。 空の結果を «検索結果» として受け取った AI が自分の知識で答えを作り上げるのを防ぐためです — AI が「文書では見つかりませんでした」と答えるのは正常な動作です。

→ 文書検索（RAG）

文書理解 — document_ 2 個

ツール	機能
`document_understand`	URL の文書 1 件を構造化された markdown に変換する — 表・レイアウト・数式を認識。PDF · DOCX · PPTX · XLSX · 画像
`document_profiles`	選択できるパースプロファイルの一覧

プロファイル	用途
`default`	RAG 索引と同じオプション —「RAG はこの文書をどう読んだのか」を確認するとき
`fast`	高速に — OCR オフ、表は粗く
`ocr`	文字のみ — 画像から文字を読みます（表構造の認識はオフ）
`scan`	スキャン文書 — テキスト層を無視してすべて OCR

プロファイルを別に用意している理由

パースオプションを呼び出す側がそれぞれ選ぶと、同じ文書が呼び出し元ごとに違って読まれます。 そのためポリシーをプロファイルにまとめてあります —「表が崩れる」類はプロファイルを変えてみるのが最初の一手です。

文字がまったく出てこない場合は «失敗» です

パーサーが成功と返しても本文が空であれば ok: false で返ります（REST レスポンスは status: "empty"）。たいていは文字層のないスキャン文書を OCR なしで読んだケースなので、scan または ocr プロファイルで呼び直してください。

文書 1 件の上限は既定で 200 MiB（MAX_DOCUMENT_BYTES）で、超えると拒否されます（REST は 413）。エージェント経路は結果が出るまで待機しますが、**MCP_WAIT_TIMEOUT（既定 300 秒）**を超えると失敗として返します。

ビジョン — vision_ 5 個

写真を見ます。ステートレスです — 画像を保存せず、処理後に破棄します。

ツール	機能
`vision_read_meter`	計器（ゲージ・デジタル表示器）の指示値を読む
`vision_inspect`	設備写真から欠陥を見つける — 油漏れ・腐食・亀裂・破損・異物・過熱
`vision_ocr`	写真内の文字を読む — 銘板・ラベル・標識・画面。韓国語は韓国語のまま書き起こします
`vision_classify`	与えられたラベルのいずれかに分類する（ラベル 2 個以上が必要）
`vision_analyze`	写真について自由に質問する

判定が割れた場合は拒否します

ビジョンは曖昧なものを断定しません。 同じ写真を複数回判定させて合意に至らなければ、答えを作り出す代わりに拒否します — 現場判定では「もっともらしい誤答」が「わからない」よりはるかに高くつくからです。

ツール	合意ルール
`vision_read_meter`	5 回中 4 回 — 値と単位が完全に一致する必要があります（最も厳格）
`vision_inspect` · `vision_classify`	3 回中 2 回 — 判定（ラベル）が一致する必要があります
`vision_analyze`	合意なし — 自由記述のため読み取り値・合否判定には使わないでください
`vision_ocr`	3 回中 2 回 — 空白を除いた文字列が一致する必要があります。2026.10 再リリースからはサービング中の LLM が読みます（それ以前は文書理解の docling OCR — 韓国語が読めませんでした）。エンジンは `VISION_OCR_ENGINE` で元に戻せます → 環境変数設定

デジタルスレッド — thread_ 4〜9 個

工場で何がどの順序で起きたのか、何が何とつながっているのかを見ます。値ではなく、事象とつながりの参照を返します — 測定値 · KPI はプラットフォーム統合 MCP か時系列インサイト側です。

ツール	機能	既定
`thread_get_timeline`	設備 · オーダー · タグ 1 つに起きたことを時系列で — 状態変化 · アラーム発生/解除 · オーダー開始/終了 · 計画停止、コパイロットのインシデント · 提案 · 発見。ウィンドウは最大 31 日	オン
`thread_trace_links`	オブジェクトがどうつながっているか — 設備階層 · タグ · 設備間の供給/依存 · 設備に紐づく作業指示 · 工程 · 部品 · 設備で流れたオーダー · 設備に紐づくインシデント · 提案。2 つのオブジェクトを与えると最短経路	オン
`thread_today_work`	職長の今日の作業リスト（`date` 省略時は当日） — その日に計画された、またはプラットフォームで稼働中の工程ごとの準備度 · 設備状態 · 履行する顧客注文の余裕日数とリスク · 待機中の資材 PO · 使用する図面と版の表示。顧客余裕日数が切迫しているものから	オン
`thread_impact_range`	遅れた PO · サプライヤー · 設備 · 不良ロットがどこまで及ぶか — 作業指示 · 顧客注文 · 顧客。前方（遅延が及ぶ先: PO 行 · サプライヤー · 部品 · 設備 · 設計変更 · 保全作業指示から）または後方（品質追跡: ロット · シリアル番号 · 不適合 · 工具 · 試料から）。`as_of` で過去の時点のつながりを、顧客注文の行には ERP 納期と残り日数（D-n）を載せます。つながっていないファミリーは «なし» ではなく «不明» です	オン
`thread_interval_production`	設備の異常 · アラーム · 停止の区間にその設備で何を作っていたか — その区間の作業指示 · ロット · シリアル番号（MES 実行時刻）と、そのロットが及ぶ顧客注文 · 顧客。区間は最大 31 日。MES がなければ «何も稼働していなかった» ではなく «不明» で、区間の後にできたつながりでのみ及ぶ顧客は確定影響と分けて記載します	オン
`thread_explain_recovery`	部品が遅延したときマイルストーンがどれだけずれるかと回復案（what-if） — 数値はサーバーの最適化ソルバーが出し、AI は伝えるだけです。PLM · QM コネクタが有効なら設計変更 · 不適合による追加遅延を、SCM がサプライヤーの供給能力を出せば遅延部品を前倒しで受け取れるかも回答します。影響が及ぶ顧客注文の行（`customer_orders[]`）と、ERP · SCM が食い違った PO 値（`purchase_order_conflicts[]`）も載せます	オン
`thread_work_readiness`	職長の作業準備度 — 工程ごとに GO · AT_RISK · NO_GO · UNKNOWN と項目別理由	オン
`thread_part_revision_status`	品番 · 版が今使ってよい版か — `current` · `outdated` · `change_open` · `unknown`	オン
`thread_check_tooling`	工具管理コネクタから — 校正が遅れた、または落下した計測器で測った測定、作業指示に投入された工具、不適合の原因候補	オン

すべて読み取り専用です（承認なしで呼ばれます）。結果は 16,000 文字以内に縮めて返します。
サーバー一覧に現れる条件が異なります。get_timeline · trace_links · impact_range · interval_production の 4 つは常にあり、explain_recovery は入力の取得先（コネクタレジストリなど）が設定されているとき、today_work · work_readiness · part_revision_status · check_tooling の 4 つはコネクタレジストリ（DT_PG_* · PI_DT_SECRET_KEY）が設定されているときのみ現れます。そのため個数が 4〜9 個になります。
再リリース(2026-10-20) から 9 つすべてが最初からオンです（ゲートウェイポリシー）。オフにする場所は AI 管理コンソール › MCP ゲートウェイ › ツール です → MCP ゲートウェイ
trace_links · get_timeline · impact_range · interval_production の結果のオブジェクト（タイムラインは事象の対象とヘッダー）には、そのシステムのコネクタにリンクテンプレートがあるときだけ元システム画面のアドレス open_url とボタンの文字 open_label が付きます。なければ両方の欄ともありません → デジタルスレッド — 外部リンク
コネクタを接続してミラーを満たすのは管理コンソール側です → デジタルスレッド

エンジニアリング計算 — eng_ 4 個

ベアリング欠陥周波数 · NPSH のような工学値を数式で計算します。モデルが頭の中で概算しないようにするためのサーバーです。サーバーは plantpulse-engcalc-api（スタック内 :7150、外部には公開しません）で、DB · ボリューム · LLM なしで動作します。別途有効化するスイッチはありません — スタックと共に常に起動します。

ツール	画面名	機能	既定
`eng_list_formulas`	工学公式一覧	計算できる公式の一覧	オン
`eng_formula`	工学公式計算	名前付き公式 29 種 — 答えと共に単位 · 代入ステップ · 出典を返します	オン
`eng_unit_convert`	単位変換	単位の変換	オン
`eng_calc_eval`	数式計算	四則 · 指数などの数式計算。許可された演算のみを解き、指数 · 長さ · 時間に上限があります（プログラムは実行しません）	オン

すべて読み取り専用のため、承認なしで呼ばれます。
キーは他のバックエンドと同じ PI_INBOUND_API_KEY です。空の場合、サーバーは起動を拒否します。

外部システムコネクタはここでは接続しません

MES · SCM · ERP · PLM · QM のような外部システムの MCP コネクタは AI 管理コンソール → デジタルスレッド → 連携マップ で登録します。そこで適合性テストに合格してはじめて有効になり、コパイロットはそれをデジタルスレッドサーバー経由で使用します。

MCP ゲートウェイに外部サーバーとして接続すると、コネクタツール（mes_ · scm_ · sched_ · erp_ · plm_ · qm_ · cmms_ · tool_ · wms_ · lims_ · ehs_ で始まるもの）は オンにできません — これらのツールはデジタルスレッドだけが中継します。
旧版でコパイロットに登録していた外部コネクタがあった場合、再リリース(2026-10-20) でその記録は削除されます。連携マップで登録し直し、認証値を再入力してください → デジタルスレッド

URL を受け取るツール — 内部アドレスは拒否します

文書理解とビジョンのツールはファイルではなく URL を受け取ります。その URL は AI が生成した文字列なので、無制限に受け付けると、AI がコンテナ内からしか到達できない場所を代わりに読んでしまう可能性があります。そのため受け口でブロックします。

http · https のみ受け付けます。
アドレスがループバック · プライベートネットワーク（10/8 · 172.16/12 · 192.168/16） · リンクローカル（クラウドメタデータを含む） に解決される場合は拒否します。リダイレクトも 1 ホップごとに再検査します。
サイズ上限 — 文書 200 MiB、写真 32 MiB。

拒否されると、ツールが ok: false と refused to fetch … の理由を返します。

社内ファイルサーバーの URL は «許可リストに記載しないと» 読めません

http://192.168.x.x/… のような社内アドレスにある文書・写真は既定で拒否されます。開放するホストを /etc/kopens/plantpulse-ai.env の FETCH_ALLOWED_HOSTS（カンマ区切りで複数、既定は空）に記載すると、compose が文書理解とビジョンの両方に渡します（2026.10 再リリースから）。

URL のホスト名と完全に一致する必要があります（大文字小文字は無視）。files.example.local:8080 のようにポートを付けると、そのポートのみ許可します。IP で呼ぶサーバーは IP をそのまま記載します。ワイルドカード · レンジはありません。
許可したホストでも http · https とサイズ上限はそのままで、リダイレクトで他の内部アドレスに移った場合はそこで拒否されます。
記載後、bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api で両サービスを作り直します。

→ 環境変数設定

命名規則

バックエンドのツール名は snake_case です（vision_read_meter）。接頭辞は MCP ゲートウェイが付けるため、サーバー文書で見た名前（read_meter）とチャットで呼ぶ名前（vision_read_meter）が異なる場合があります。

二つのサーバーが同じ公開名を出すと 先に登録された方が勝ち、後のものは公開されません（ツール 画面に衝突として表示）。後のサーバーの接頭辞を変えて解消します。

🔴 ツール一覧を手で書き写さないでください。 インストール状態（何がオンか）の正本は ゲートウェイ DB で、画面は AI 管理コンソール › MCP ゲートウェイ › ツール、全件はゲートウェイ REST GET /api/v1/tools です。ゲートウェイは起動時と 5 分ごとに各サーバーのツール一覧を読み直し、 サーバー 画面の 再検出 でその場で読み直させることもできます。

逆方向 — コパイロットも MCP サーバーです

ここまではコパイロットがツールを «使う» 話でした。逆に他の AI エージェントがコパイロットをツールとして使うこともできます。コパイロットが自身の機能を MCP として提供しているからです。

項目	値
エンドポイント	`POST /mcp`（末尾スラッシュ `/mcp/` も受け付けます）
プロトコル	JSON-RPC 2.0
認証	`/api/v1` と同じです — `X-API-Key` のみ（2026.10 再リリース 6 からログインセッションは 403）

ツール	機能
`ask_plant`	自然言語の質問 → 回答。必要な照会ツールはコパイロットが自動で選びます、根拠も併せて載ります。呼び出した API キーの主体（そのキーの発行を受けた人）の権限で問い合わせ、`sessionId` を空にするとその主体の所有で新しい会話を開きます
`list_plant_tools`	コパイロットが «今» 到達できる照会ツールの一覧
`daily_tasks`	朝のカード（KST 基準）

なぜ 3 つだけなのか — 読み取りのみを公開します

変更を伴うツールには人が承認する手続きが付いていますが、MCP で呼ぶ側はその手続きを知りません。そのため照会のみを公開します。

3 つは /api/v1 と同じ機能で、同じ実装に委譲します — 同じ能力を 2 つのプロトコルで提供しつつコードは 1 組です。2 組になると片方しか修正されません。

末尾スラッシュは両方受け付けます

/mcp と /mcp/ のどちらも動作します。クライアントによってどちらを呼ぶかが異なり、その 1 文字のせいで毎回の呼び出しが 307 で弾かれることが実際にありました。当社を呼ぶ側はその落とし穴を踏みません。

最初にオンにしておくツール — ゲートウェイポリシー​

プラットフォーム統合 MCP — 22 個​

時系列インサイト — insight_ 39 個​

RAG — rag_ 2 個​

文書理解 — document_ 2 個​

ビジョン — vision_ 5 個​

デジタルスレッド — thread_ 4〜9 個​

エンジニアリング計算 — eng_ 4 個​

外部システムコネクタはここでは接続しません​

URL を受け取るツール — 内部アドレスは拒否します​

命名規則​

逆方向 — コパイロットも MCP サーバーです​

関連文書​