MCP とツール

zqagent の実行時には MCP（Model Context Protocol）で外部ツールを注入できます。内蔵 OCR はすぐ使え、/tool add でコマンドツールも作成できます。

MCP サーバーのインストール

コマンド	説明
/mcp	サーバー、接続状態、ツール数を一覧表示
/mcp add	対話式インストール：テンプレート選択 → パラメータ入力 → 接続して保存
/mcp add <name> stdio <cmd...>	ローカルプロセスを手動追加
/mcp add <name> http|sse <url>	リモートエンドポイントを手動追加
/mcp import [file]	設定をインポート。ファイルなしの場合は JSON を貼り付け、EOF で終了
/mcp rm|enable|disable|refresh [name]	削除 / 有効化 / 無効化 / ツール一覧の更新

内蔵テンプレート：Filesystem、Memory、Sequential Thinking、GitHub、Fetch、PostgreSQL、OCR。

既存設定のインポート

/mcp import は素の配列、{ "servers": [...] }、および Claude Desktop / Cursor の mcpServers オブジェクト形式に対応します：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

• type を省略すると builtin / url / command から推測します。url が /sse で終わる場合は SSE と推測します。
• command は文字列でもよく、args 配列と自動的に結合されます。${VAR} / ${env:VAR} の環境変数展開にも対応。
• 保存時は配列形式で .agent/mcp.json に書き込みます（プロジェクトに従い、git にコミット可能）。同名の項目をインポートするときは上書きかスキップかを個別に確認します。

内蔵 OCR

内蔵 OCR は既定で有効です（{ "name": "ocr", "type": "builtin", "builtin": "ocr" }）。ツール名は mcp__ocr__recognize です。

• 入力：imagePath（推奨。ワークスペース内のパス）、imageBase64、imageUrl。PDF はページごとに認識します（maxPages 既定 5、dpi 既定 150）。
• エンジンは自動的に降格します：macOS Vision（Xcode Command Line Tools が必要）→ tesseract + pdftoppm → 設定済みのマルチモーダルモデル。
• すべて使えない場合は error と how_to_fix を返し、起動や他のツールをブロックしません。
• 無効化する場合：/mcp disable ocr。

Linux サーバーイメージには tesseract-ocr、tesseract-ocr-chi-sim、poppler-utils が組み込まれています。ローカル環境ではシステムのパッケージマネージャーでインストールできます：

# macOS
brew install tesseract tesseract-lang poppler
# Debian / Ubuntu
apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

オンデマンド読み込み

MCP ツールが多い場合（既定で 16 個以上、または schema 合計 24000 文字以上）、自動的にオンデマンド読み込みに切り替わります：

• mcp__* を全量送信せず、mcp_search_tools（検索）と mcp_call_tool（呼び出し）を使います。
• モデルがまず検索し、ヒットしたツールは次のターンで読み込まれます（1 セッション上限 40 個）。メタツールで直接呼び出すこともできます。
• 小規模な場合は従来どおり全量注入され、挙動は変わりません。ZQAGENT_MCP_LAZY=1|0 で強制できます。

コマンドツール

コマンド	説明
/tool add <name> <cmd...>	コマンドツールを追加（shell コマンドを実行）
/tool rm|disable|enable <name>	ツールを削除 / 無効化 / 有効化

即時反映と保存

ツールの追加 / 削除 / 無効化 / 置換は次の会話からすぐ反映され、再起動は不要です。

MCP サーバーとコマンドツールの設定はプロジェクトとともに保存され、git にコミットしてチームと共有できます。 MCP が注入するツール（内蔵 OCR を含む）は既定で高リスクとして扱われ、対話モードでは毎回承認が必要です。

次のステップ

• 内蔵ツール
• CLI の使い方