---
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 経路あります。

- 個人用: 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 機能全体が無効化されます。

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

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

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

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

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

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

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

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

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

## トラブルシューティング

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

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