> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.sprocket.bz/llms.txt
> Use this file to discover all available pages before exploring further.

# AI・外部連携（MCPサーバー・M2M API）

> 外部の AI クライアントから Spumote を操作する MCP サーバーと、システム連携用の M2M API の使い方と制限を説明します。

> この記事は Spumote のソースコードから生成した試験出力です。内容は確認中のため、正式な仕様は担当者に確認してください。

## この機能でできること

Spumote は、外部の AI クライアント（Claude など）から自社の Spumote 組織を操作するための入口を持っています。

* **MCP サーバー**: MCP（Model Context Protocol。AI クライアントが外部サービスの「道具（ツール）」を使うための共通規格）に対応した接続先です。Claude などに Spumote をつなぐと、「先週の売上を集計してグラフにして」「このデータでワークフローの下書きを作って」といった依頼を、AI が Spumote のツールを呼び出して実行します。
* **M2M API（システム連携用 OAuth クライアント）**: 人が操作しない社内システムやバッチから、決めた権限の範囲で Spumote の MCP を使うための認証情報（クライアント ID とシークレット）を発行する仕組みです。

どちらも「AI やシステムは、接続時に許可した範囲（スコープ）と、本人（またはシステム用アカウント）のロールの権限の **両方** を満たす操作しかできない」という二重のガードがかかっています。

## 画面の場所

* MCP サーバーの接続先 URL と接続手順: 管理画面の 設定 › 接続先 にある「AI アシスタント ( MCP )」の節（「エンドポイント」「つなぎ方」）。URL は「読み書き」「読み取り + SELECT 実行 ( 書き込みなし )」「読み取り専用」の 3 種類が表示されます
* MCP サーバーへの接続操作: AI クライアント（Claude など）側のコネクタ設定で、上の URL を登録します
* M2M 用 OAuth クライアント: API（`/v1/oauth-clients`）から発行・一覧・失効します（オーナーのみ）

## MCP サーバーにつなぐ

### 接続の流れ

1. AI クライアントのコネクタ（外部ツール連携）設定に、Spumote の MCP の URL を登録します（claude.ai では 設定 › コネクタ › カスタムコネクタを追加）。
2. 初回接続時にブラウザで Spumote のログイン画面が開き、本人としてログインして接続を許可します（OAuth 2.1。パスワードを AI クライアントに渡さずに、許可した範囲の「通行証（アクセストークン）」だけを渡す方式）。
3. 接続後、AI はまず組織一覧ツールで操作対象の組織を選びます。複数の組織に所属している場合、AI は組織を切り替える前に利用者へ確認するよう指示されています。
4. 以降、利用者が AI に依頼すると、AI が必要なツールを選んで呼び出します。ツールの説明は既定で日本語です。

### 接続先の種類（モード）

同じ MCP サーバーに、できることの範囲が違う 3 種類の入口があります。用途に合わせて URL を使い分けます。

| 入口 | できること | 想定する使い方 |
| - | - | - |
| `/mcp/readonly` | 読み取りのみ。BigQuery のクエリは実行しない（見積もりの dry-run は可） | まずは安全に、データの中身や設定を AI に調べさせたい |
| `/mcp/query` | 読み取り＋ SELECT 専用のクエリ実行（スキャン課金はあるがデータは変えない） | 集計・分析は自由にさせたいが、作成・変更・送信はさせたくない |
| `/mcp` | すべて（作成・更新・削除・実行・送信を含む） | ワークフローの作成や実行まで任せたい |

さらに `/mcp/x/<ツール群>`（例: ワークフローだけ）で、出すツールの分野を絞った入口も作れます。分野は orgs（組織）／data（データ）／files（ファイル）／catalog（データカタログ）／workflows（ワークフローの参照・実行）／workflow-authoring（ワークフローの作成）の 6 種類です。URL の末尾に `?lang=en` を付けるとツールの説明が英語になります。

### 許可する範囲（スコープ）

接続を許可するときのスコープ（8 種類）と、それぞれに必要なロール権限です。本人のロールに権限が無いスコープは、許可しても使えません（詳しくは付録A 権限一覧）。

