---
id: mcp
title: MCP サーバー連携
category: advanced
order: 130
keywords: [MCP, Model Context Protocol, サーバー, ツール連携, 外部連携]
---

## MCP 連携でできること

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

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

## サーバーを登録する

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

- ワークスペース単位: ワークスペースを開いて **設定 → MCP** → 「+ 追加」。個人ワークスペースで登録したサーバーは自分専用、案件ワークスペースで登録したサーバーはそのワークスペースのメンバーで共有されます（旧「ユーザーフォルダ → MCP サーバー」タブは廃止され、ワークスペース設定に集約されました。→「[個人の資産（ワークスペース設定）](09-userfolder.md)」）。
- 全体共有 (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 機能全体が無効化されます。

```bash
export MCP_ENCRYPTION_KEY="$(openssl rand -base64 32)"
```

機密値なので `config.yaml` ではなくデプロイ環境の環境変数で渡してください。

## エージェントへの露出 (ツールポリシーと接続)

エージェントが MCP ツールを使えるかどうかは、**ワークスペースのツールポリシー**と、**そのワークスペース（スペース）に MCP サーバーが登録・連携されているか**で決まります。以前のように Piece の `allowed_tools` へ `mcp__*` を書き足す必要はありません。

仕組みはこうです。

- MCP カテゴリはワークスペースのツールポリシーで既定オンになっており、エージェントには常に `mcp__*`（全 MCP ツール）への入口が渡されます。
- 実際に呼べるツールは、そのワークスペースに**登録済みかつ連携済み**の MCP サーバーが提供するものに限られます。サーバーを登録していなければ、エージェントから見える MCP ツールはありません。
- OAuth 方式のサーバーは「連携」ボタンで認証を済ませるまで、ツールが提示されません。

つまり「どのサーバーを使わせるか」はワークスペースに登録するサーバーで決まり、Piece 側で許可リストを管理する必要はなくなりました。ツールポリシー全体の考え方は [ワークスペースとメンバー](./21-workspaces.md)、ツールの分類は [ツールリファレンス](./16-tools.md) を参照してください。

### タスク作成時の連携チェック

タスク作成時、選んだ Piece が必要とする MCP サーバーにまだ連携していない場合は警告が表示され、その場で連携できます。未連携のまま作成すると、タスクは連携待ちで停止し、連携完了後に再開します。

## タスクごとに MCP を無効化する

MCP ツールの定義は LLM への送信トークンを消費します。MCP を使わないタスクでは、タスク作成ダイアログの

> MCP ツールを無効化 (トークン節約)

チェックボックスを ON にすると、そのタスクでは MCP ツールが一切提示されません。トークン節約や挙動の単純化に有効です。タスク作成の詳細は [タスクを作って実行する](./02-tasks.md) を参照してください。

## ランタイム設定 (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 |

設定画面の詳細は [設定](./17-settings.md) を参照してください。

## 生の 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` を参照してください。