maestro/13-mcp.md at f5c7666f6b859a0a8d2eda8375c3580ad8c17b86

swallow/maestro

Fork 0

oss-sync f5c7666f6b feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00

5.9 KiB

Raw Blame History

id, title, category, order, keywords

title

MCP 連携でできること

MCP (Model Context Protocol) は、外部サービスのツールをエージェントに開放するための標準プロトコルです。MCP サーバーを登録すると、そのサーバーが提供するツールが mcp__<serverId>__<toolName> という名前でエージェントに見えるようになり、タスク実行中に呼び出せます。

たとえば Gmail / Google Calendar / Drive / Notion / Canva などの MCP サーバーを登録しておくと、これらのアクションをエージェントのタスクから直接実行できます。

サーバーを登録する

登録方法は 2 経路あります。

個人用: TopBar → ユーザーフォルダ → MCP サーバータブ → 「+ 追加」。owner_id が自分にセットされ、他のユーザーからは見えません。
全体共有 (admin): admin が同じ画面の「全体のサーバー」セクションから登録すると、組織全員が使えます。

登録時に入力する主な項目:

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 ではなくデプロイ環境の環境変数で渡してください。

Piece への露出 (依存ゲーティング)

エージェントが MCP ツールを呼べるのは、その Piece の allowed_tools に mcp__* ワイルドカードが入っている場合だけです。

allowed_tools:
  - Read
  - WebSearch
  - 'mcp__*'          # 全 MCP ツールを許可

特定サーバーだけ許可したい場合は接頭辞で絞ります。

allowed_tools:
  - 'mcp__gmail__*'   # Gmail サーバーのツールのみ

汎用の chat piece はデフォルトで mcp__* を含むため、通常のチャットタスクからは自動で MCP ツールを使えます。Piece の allowed_tools の考え方は 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 行サマリの追記ログ

デバッグや監査の際にこれらを確認できます。

トラブルシューティング

ツールが見えない: 未連携 (OAuth)、MCP_ENCRYPTION_KEY 未設定、または Piece の allowed_tools に mcp__* が無い、のいずれか
private IP / localhost への接続が拒否される: SSRF チェックによるもの。自前サーバーなら mcp.allow_private_addresses: true で許可
OAuth token の期限切れ: 該当サーバーを再連携する

より詳しい仕様は docs/mcp.md を参照してください。

5.9 KiB Raw Blame History