8.4 KiB
id, title, category, order, keywords
| id | title | category | order | keywords | |||||
|---|---|---|---|---|---|---|---|---|---|
| mcp | MCP サーバー連携 | advanced | 130 |
|
MCP 連携でできること
MCP (Model Context Protocol) は、外部サービスのツールをエージェントに開放するための標準プロトコルです。MCP サーバーを登録すると、そのサーバーが提供するツールが mcp__<serverId>__<toolName> という名前でエージェントに見えるようになり、タスク実行中に呼び出せます。
たとえば Gmail / Google Calendar / Drive / Notion / Canva などの MCP サーバーを登録しておくと、これらのアクションをエージェントのタスクから直接実行できます。
サーバーを登録する
登録方法は 2 経路あります。
- ワークスペース単位: ワークスペースを開いて 設定 → MCP → 「+ 追加」。個人ワークスペースで登録したサーバーは自分専用、案件ワークスペースで登録したサーバーはそのワークスペースのメンバーで共有されます（旧「ユーザーフォルダ → MCP サーバー」タブは廃止され、ワークスペース設定に集約されました。→「個人の資産（ワークスペース設定）」）。
- 全体共有 (admin): admin が 設定 → MCP & Connections の「全体のサーバー」セクションから登録すると、組織全員が使えます。
案件ワークスペースで登録した API key 方式のサーバーは、ワークスペースのオーナー・管理者が 設定 → MCP からメンバーの利用可否を管理できます。資格情報（token / API key）はワークスペースの鍵で暗号化され、メンバーはサーバーを使えても生の値は見えません。
登録時に入力する主な項目:
- id / name: 識別子と表示名 (例
gmail/Gmail) - URL: MCP サーバーのエンドポイント
- 認証方式: OAuth または API key
認証方式
| 方式 | 用途 | 特徴 |
|---|---|---|
| OAuth | ユーザー権限で動くサービス (Google 系・Notion・Canva 等) | ユーザーごとに token を持つ。登録後に「連携」ボタンでブラウザ認証 |
| API key | 共通アカウントで OK なサービス | 静的トークンを 1 度登録すれば全員が使える |
通信方式について
現行実装の MCP クライアントは HTTP ベースの transport (Streamable HTTP) で MCP サーバーに接続します。サーバー側はこの方式に対応した URL を提供してください。ローカル subprocess を起動する stdio transport は現時点では未対応です。
MCP_ENCRYPTION_KEY が必須
MCP サブシステムは、サーバー起動時に環境変数 MCP_ENCRYPTION_KEY が設定されている必要があります。token や API key の暗号化に使われ、未設定だと MCP 機能全体が無効化されます。
export MCP_ENCRYPTION_KEY="$(openssl rand -base64 32)"
機密値なので config.yaml ではなくデプロイ環境の環境変数で渡してください。
エージェントへの露出 (ツールポリシーと接続)
エージェントが MCP ツールを使えるかどうかは、ワークスペースのツールポリシーと、そのワークスペース（スペース）に MCP サーバーが登録・連携されているかで決まります。以前のように Piece の allowed_tools へ mcp__* を書き足す必要はありません。
仕組みはこうです。
- MCP カテゴリはワークスペースのツールポリシーで既定オンになっており、エージェントには常に
mcp__*（全 MCP ツール）への入口が渡されます。 - 実際に呼べるツールは、そのワークスペースに登録済みかつ連携済みの MCP サーバーが提供するものに限られます。サーバーを登録していなければ、エージェントから見える MCP ツールはありません。
- OAuth 方式のサーバーは「連携」ボタンで認証を済ませるまで、ツールが提示されません。
つまり「どのサーバーを使わせるか」はワークスペースに登録するサーバーで決まり、Piece 側で許可リストを管理する必要はなくなりました。ツールポリシー全体の考え方は ワークスペースとメンバー、ツールの分類は ツールリファレンス を参照してください。
タスク作成時の連携チェック
タスク作成時、選んだ Piece が必要とする MCP サーバーにまだ連携していない場合は警告が表示され、その場で連携できます。未連携のまま作成すると、タスクは連携待ちで停止し、連携完了後に再開します。
タスクごとに MCP を無効化する
MCP ツールの定義は LLM への送信トークンを消費します。MCP を使わないタスクでは、タスク作成ダイアログの
MCP ツールを無効化 (トークン節約)
チェックボックスを ON にすると、そのタスクでは MCP ツールが一切提示されません。トークン節約や挙動の単純化に有効です。タスク作成の詳細は タスクを作って実行する を参照してください。
ランタイム設定 (admin)
MCP の動作に関わる共通設定は 設定 → MCP & Connections → MCP Runtime にあります (admin 専用)。config.yaml では mcp セクションに対応します。
| 設定キー (snake_case) | 意味 | デフォルト |
|---|---|---|
call_timeout_seconds |
1 回の MCP ツール呼び出しの最大時間 (秒) | 60 |
tool_cache_ttl_seconds |
サーバーから取得したツール一覧のキャッシュ時間 (秒) | 600 |
oauth_pending_ttl_minutes |
OAuth 認可フローの pending 保持時間 (分) | 10 |
max_binary_size_mb |
バイナリ出力 1 ファイルの最大サイズ (MB) | 20 |
max_output_files_per_job |
1 ジョブで保存できるバイナリ出力数 | 10 |
max_output_size_mb_per_job |
1 ジョブのバイナリ出力合計上限 (MB) | 200 |
allow_private_addresses |
private 網に置いた自前 MCP サーバーへの接続を許可 | false |
設定画面の詳細は 設定 を参照してください。
生の MCP レスポンスはログに残る
MCP ツール呼び出しの生レスポンスは、各ジョブのワークスペース配下に保存されます。
logs/mcp/{serverId}/{toolName}-{timestamp}-{hash}.json— 個別レスポンスの全文logs/mcp-history.jsonl— 1 行サマリの追記ログ
デバッグや監査の際にこれらを確認できます。
他のワークスペースから取り込む
同じ MAESTRO 内の別ワークスペースに登録済みの MCP サーバーを、まとめてコピーできます。設定 → MCP の「他のワークスペースから取り込む」ボタンを押すと、自分が管理しているワークスペースの一覧が出るので、コピー元を選んで実行してください。
- 操作できる条件: 取り込み元と移し先の両方でオーナー・管理者であること
- スキップ: 同じ id または同じ URL のサーバーがすでにある場合は自動でスキップされ、既存の設定は上書きされません
- 再認証が必要: OAuth 方式のサーバーは per-user トークンを移せません。取り込み後に「連携」ボタンでブラウザ認証をやり直してください。API key 方式はそのまま使えます
- 同一サーバー内のみ: 別環境（別インスタンス）へのエクスポートには対応していません
トラブルシューティング
- ツールが見えない: そのワークスペースに MCP サーバーが登録されていない、OAuth サーバーが未連携、ワークスペースのツール設定で MCP が無効、
MCP_ENCRYPTION_KEY未設定、またはタスク作成時に「MCP ツールを無効化」を ON にした、のいずれか - private IP / localhost への接続が拒否される: SSRF チェックによるもの。自前サーバーなら
mcp.allow_private_addresses: trueで許可 - OAuth token の期限切れ: 該当サーバーを再連携する
より詳しい仕様は docs/mcp.md を参照してください。