| スコープ | 必要なロール権限 | 主な用途 |
| - | - | - |
| `mcp:org.read` | `data:read` | 組織の選択・組織情報の取得 |
| `mcp:data.read` | `data:read` | BigQuery の一覧・プレビュー、ファイル接続先一覧、ダッシュボード閲覧 |
| `mcp:cdp.read` | `data:read` ＋ `data:bigquery:execute` | SELECT クエリの実行 |
| `mcp:catalog.read` | `data:bigquery:read` | データカタログの閲覧 |
| `mcp:catalog.write` | `data:bigquery:write` | データカタログの書き込み・承認 |
| `mcp:workflow.read` | `data:read` | ワークフロー・実行履歴の閲覧 |
| `mcp:workflow.write` | `data:write` | ワークフロー等の作成・更新 |
| `mcp:workflow.run` | `data:workflow:manual-execute` | ワークフローの手動実行・再実行 |

## ツール群ごとにできること

### データ操作

* 組織の BigQuery のデータセット・テーブル一覧の取得、テーブルの先頭行のプレビュー（最大 100 行）。
* クエリの見積もり（dry-run。実行せずに構文とスキャン量を確認、課金なし）と、SELECT の実行（結果は既定 100 行・最大 1,000 行）。
* データを変える文（INSERT／UPDATE／DELETE／CREATE など）は **二段階** でしか実行できません。1 回目は実行せず「流れる SQL」と確認用の合言葉（5 分で失効）が返り、AI はその SQL を利用者に見せて承認を得てから 2 回目を呼びます。途中で SQL を書き換えると拒否されます。
* ワークフロー（自動処理）の一覧・定義の参照、下書きの検証、作成・更新・有効化・一時停止・削除、手動実行、実行状況とログの確認、失敗したステップからの再実行、実行中の処理のキャンセル。
* データ到着チェック（アセットセンサー。S3／GCS／SFTP のファイルや BigQuery のパーティションが届いたかを定期的に見に行く仕組み）と、失敗通知の宛先（通知セット）の作成・更新・削除。
* ファイル接続先の一覧、Spumote 管理ストレージ（Spumote が用意する組織専用の保管場所）の接続先作成、接続先の名前・状態の変更や無効化。シークレット（鍵やパスワード）は AI に一切返しません。

### データカタログ

テーブルや列の意味（表示名・説明・タグ・主キー・業務上の型など）を記録した「データカタログ」を読み書きします。AI が書いた内容は「AI の提案（未承認）」として保存され、変更履歴に「MCP から」と残るので、人が管理画面で確認してから承認できます。利用者が内容を明示的に承認した場合だけ、AI が承認まで行えます。

### 分析レポート

AI が作った SELECT とグラフの設定（折れ線・棒・面・円・ファネル・数値・表・日本地図）を「分析レポート」として保存します。SQL は Spumote 側で実行され、結果の行は AI に返りません（返るのは件数・列名・閲覧 URL など）。保存したレポートは組織のメンバーが URL から閲覧できます。さらに、保存したレポートを毎週月曜 9 時などの定期配信にできます（通知にはレポートへのリンクと出力テーブル名だけが載り、データ本体は載りません）。

あらかじめ用意された分析の手順書（プロンプト）も配布しています。

| 手順書 | 内容 |
| - | - |
| 分析クイックスタート | 組織選択 → カタログ確認 → dry-run → 実行 → 分析レポート保存までの標準手順 |
| 週次 KPI レポート | 週次 KPI の推移を折れ線で保存し、毎週月曜の定期配信まで用意する |
| ファネル分析 | ステップ別の通過数と遷移率を棒グラフで保存する |
| コホートリテンション | 月次コホート × 経過月の継続率を表と折れ線で保存する |
| 異常チェック | 直近 7 日と前 7 日を比べ、±20% を超える変化を異常候補として保存する |
| カタログ下書き | 未記入のデータカタログを下書きし、AI の提案として保存して人の承認に回す |

### ダッシュボード

組織のホーム画面に並ぶ共有ダッシュボード（メモカードと分析レポートのカード）を読み書きします。保存は全カードの置き換えなので、AI は最初に現在の内容を読み、他のカードを残したうえで保存します。他の人が先に更新していた場合は保存が拒否され、読み直しが必要です。削除したメモも過去の版から復元できます。

### 設計ガイド

Spumote のデータ設計の型（データの層の分け方、標準テーブル、機密データの分離、命名規則など）を AI が必要な節だけ取り出して参照します。AI がワークフローやテーブルを設計するとき、組織の流儀に沿ったものを作るための参考資料です。

