---
title: 利用可能なMCPツール一覧
description: ThingsConnectのMCPサーバが提供するツールのパラメータ・レスポンス仕様
createdAt: 2026-06-17
lastModified: 2026-10-15
sidebar:
  label: 利用可能なツール一覧
---

ThingsConnect のクラウド（MCPサーバ）が提供するツールの一覧です（全 58 種類）。接続方法は[MCPサーバのセットアップ](/docs/mcp/setup)を参照してください。

共通のルールです。

- **パラメータ名は snake_case**（`edge_pc_id` / `device_id` など）。レスポンスの JSON はツールによって snake_case と camelCase が混在します（下記の各節に実際の形を記載しています）。
- **参照できる範囲は接続トークンの組織（テナント）内だけ**です。他組織のエッジPC・デバイスを ID で指定しても「見つからない」として扱われます。
- **操作系のツールは「MCP（操作）」スコープを持つトークンでだけ使えます。** 持たないトークンでは一覧にも出ません。対象は `update_edge_pc_note` / `update_edge_pc_attributes` / `add_camera_device` / `update_device` / `remove_device` / `start_rtmp_stream` / `stop_rtmp_stream` / `create_dashboard` / `update_dashboard` / `delete_dashboard` / `add_widget` / `remove_widget` / `create_query` / `update_query` / `delete_query` / `onvif_probe_camera` / `onvif_register_camera` / `onvif_ptz_control` / `onvif_set_imaging` / `onvif_reboot_camera` / `protect_photo` / `capture` / `run_capture_job` / `protect_recording` / `unprotect_recording` / `update_camera_storage_settings` の 26 個です。スコープの選び方は[MCPサーバのセットアップ](/docs/mcp/setup)を参照してください。
- **パスワード・ストリームキー・エッジPC の認証情報は返しません。** レスポンスでは `***` に伏せ、ツールの呼び出し記録にも伏せたまま残します。
- **組織全体で MCP を無効にしている場合は、どのツールも使えません**（接続時に `403` が返ります）。設定は管理ダッシュボードの「組織設定」→「API・MCP」の「MCP サーバー」です。
- 画像を返すツール（`get_device_snapshot` / インライン指定の `capture_device_image` / `get_snapshot` / `compare` / `capture`）以外は、**すべて JSON 文字列をテキストとして返します**。

:::note
  アクチュエータ（リレー等）の制御ツールはありません。機器そのものを動かせるのは ONVIF カメラの PTZ（`onvif_ptz_control` と撮影の `capture`・`run_capture_job`）だけで、ほかは**参照と設定**です。今後の予定は[概要](/docs/overview)と[ロードマップ](/docs/roadmap)を参照してください。
:::

## ツール一覧

### エッジPC