## MCP ツール一覧

「入口」列は、そのツールが出る接続先です（読取＝すべての入口／クエリ＝`/mcp/query` と `/mcp`／全＝`/mcp` のみ）。「必要な権限」はロール権限で、対応するスコープも必要です。

### 組織・共通

| ツール名 | 何ができるか | 必要な権限 | 入口 |
| - | - | - | - |
| `spumote_list_organizations` | 使える組織と、ログイン中のユーザーを一覧する | `data:read` | 読取 |
| `spumote_get_organization_context` | 組織のロール・権限・機密レベル・フォルダ・データセット・接続先の情報（シークレットなし）を取得する | `data:read` | 読取 |
| `spumote_get_design_guide` | データ設計の型（目次 → 必要な節）を取得する | （組織データに触れない） | 読取 |
| `spumote_get_dashboard` | 共有ダッシュボードを取得する | `data:read` | 読取 |
| `spumote_list_dashboard_revisions` | ダッシュボード・メモの履歴を取得する | `data:read` | 読取 |
| `spumote_save_dashboard` | 共有ダッシュボードを保存する（全カード置換） | `data:write`（新しい分析カードは `data:analysis:read` も） | 全 |
| `spumote_restore_dashboard_note` | メモの過去版を復元する | `data:write` | 全 |

### データ・クエリ・分析

| ツール名 | 何ができるか | 必要な権限 | 入口 |
| - | - | - | - |
| `spumote_list_bigquery_assets` | BigQuery のプロジェクト・データセット（必要ならテーブル）を一覧する | `data:read` | 読取 |
| `spumote_preview_table` | テーブルの先頭を最大 100 行プレビューする | `data:read` | 読取 |
| `spumote_dry_run_query` | クエリを実行せずに検証し、スキャン量を見積もる | `data:bigquery:execute` | 読取 |
| `spumote_execute_query` | SELECT を実行し結果を返す | `data:bigquery:execute` | クエリ |
| `spumote_execute_statement` | データを変える文を二段階で実行する | `data:bigquery:execute` | 全 |
| `spumote_list_analyses` | 保存済みの分析レポートを一覧する | `data:analysis:read` | 読取 |
| `spumote_save_analysis` | SELECT とグラフ設定を分析レポートとして保存する | `data:analysis:write` ＋ `data:bigquery:execute` | 全 |
| `spumote_schedule_report` | 分析レポートを定期配信のワークフローにする（下書きで作成） | `data:analysis:write` ＋ `data:workflow:manage` | 全 |

### データカタログ

| ツール名 | 何ができるか | 必要な権限 | 入口 |
| - | - | - | - |
| `spumote_get_data_catalog` | テーブル・列のカタログ（未記入も含む）を取得する | `data:bigquery:read` | 読取 |
| `spumote_get_data_catalog_history` | カタログの変更履歴を取得する | `data:bigquery:read` | 読取 |
| `spumote_upsert_data_catalog` | カタログを AI の提案として書き込む（1 回 500 件まで） | `data:bigquery:write` | 全 |
| `spumote_approve_data_catalog` | AI の提案を承認する | `data:bigquery:write` | 全 |

### ワークフロー・センサー・通知・ファイル