| ツール                | パラメータ           | 説明                                                       |
| --------------------- | -------------------- | ---------------------------------------------------------- |
| `list_edge_pcs`       | なし                 | 組織内のエッジPC一覧                                       |
| `get_edge_pc_info`    | `edge_pc_id`         | エッジPCの情報とシステム状態（LAN の IP・MAC アドレス、有線か Wi-Fi かを含む）。認証情報は `***` に伏せて返す |
| `update_edge_pc_note` | `edge_pc_id`, `note` | エッジPCのメモを書き換える（全文を置き換え。空文字で消去） |
| `update_edge_pc_attributes` | `edge_pc_id`, `attributes` | エッジPCの[管理項目](/docs/guides/organization#管理項目)の値を変更する（下記「管理項目」参照） |
| `list_custom_fields` | `target?` | 組織で作った[管理項目](/docs/guides/organization#管理項目)の一覧（項目名・種類・選択肢）。`target` は `edge_pc` か `device` |
| `list_notifications` | `status?` | [通知](/docs/guides/notifications)の一覧（`open` が未解消で既定、`resolved` が解消済み）。`type` が `condition` の通知は原因が消えると自動で閉じ、`event` は画面で確認済みにして閉じる |

### デバイス（共通）

| ツール               | パラメータ                                                                                   | 説明                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `list_devices`       | `edge_pc_id`                                                                                 | 指定エッジPCのカメラとセンサの一覧（AI アプリは含まない）                                  |
| `list_local_cameras` | `edge_pc_id`                                                                                 | エッジPCに物理接続された USB / CSI カメラを検出する                                        |
| `add_camera_device`  | `edge_pc_id`, `name`, `note?`, `manufacturer?`, `model?`, `serial_number?`, `camera_kind?`, ソース欄, `width?`, `height?`, `fps?`, `audio?` | カメラを登録する（下記「カメラ種別とソース欄」参照）。`audio` の既定は `false`（音声なし） |
| `update_device`      | `device_id`, `name?`, `note?`, `manufacturer?`, `model?`, `serial_number?`, `mac_address?`, `attributes?`, ソース欄, `width?`, `height?`, `fps?`, `audio?` | 名前・メモ・機器情報・管理項目・映像ソース・解像度・音声を変更する（名前・メモ・機器情報・管理項目は全種別、それ以外はカメラのみ）。機器情報は空文字で消去 |
| `remove_device`      | `edge_pc_id`, `device_id`                                                                    | カメラ・センサの登録を解除する（AI アプリは管理ダッシュボードの AI アプリの画面から消す）  |

#### カメラ種別とソース欄

`camera_kind` によって使うソース欄が変わります。省略時は `rtsp` です。

| `camera_kind` | ソース欄       | 例                                                       |
| ------------- | -------------- | -------------------------------------------------------- |
| `rtsp`        | `rtsp_url`     | `rtsp://192.168.1.100:554/stream1`                       |
| `http`        | `source_url`   | `http://192.168.1.100/video.mjpg`（HLS の `.m3u8` も可） |
| `usb`         | `video_device` | `/dev/v4l/by-id/usb-...-video-index0`                    |
| `csi`         | `camera_index` | `0`                                                      |

`usb` / `csi` は**先に `list_local_cameras` を呼んで値を取得**してください（デバイスパスは推測できません）。`width` / `height` / `fps` は取り込み解像度で、`rtsp` では使いません（カメラ本体の設定に従います）。**カメラ種別は登録後に変更できません**（別の機器になるため、削除して登録し直します）。

:::warning
センサと AI アプリを**追加**するツールはありません（`add_camera_device` はカメラ専用です）。管理ダッシュボードから追加してください（[センサの設定](/docs/guides/sensors) / [AI アプリを使う](/docs/guides/ai-apps)）。

`update_device` で変更できるのは**名前・メモ・機器情報・管理項目（全種別）と、カメラの映像ソース・解像度・音声**だけです。録画（NVR）の設定、センサの履歴保存は MCP からは変更できません。

:::

### カメラの映像・画像

| ツール                 | パラメータ                                           | 説明                                                                   |
| ---------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| `get_device_snapshot`  | `edge_pc_id`, `device_id`                            | 低解像度（横 320px）の最新フレーム。画像として返る                     |
| `capture_device_image` | `edge_pc_id`, `device_id`, `inline?`, `max_width?`   | 高解像度の静止画を撮る。既定は署名付き URL                             |
| `start_rtmp_stream`    | `device_id`, `rtmp_url`, `stream_key`, `resolution?` | YouTube Live などへの外部配信を開始する。`rtmp_url` は `rtmp://` か `rtmps://` で始まる URL |
| `stop_rtmp_stream`     | `device_id`                                          | 外部配信を停止する                                                     |
| `get_rtmp_status`      | `device_id`                                          | 外部配信の状態と、載せている編集（テロップ・モザイク）の件数を取得する |

### センサ

| ツール               | パラメータ                             | 説明                                     |
| -------------------- | -------------------------------------- | ---------------------------------------- |
| `get_sensor_reading` | `device_id`                            | センサの現在値（値・単位・接続状態）     |
| `get_sensor_history` | `device_id`, `from?`, `to?`, `bucket?` | センサの履歴を時間バケットで集計して取得 |

### AI アプリ

カメラに追加した [AI アプリ](/docs/guides/ai-apps)は、機器ではないのでデバイスのツールには出ません。1 件（**インスタンス**）が 1 台のカメラの映像を読み、結果を記録します。

| ツール                   | パラメータ                                                                | 説明                                                                         |
| ------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `list_ai_app_instances`  | `edge_pc_id?`, `ai_app_id?`                                               | カメラに追加した AI アプリの一覧（入力元のカメラ・記録する metric_key 付き） |
| `get_ai_app_instance`    | `instance_id`                                                             | 最新の結果（検出数・最上位ラベル、メーター読み取りなら読んだ値）             |
| `get_ai_app_history`     | `instance_id`, `from?`, `to?`, `bucket?`                                  | 結果の履歴を時間バケットで集計して取得                                       |
| `list_ai_events`         | `instance_id?`, `ai_app_id?`, `event_type?`, `plate?`, `since?`, `limit?` | 在/不在ルールの切り替わりとナンバーの読み取りを新しい順に取得                |

### ダッシュボード

| ツール             | パラメータ                                          | 説明                                                        |
| ------------------ | --------------------------------------------------- | ----------------------------------------------------------- |
| `list_dashboards`  | なし                                                | ダッシュボード一覧（id / 名前 / ウィジェット数）            |
| `get_dashboard`    | `dashboard_id`                                      | ウィジェットを含むダッシュボードの取得                      |
| `create_dashboard` | `name`, `description?`, `widgets?`                  | ダッシュボードを作成（ウィジェットごと一括作成も可）        |
| `update_dashboard` | `dashboard_id`, `name?`, `description?`, `widgets?` | 名前・説明の変更、またはウィジェット全体の置き換え          |
| `delete_dashboard` | `dashboard_id`                                      | ダッシュボードをゴミ箱へ移動（30 日以内なら画面から復元可） |
| `add_widget`       | `dashboard_id`, `widget`                            | ウィジェットを 1 つ追加（既存は保持）                       |
| `remove_widget`    | `dashboard_id`, `widget_id`                         | ウィジェットを 1 つ削除                                     |
| `list_metrics`     | なし                                                | ウィジェットに指定できる metric_key とセンサの一覧          |

### クエリ（SQL）

| ツール                  | パラメータ                                   | 説明                                                        |
| ----------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| `describe_query_schema` | なし                                         | `run_query` で使える表・列の定義                            |
| `run_query`             | `sql`                                        | 読み取り専用 SQL（`SELECT` / `WITH` のみ）を実行            |
| `list_queries`          | なし                                         | 保存クエリの一覧                                            |
| `get_query`             | `query_id`                                   | 保存クエリを SQL 込みで取得                                 |
| `create_query`          | `name`, `sql`, `chart_config?`               | クエリを保存                                                |
| `update_query`          | `query_id`, `name?`, `sql?`, `chart_config?` | 保存クエリを更新（`chart_config: null` でグラフ設定を消去） |
| `delete_query`          | `query_id`                                   | 保存クエリをゴミ箱へ移動（30 日以内なら画面から復元可）     |

### ONVIF カメラ

| ツール                   | パラメータ                                                                                            | 説明                                                                                                                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onvif_discover_cameras` | `edge_pc_id`                                                                                          | エッジPC から LAN 上の ONVIF カメラを探す                                                                                                                                                                  |
| `onvif_probe_camera`     | `edge_pc_id`, `host`, `port?`, `username?`, `password?`                                               | 機器情報とメディアプロファイル（RTSP URL 込み）を取得                                                                                                                                                      |
| `onvif_get_device_info`  | `edge_pc_id`, `device_id`                                                                             | 登録済みカメラの機器情報                                                                                                                                                                                   |
| `onvif_get_ptz_status`   | `edge_pc_id`, `device_id`                                                                             | PTZ の現在位置（左右・上下は -1〜1、ズームは 0〜1）と動作中かどうか                                                                                                                                        |
| `onvif_register_camera`  | `edge_pc_id`, `name`, `host`, `rtsp_url`, `port?`, `username?`, `password?`, `profile_token?`, `manufacturer?`, `model?`, `serial_number?` | 探索したカメラをデバイスとして登録。`onvif_probe_camera` の `deviceInfo` を機器情報に渡せます |
| `onvif_ptz_control`      | `edge_pc_id`, `device_id`, `action`, `pan?`, `tilt?`, `zoom?`, `preset_token?`                        | パン・チルト・ズーム・プリセット移動・停止。`action` は `relative`（現在位置から決まった量だけ動かす） / `absolute`（位置を指定して動かす） / `continuous`（停止するまで動かし続ける） / `stop` / `preset` |
| `onvif_set_imaging`      | `edge_pc_id`, `device_id`, `brightness?`, `color_saturation?`, `sharpness?`, `contrast?`              | 明るさ・彩度・シャープネス・コントラストの変更                                                                                                                                                             |
| `onvif_reboot_camera`    | `edge_pc_id`, `device_id`                                                                             | カメラを再起動                                                                                                                                                                                             |

### 撮影

[撮影](/docs/guides/capture)の撮影プリセットの向きと、メディアビューワーに保存した写真を扱います。**場所は向きの名前（現場の呼称。「1 工区」「調整池」など）で指定します。** 向きの無い撮影プリセットは、プリセット名がそのまま場所の名前になります。撮影ジョブ・撮影プリセット・外部送信先の登録は管理ダッシュボードの「撮影」で行い、ここでは参照・撮影と写真の保護を扱います。

| ツール         | パラメータ                                                          | 説明                                                                                                                                      |
| -------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `list_presets` | `device_id?`                                                        | 撮影プリセットと、それぞれの向き（名前・撮る順・ズームの覚え書き・外しているか・最終撮影時刻）の一覧。`device_id` を省くと組織内のすべて |
| `get_snapshot` | `preset`, `preset_name?`, `datetime?`, `device_id?`, `full?`        | その場所の、指定時刻に最も近い 1 枚。`datetime` を省くと最新                                                                              |
| `compare`      | `preset`, `preset_name?`, `date_a`, `date_b`, `device_id?`, `full?` | 同じ場所の 2 時点の写真を並べて返す                                                                                                       |
| `capture`      | `preset`, `preset_name?`, `zoom?`, `device_id?`                     | 向きを 1 つその場で撮り、メディアビューワーにも保存する。撮影中のジョブには割り込み、ジョブは後で残りの向きを撮る                           |
| `protect_photo` | `preset`, `preset_name?`, `datetime`, `protect?`, `device_id?`     | その場所の、指定時刻に最も近い 1 枚を保護する。`protect` に `false` を渡すと解除する                                                     |

- **`preset` には向きの名前を渡します**（パラメータ名は変えていません）。同じ名前の向きが複数の撮影プリセットにあるときは `preset_name`（撮影プリセットの名前）を、複数のカメラにあるときは `device_id` を添えます。
- **名前は表記ゆれを吸収します。** 完全一致 → 前方一致 → 部分一致の順に探し、全角・半角と空白の違いは無視します。複数の場所が該当したときは候補を返すので、`preset_name` か `device_id` を添えて呼び直してください。
- **対象はメディアビューワーに保存したすべての撮影の写真です**（スケジュール・手動・外部 API・エッジ内・その場で撮影のどれで撮ったかを問いません）。
- **画像は既定で横 1280px 程度に縮小したものを返します。** 原寸（4K）が要るときだけ `full` に `true` を渡してください。
- **写真は撮ったエッジPC から読み出します。** エッジPC がオフラインの間は「画像を取得できませんでした（エッジPC がオフラインの可能性があります）。」を返します。
- **`compare` は写真を並べて返すだけで、差分は検出しません。** 何が変わったかの判断は読み手（AI と人）に委ねる設計です。
- **`protect_photo` で保護した写真は、エッジPC の保存先が満杯になっても、保護していない録画と写真を消し切るまで残ります。** エッジPC がオフラインのときは失敗します。`get_snapshot` と `compare` は、保護した写真に「保護中」と添えて返します。
- **`capture` は向きが登録された場所だけ撮れます**（向きの無い撮影プリセットは、撮影ジョブの `run_capture_job` で撮ります）。外部送信先へは送りません。`zoom` は 0（引き）〜1（寄り）で、向きに登録されたズームを一時的に上書きします。

撮影ジョブを扱うツールです。

| ツール                    | パラメータ                                              | 説明                                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_capture_jobs`       | `device_id?`                                            | 撮影ジョブの一覧（カメラと撮影プリセットの ID・撮るもの（`kind` が `photo` か `clip`、録画は `clipSeconds` 秒）・外部送信先の名前・メディアビューワーに保存するか・スケジュール（cron 式を含む）・許可しているトリガー）。外部送信先の認証情報は含まない             |
| `list_capture_deliveries` | `job_id?`, `run_id?`, `device_id?`, `status?`, `limit?` | 撮影ログ（写真 1 枚ごとの撮影と外部送信の結果）を新しい順に返す。`status` は `pending` / `sent` / `failed` / `abandoned` / `captured`（保存のみ）、`limit` は 1〜200（既定 50） |
| `run_capture_job`         | `job_id`, `payload?`                                    | いま 1 回撮影する（撮影プリセットの向きを順に撮り、ジョブの出力どおり保存・送信する）。`payload` は外部送信先へ一緒に渡す JSON（4KB まで）。実行 ID（`run_id`）を返す            |

- **`run_capture_job` の結果は、返った `run_id` を `list_capture_deliveries` に渡して確かめます。** 撮影は依頼を受け付けた後にエッジPC で進むので、向きの多いジョブは結果が揃うまで時間がかかります。
- **`run_capture_job` は無効にしたジョブでは失敗します。** 外部 API からの起動を許可していないジョブでも実行できます（MCP の操作スコープで行う手動実行として扱い、撮影ログのトリガーは「手動」になります）。

### 録画

カメラの録画のうち残したい区間を自動削除から保護するほか、録画と静止画の保存サイズを変えられます（→ [録画を保護する](/docs/guides/recording#録画を保護する)、[保存サイズを選ぶ](/docs/guides/recording#保存サイズを選ぶ)）。

| ツール                      | パラメータ                | 説明                                                                                                                                         |
| --------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_protected_recordings` | `device_id` | 保護した区間の一覧を返す（`id` / `fromAt` / `toAt` / `note` / `createdAt`） |
| `protect_recording` | `device_id`, `from`, `to`, `note?` | 区間（最大 7 日）を自動削除から保護する。`from` / `to` は ISO 8601（タイムゾーン付き） |
| `unprotect_recording` | `device_id`, `range_id` | 保護を解除する。`range_id` は `list_protected_recordings` の `id` |
| `get_camera_storage_settings` | `device_id` | 録画と静止画の保存サイズ（`maxWidth`。`0` はパススルー）と判断材料をまとめて返す。判断材料は、カメラが実際に出している映像（コーデック・解像度・fps・ビットレート）、録画に書いているビットレートと 1 日あたりの容量、エッジPC の CPU の型番・コア数・使用率（エッジPC がオフラインのときは `null`）、録画先の空き容量 |
| `update_camera_storage_settings` | `device_id`, `recording_max_width?`, `still_max_width?`, `retention_days?` | 録画の幅の上限・静止画の幅の上限（どちらも `0` はパススルー、それ以外は 320〜3840px）と録画の保持日数を変える |

- **保護はエッジPC に対して行うので、エッジPC がオフラインのときは失敗します。** 1 台のカメラで保護できるのは 200 区間までです。
- **保護してもエッジPC の外には残りません。** エッジPC の故障・撤去では失われ、保存先が満杯になれば保護した録画も古い順に消えます。
- **「録画の容量を減らしたい」と頼むと、AI は `get_camera_storage_settings` の値から推奨を出せます。** 録画の縮小はエッジPC の CPU を常時使う（Raspberry Pi 5 で 1 台あたり 1 コアの約 6 割）ので、CPU の余裕が無ければ縮小を勧めません。カメラのビットレートが既に低いと縮小しても容量はあまり減らないため、カメラ側の設定を変える案も出します。

---

## よく使うツールの詳細

### `list_edge_pcs`

組織内のエッジPC一覧を返します。**ほとんどの操作は `edge_pc_id` を必要とするため、多くの場合これが起点**になります。

**パラメータ**: なし

**レスポンス例**:

```json
[
  {
    "id": "edge-pc-test-001",
    "organizationId": "org-test-001",
    "name": "拠点A（テストエッジPC）",
    "note": "1F 東側の制御盤内",
    "attributes": { "設置日": "2024-04-01", "資産番号": "A-0012" },
    "thingName": "edge-device-01",
    "baseUrl": "https://edge-01.example.com",
    "createdAt": "2026-06-17T10:00:00.000Z",
    "updatedAt": "2026-06-17T10:00:00.000Z"
  }
]
```

`thingName` が画面でいう **EDGE ID**、`baseUrl` が **Base URL** です。`note` は画面の **メモ**（未設定なら `null`）。`attributes` は[管理項目](/docs/guides/organization#管理項目)の値で、キーは項目名です（未入力の項目は含みません）。

### 管理項目

`list_edge_pcs` と `list_devices` は、組織で作った[管理項目](/docs/guides/organization#管理項目)の値を `attributes` に項目名をキーにして返します。値を変えるときは、エッジPC は `update_edge_pc_attributes`、デバイスは `update_device` の `attributes` に、同じく項目名をキーにして渡します。

```json
{ "edge_pc_id": "edge-pc-test-001", "attributes": { "設置日": "2024-04-01", "資産番号": null } }
```

渡した項目だけが変わり、`null` を渡した項目は値が消えます。日付は `YYYY-MM-DD`、選択肢の項目は定義した値のどれかを渡します。項目名と種類は `list_custom_fields` で確かめられます。項目の作成・削除はダッシュボードの組織設定から行います。

### `list_devices`

指定したエッジPCに登録されているカメラとセンサを返します。カメラに追加した AI アプリは含みません（[`list_ai_app_instances`](#list_ai_app_instances) で取得します）。

**パラメータ**:

| パラメータ   | 型     | 必須 | 説明                                  |
| ------------ | ------ | :--: | ------------------------------------- |
| `edge_pc_id` | string |  ✓   | エッジPC ID（`list_edge_pcs` で確認） |

**レスポンス例**:

```json
[
  {
    "id": "edge-device-01__8f14e45f-ceea-467a-9f3b-1b2c3d4e5f60",
    "edgePcId": "edge-pc-test-001",
    "edgePcName": "拠点A（テストエッジPC）",
    "type": "camera",
    "name": "工場エントランス",
    "note": "1F 東側の天井。脚立が必要",
    "attributes": { "購入日": "2023-10-01" },
    "cameraKind": "rtsp",
    "rtspUrl": "rtsp://192.168.1.100:554/stream1",
    "createdAt": "2026-06-17T10:05:00.000Z"
  }
]
```

`type` は `camera` か `sensor` です。`note` は画面の **メモ**（未設定なら `null`）。カメラは `cameraKind`（`rtsp` / `usb` / `csi` / `http`）に応じて `rtspUrl` / `sourceUrl` / `videoDevice` / `cameraIndex` のいずれかが埋まります。URL に含まれるパスワードは `rtsp://admin:***@192.168.1.100:554/stream1` のように伏せて返します。伏せたままの URL を `update_device` に渡すとエラーになるので、映像ソースを変えるときは実際のパスワードを入れて渡してください。

### `list_local_cameras`

エッジPCに**物理接続された** USB / Web カメラ・Raspberry Pi のカメラモジュールを検出します。`add_camera_device` で `camera_kind` に `usb` / `csi` を使う前に呼び、`id` をそのまま `video_device` / `camera_index` に渡してください（デバイスパスは推測できません）。

**パラメータ**:

| パラメータ   | 型     | 必須 | 説明        |
| ------------ | ------ | :--: | ----------- |
| `edge_pc_id` | string |  ✓   | エッジPC ID |

**レスポンス例**:

```json
{
  "cameras": [
    {
      "kind": "usb",
      "id": "/dev/v4l/by-id/usb-046d_HD_Pro_Webcam_C920_9A8B-video-index0",
      "name": "HD Pro Webcam C920",
      "devicePath": "/dev/video0",
      "modes": [{ "format": "mjpeg", "width": 1280, "height": 720, "fps": [30] }]
    }
  ],
  "tools": { "v4l2Ctl": true, "rpicamHello": false }
}
```

`id` は再起動や挿し直しでも変わらないパスです（`devicePath` は表示用で、認識順に振られるため登録には使いません）。`modes` は `width` / `height` / `fps` に指定できる組み合わせです。

**エッジPCがオフラインでも検出ツールが未導入でもエラーにはならず、空の一覧を返します。** `tools.v4l2Ctl`（USB）・`tools.rpicamHello`（CSI）が `false` なら、その種別は検出できません。

### `get_device_snapshot`

最新フレームを**横 320px の低解像度**（アスペクト比は維持）で返します。生存確認やざっと様子を見る用途向けです。画像コンテンツとして返るため、AI エージェントはそのまま内容を読み取れます。

**パラメータ**: `edge_pc_id`, `device_id`（ともに必須）

保存・外部サービスへの受け渡しなど**高解像度が必要な場合は `capture_device_image`** を使ってください。

### `capture_device_image`

その場で高解像度の静止画を撮ります。

**パラメータ**:

| パラメータ   | 型      | 必須 | 説明                                           |
| ------------ | ------- | :--: | ---------------------------------------------- |
| `edge_pc_id` | string  |  ✓   | エッジPC ID                                    |
| `device_id`  | string  |  ✓   | カメラのデバイス ID                            |
| `inline`     | boolean |  —   | `true` で画像を直接返す（既定 `false`）        |
| `max_width`  | number  |  —   | `inline=true` のときの最大幅 px（既定 `1920`） |

既定（`inline` 省略時）は、**短時間だけ有効な署名付き URL** を返します。認証ヘッダなしで取得できるので、コードで取得して外部サービス（Google Drive・kintone など）へアップロードする用途に向いています。

```json
{
  "image_url": "https://edge-01.example.com/capture/edge-device-01__8f14e45f-ceea-467a-9f3b-1b2c3d4e5f60?...",
  "expires_at": "2026-06-17T10:35:00.000Z",
  "resolution": "source"
}
```

`inline: true` を指定すると、URL ではなく画像そのものが返ります（`max_width` に縮小）。コード実行のできないクライアントではこちらを使ってください。

### `get_sensor_reading`

センサの現在値を返します。値は単位を持たない数値で、単位・表示名は metric_key の定義から付与されます。

**パラメータ**: `device_id`（必須）

**レスポンス例**:

```json
{
  "device_id": "edge-device-01__c9b1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "name": "電子天秤 001",
  "edge_pc": "拠点A（テストエッジPC）",
  "metric_key": "weight",
  "display_name": "重量",
  "unit": "kg",
  "value": 12.34,
  "connected": true,
  "edge_offline": false,
  "line_stale": false,
  "updated_at": "2026-06-17T10:30:05.000Z",
  "record_history": true
}
```

`edge_offline` が `true` のときは、エッジPC がオフラインのため接続状態が分かりません（`connected` は `false`、`value` は最後に届いた値です）。

`line_stale` は、電文のセンサで設定した時間電文が届いていないとき `true` です（→ [電文が届かないときに知らせる](/docs/guides/sensors#電文が届かないときに知らせる)）。

センサ以外のデバイス ID を渡すとエラーになります。AI アプリの最新の結果は [`get_ai_app_instance`](#get_ai_app_instance) で取得します。

### `get_sensor_history`

センサの履歴を時間バケットで集計して返します。

**パラメータ**:

| パラメータ  | 型     | 必須 | 説明                                                                           |
| ----------- | ------ | :--: | ------------------------------------------------------------------------------ |
| `device_id` | string |  ✓   | センサのデバイス ID                                                            |
| `from`      | string |  —   | ISO 8601 の開始時刻（既定: 1 時間前）                                          |
| `to`        | string |  —   | ISO 8601 の終了時刻（既定: 現在）                                              |
| `bucket`    | string |  —   | 集計幅。`10 seconds` / `1 minute` / `5 minutes` / `1 hour`（既定: `1 minute`） |

**レスポンス例**:

```json
{
  "device_id": "edge-device-01__c9b1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "bucket": "1 minute",
  "from": "2026-06-17T09:30:00.000Z",
  "to": "2026-06-17T10:30:00.000Z",
  "points": [
    { "ts": "2026-06-17T09:30:00.000Z", "metric_key": "weight", "value": 12.1, "min": 12.0, "max": 12.3, "count": 12 }
  ]
}
```

:::warning
履歴はデバイスの**履歴保存が有効な場合のみ**蓄積されます。また、履歴は **7 日**より古いものが自動削除されます。

AI アプリの結果の履歴は [`get_ai_app_history`](#get_ai_app_history) で取得します。

:::

### `list_ai_app_instances`

カメラに追加した AI アプリを新しい順に返します。

**パラメータ**:

| パラメータ   | 型     | 必須 | 説明                                                                       |
| ------------ | ------ | :--: | -------------------------------------------------------------------------- |
| `edge_pc_id` | string |  —   | このエッジPC のものだけに絞る                                              |
| `ai_app_id`  | string |  —   | AI アプリの ID（`license-plate` / `object-detection` など）で絞る          |

**レスポンス例**:

```json
[
  {
    "instance_id": "edge-device-01__2b7e1516-28ae-4d2a-a6d2-15b2c3d4e5f6",
    "ai_app_id": "object-detection",
    "name": "入口の人数",
    "note": null,
    "edge_pc_id": "edge-pc-test-001",
    "edge_pc": "拠点A（テストエッジPC）",
    "camera_id": "edge-device-01__8f14e45f-ceea-467a-9f3b-1b2c3d4e5f60",
    "camera": "工場エントランス",
    "metric_keys": ["object_count"],
    "created_at": "2026-09-30T02:41:28.009Z"
  }
]
```

`camera_id` は映像を読むカメラのデバイス ID です。`metric_keys` は結果を記録する計測項目で、`run_query` やダッシュボードのウィジェットにも使えます。

### `get_ai_app_instance`

AI アプリのインスタンス 1 件と、最新の結果を返します。

**パラメータ**: `instance_id`（必須。`list_ai_app_instances` で確認）

**レスポンス例**:

```json
{
  "instance_id": "edge-device-01__2b7e1516-28ae-4d2a-a6d2-15b2c3d4e5f6",
  "ai_app_id": "object-detection",
  "name": "入口の人数",
  "camera": "工場エントランス",
  "metric_keys": ["object_count"],
  "connected": true,
  "edge_offline": false,
  "last_error": null,
  "latest": { "count": 3, "top_label": "person", "top_confidence": 0.91, "value": null, "unit": null, "updated_at": null }
}
```

推論のアプリは `count`・`top_label`・`top_confidence`、メーター読み取りは `value`・`unit`・`updated_at` が入り、使わない項目は `null` です。まだ結果が無ければ `latest` が `null` になります。`edge_offline` の意味は [`get_sensor_reading`](#get_sensor_reading) と同じです。

### `get_ai_app_history`

AI アプリの結果の履歴を時間バケットで集計して返します。パラメータは `instance_id`（必須）と、[`get_sensor_history`](#get_sensor_history) と同じ `from` / `to` / `bucket` です。レスポンスも同じ形で、`device_id` の代わりに `instance_id` が入ります。

### `list_ai_events`

[AI アプリ](/docs/guides/ai-apps)のイベントを新しい順に返します。在/不在ルールの切り替わり（`presenceStart` / `presenceEnd`）と、ナンバーの読み取り（`plateRead`）です。イベントは **30 日間**残ります。

**パラメータ**:

| パラメータ   | 型     | 必須 | 説明                                                                          |
| ------------ | ------ | :--: | ----------------------------------------------------------------------------- |
| `instance_id` | string |  △   | AI アプリのインスタンス ID。`instance_id` か `ai_app_id` のどちらかを指定します |
| `ai_app_id`  | string |  △   | AI アプリの ID（`license-plate` / `object-detection` など）。そのアプリの全インスタンスが対象です |
| `event_type` | string |  —   | `presenceStart` / `presenceEnd` / `plateRead` で絞り込む                     |
| `plate`      | string |  —   | 番号の部分一致（`plateRead` のみ。1〜40 文字）                               |
| `since`      | string |  —   | ISO 8601。この時刻以降のイベントだけを返す                                   |
| `limit`      | number |  —   | 取得件数（1〜200、既定 `50`）                                                 |

**レスポンス例**:

```json
{
  "total": 1,
  "events": [
    {
      "id": "…",
      "ts": "2026-09-28T10:30:01.000Z",
      "instanceId": "edge-device-01__8f14e45f-ceea-467a-9f3b-1b2c3d4e5f60",
      "instanceName": "ゲートのナンバー読み取り",
      "edgePcName": "第1工場",
      "eventType": "plateRead",
      "ruleId": null,
      "detail": { "plate": "品川300あ1234", "confidence": 0.98, "bbox": { "x": 0.41, "y": 0.62, "width": 0.12, "height": 0.06 } },
      "hasPhoto": true
    }
  ]
}
```

:::warning
画像そのものは返しません。`hasPhoto` で、エッジPC の[メディアビューワー](/docs/guides/photos)に画像が残っているかだけが分かります。件数や確信度の推移はここには入らないので、[`get_ai_app_history`](#get_ai_app_history) で取得してください。オンデマンドで推論を実行するツールはありません。

:::

### `list_metrics`

ダッシュボードのウィジェットを組む前に、指定できる `metricKey` と `deviceId` / `edgePcId` を調べるためのカタログです。

**パラメータ**: なし

**レスポンス例**:

```json
{
  "metrics": [{ "metricKey": "weight", "displayName": "重量", "unit": "kg" }],
  "devices": [
    {
      "deviceId": "edge-device-01__c9b1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "name": "電子天秤 001",
      "edgePcId": "edge-pc-test-001",
      "edgePcName": "拠点A（テストエッジPC）",
      "metricKeys": ["weight"]
    }
  ]
}
```

### `create_dashboard` / `add_widget`

ウィジェットは **`get_dashboard` の結果と同じ camelCase** で受け渡します（結果をそのまま編集して書き戻せます）。`id` と `layout` は省略でき、自動で補われます。

**ウィジェットの型**:

| `type`         | 内容                           | 参照するもの |
| -------------- | ------------------------------ | ------------ |
| `timeseries`   | 時系列の折れ線                 | `query`      |
| `bar`          | 棒グラフ                       | `query`      |
| `stat`         | 単一数値（KPI）                | `query`      |
| `summaryTable` | センサ × metric のサマリー表   | `query`      |
| `queryTable`   | 保存クエリの結果を表で表示     | `queryId`    |
| `queryChart`   | 保存クエリの結果をグラフで表示 | `queryId`    |

**リクエスト例**:

```json
{
  "name": "拠点A 重量モニタ",
  "widgets": [
    {
      "type": "stat",
      "title": "現在の重量",
      "query": { "metricKey": "weight", "deviceId": "edge-device-01__c9b1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f" }
    },
    { "type": "timeseries", "title": "重量の推移", "query": { "metricKey": "weight" } }
  ]
}
```

`queryTable` / `queryChart` は `query` ではなく `queryId`（`list_queries` / `create_query` で得た保存クエリの ID）を指定します。

### `run_query` / `describe_query_schema`

センサ・AI 推論の履歴に対して、読み取り専用の SQL を直接実行できます。**先に `describe_query_schema` を呼んで表・列を確認してください。**

- 実行できるのは **`SELECT` / `WITH` で始まる単一文だけ**です。
- 自組織の行しか返りません。`tenant_id` の条件を書く必要はありません。
- MCP 経由の結果は **200 行**で打ち切られます。より多くの行が必要な場合は集計するか、管理ダッシュボードの[クエリ](/docs/guides/queries)から CSV で書き出してください。

**レスポンス例**:

```json
{
  "columns": ["device_id", "avg_value"],
  "rows": [{ "device_id": "edge-device-01__c9b1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "avg_value": 12.2 }],
  "rowCount": 1,
  "truncated": false,
  "elapsedMs": 42
}
```

`truncated` が `true` のときは上限で打ち切られています。

---

## エラー

エラー時は、**`isError` を立てたテキスト**が返ります。構造化されたエラーコードは返しません。

主なメッセージです。

| メッセージ                                | 意味                                                               |
| ----------------------------------------- | ------------------------------------------------------------------ |
| `Edge PC not found`                       | `edge_pc_id` が存在しないか、トークンの組織のものではない          |
| `Device not found`                        | `device_id` が存在しないか、トークンの組織のものではない           |
| `Device is not a sensor`                  | センサ用のツールにカメラ等の ID を渡した                           |
| `No frame available` / `Capture failed`   | エッジPCから画像を取得できなかった（オフライン・カメラ未接続など） |
| `Dashboard not found` / `Query not found` | 指定した ID のダッシュボード / 保存クエリが無い                    |
| SQL のエラーメッセージ                    | `run_query` に渡した SQL が不正（`SELECT` 以外、構文エラーなど）   |

メッセージは英語です（`Edge PC not found` など）。

認証に失敗した場合は、ツール呼び出し以前に HTTP `401`（`{"error":"Unauthorized"}`）が返ります。