| ツール名 | 何ができるか | 必要な権限 | 入口 |
| - | - | - | - |
| `spumote_list_workflows` | ワークフローを一覧する | `data:read` | 読取 |
| `spumote_get_workflow` | ワークフローの定義を取得する | `data:read` | 読取 |
| `spumote_list_workflow_runs` | 実行履歴を一覧する | `data:read` | 読取 |
| `spumote_get_workflow_run` | 実行の状態とステップ結果を取得する | `data:read` | 読取 |
| `spumote_get_execution_logs` | 実行 1 件のステップログを取得する | `data:read` | 読取 |
| `spumote_validate_workflow` | 下書きを保存せずに検証する | `data:read` | 読取 |
| `spumote_create_workflow` | ワークフローを作成する | `data:write` | 全 |
| `spumote_update_workflow` | ワークフローを部分更新する（履歴・フォルダは保持） | `data:write` | 全 |
| `spumote_activate_workflow` | 下書き・一時停止のワークフローを有効にする | `data:write` | 全 |
| `spumote_pause_workflow` | 有効なワークフローを一時停止する | `data:write` | 全 |
| `spumote_delete_workflow` | ワークフローを削除する | `data:write` | 全 |
| `spumote_run_workflow` | 有効なワークフローを手動実行する | `data:workflow:manual-execute` | 全 |
| `spumote_rerun_failed` | 失敗したステップから再実行する | `data:workflow:manual-execute` | 全 |
| `spumote_cancel_execution` | 実行中の処理をキャンセルする | `data:workflow:write` | 全 |
| `spumote_list_asset_sensors` | データ到着チェック（センサー）を一覧する | `data:read` | 読取 |
| `spumote_get_asset_sensor` | センサー 1 件と直近の確認履歴を取得する | `data:read` | 読取 |
| `spumote_create_asset_sensor` | センサーを作成する | `data:write` | 全 |
| `spumote_update_asset_sensor` | センサーを更新する（一時停止も） | `data:write` | 全 |
| `spumote_delete_asset_sensor` | センサーを削除する | `data:write` | 全 |
| `spumote_list_notification_sets` | 通知セットを一覧する | `data:workflow:manage` | 読取 |
| `spumote_create_notification_set` | 通知セットを作成する | `data:workflow:manage` | 全 |
| `spumote_update_notification_set` | 通知セットを更新する | `data:workflow:manage` | 全 |
| `spumote_delete_notification_set` | 通知セットを削除する | `data:workflow:manage` | 全 |
| `spumote_list_file_assets` | ファイル接続先を一覧する（シークレットなし） | `data:read` | 読取 |
| `spumote_create_managed_file_asset` | Spumote 管理ストレージの接続先を作成する | `data:write` ＋ `data:file:read` ＋ `data:file:write` ＋ `data:connection:manage` | 全 |
| `spumote_update_file_asset` | 接続先の名前・状態を変更する | `data:write` ＋ `data:connection:manage` | 全 |
| `spumote_delete_file_asset` | 接続先を無効化する | `data:write` ＋ `data:connection:manage` | 全 |

## M2M API（システム連携用 OAuth クライアント）

人がログインして許可する代わりに、システム用アカウント（サービスプリンシパル）とクライアント ID・シークレットを発行し、システムが自動でアクセストークンを取得して MCP を使う方式です（OAuth の client\_credentials 方式）。

1. オーナーが、名前・割り当てるロール・許可するスコープ（1 つ以上）を指定して発行します。
2. 発行時の応答にだけシークレットが含まれます。以後は二度と取得できないので、その場で安全に保管します。
3. 不要になったら失効させます。

システム用アカウントにも「ロールの権限」と「スコープ」の二重ガードがかかるので、必要最小限のロールとスコープで発行します。

| 項目 | 内容・制限 |
| - | - |
| 名前 | 1〜200 文字 |
| ロール | 組織のロールから 1 つ |
| スコープ | 上の「許可する範囲（スコープ）」から 1 つ以上 |

## 活用例

* **週次 KPI の自動配信**: AI に「注文件数の週次推移をレポートにして、毎週月曜に届くようにして」と頼むと、分析レポートを保存し、定期配信のワークフローを下書きで作ります。内容を確認して有効化すれば、以後は AI なしで毎週通知が届きます。
* **分析は任せて、データの変更はさせない**: 分析担当には `/mcp/query` の入口だけを案内すると、AI は自由に集計できますが、ワークフローの作成やデータの変更はできません。

## 注意点・制限

* AI ができることは、接続時に許可したスコープと本人のロール権限の両方を満たす範囲に限られます。ロールを超える操作はできません。
* 機密レベル「一般」のロールでは、クエリ結果はマスクされたまま AI に渡ります。
* SELECT の実行は既定 100 行・最大 1,000 行、スキャン課金の上限は既定 10 GiB（指定で最大 1 TiB）です。分析レポートの保存は既定 100 行・最大 1,000 行です。
* データを変える SQL は、AI が実行前に利用者へ SQL を見せて確認するよう指示されています。
* シークレット（接続先の鍵など）は、どのツールからも返りません。
* MCP 経由の呼び出しは、経路「mcp」として監査ログに残ります。

## 関連ページ

* 付録A 権限一覧
* 付録C APIエンドポイント一覧
* [02-3-1 自動処理（ワークフロー）：基本と作り方](/dsv2/workflow-basics)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.