Claude CodeでMCP・Agent・Pluginを統合起動する方法｜外部ツール連携の完全入門

Claude Code単体でも強力ですが、MCP（Model Context Protocol）で外部データソースに接続したり、カスタムエージェントで役割を分担させたりすると、パイプラインの能力は一気に広がります。「データベースからスキーマを取得してドキュメントを自動生成」「コード解析エージェントとドキュメント生成エージェントを分離して品質向上」といったことが実現できます。本記事では --mcp-config、--agents、--plugin-dir、--system-prompt など統合起動に関わるオプションを一気に解説します。

前提知識

Claude Code CLI のprintモード、セッション管理、--effort によるコスト最適化、--disallowed-tools による権限設計、--debug / --settings による設定管理の基本を理解していることを前提とします。MCPの概念は本記事で解説しますので、初めての方でも読み進められます。

MCP・Plugin・Agent の違い

統合起動に関わる3つの概念を整理します。

–system-prompt でパイプライン専用プロンプトを設定する

最も手軽な拡張はシステムプロンプトのカスタマイズです。システムプロンプトとは、Claude
がユーザーのプロンプトを処理する前に読み込む「裏側の指示書」のことで、応答のスタイルや役割を制御できます。–system-prompt でこの指示書を丸ごと置き換え、–append-system-promptで既存の指示書に追記できます。

# --system-prompt: プロンプト全体を置き換え
claude -p "README概要を生成してください" --system-prompt "あなたはREADME生成の専門家です。日本語で応答してください。" --output-format json | jq -r '.result'

# --append-system-prompt: 既存のデフォルトプロンプトに追記（こちらが安全）
claude -p "README概要を生成してください" --append-system-prompt "出力はMarkdown形式で、見出しレベルは##から始めてください。" --output-format json | jq -r '.result'

--system-prompt はデフォルト動作ごと置き換えるため、多くの場合 --append-system-prompt の方が安全です。

–file でファイルリソースを取り込む

--file は外部サービスのファイルリソースをダウンロードするオプションで、file_id:relative_path の形式で指定します。

利用には CLAUDE_CODE_SESSION_ACCESS_TOKEN 環境変数の設定が必要です。

ローカルファイルをコンテキストに含めたい場合は、プロンプト内でファイル名を指示するか、次に紹介する --add-dir を使ってください。

–add-dir で追加ディレクトリを許可する

デフォルトではカレントディレクトリ配下のファイルにアクセスしますが、--add-dir で範囲を広げられます。モノレポで別パッケージを参照したり、共有テンプレートディレクトリを読み込む場合に便利です。

# 共有ライブラリのディレクトリも含めて解析
claude -p "共有ライブラリも含めてコードを分析してください" --add-dir ~/shared-libs --output-format json | jq -r '.result'

# 複数ディレクトリを追加
claude -p "両パッケージを比較分析" --add-dir ~/monorepo/packages/api --add-dir ~/monorepo/packages/web --output-format json | jq -r '.result'

–mcp-config で MCP サーバーに接続する

MCP設定をJSONファイルで定義し、Claude Codeに読み込ませます。

注意: args の最後の要素（/Users/use r/project）は、MCPサーバーがアクセスするディレクトリのパスです。実 際のプロジェクトディレクトリのフルパスに置き換えてください（例: /Users/yourname/readme-pipeline-demo）。パスが存在しない場合 やプレースホルダーのままだと、MCPサーバーに接続できず、Claude Codeは通常のファイルアクセスにフォールバックします。

# MCP設定ファイルの作成
cat << 'EOF' > mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/user/project"
      ]
    }
  }
}
EOF

# MCP経由で実行
claude -p "MCP経由でリポジトリの構造を確認" --mcp-config mcp_config.json --output-format json | jq -r '.result'

–strict-mcp-config でセキュリティを強化

本番パイプラインでは、明示指定したMCPサーバー以外を無視してセキュリティを高めましょう。

Claude Codeは通常、--mcp-config で指定したサーバーに加えて、ユーザー設定（~/.claude/settings.json）やプロジェクト設定（.claude/settings.json）に定義された MCPサーバーもすべて読み込みます。つまり、誰かが設定ファイルに追加したMCPサ ーバーが、知らないうちにパイプラインで使われる可能性があります。

--strict-mcp-config を付けると、--mcp-config で明示指定したサーバーだけが有効になり、それ以外は無視されます。CI/CD環境 など、接続先を厳密に管理したい場面で使いましょう。

claude -p "README情報を生成" --mcp-config mcp_config.json --strict-mcp-config --output-format json | jq -r '.result'

--strict-mcp-config を付けると、プロジェクトやユーザー設定で定義された他のMCPサーバーは無視されます。

–agents でカスタムエージェントを定義する

--agents でJSON形式のエージェント定義を渡し、--agent で使用するエージェントを選択します。

# エージェント定義ファイルを作成
cat << 'EOF' > agents.json
{
  "code-analyzer": {
    "description": "コードの静的解析を行うエージェント",
    "prompt": "コード解析の専門家として分析してください。"
  },
  "doc-writer": {
    "description": "技術ドキュメントを生成するエージェント",
    "prompt": "技術ドキュメントのライターとして日本語で生成してください。"
  }
}
EOF

段階的に異なるエージェントを使い分けます。

# Step 1: コード解析（code-analyzerエージェント）
claude -p "コード構造を分析" --agents "$(cat agents.json)" --agent code-analyzer --output-format json | jq -r '.result' > analysis.txt

# Step 2: ドキュメント生成（doc-writerエージェント）
cat analysis.txt | claude -p "分析結果からREADMEを生成" --agents "$(cat agents.json)" --agent doc-writer --output-format json | jq -r '.result' > README.md

エージェントを分離することで、各ステップの専門性が高まり、出力品質が向上します。

–plugin-dir でプラグインを読み込む

Claude Codeはプラグインで機能を拡張できます。

通常は claude plugin install でインストールしますが、--plugin-dir を使うと、ローカルで開発中のプラグインをそのセッションだけ一時的に読み込め ます。

# ローカルのプラグインディレクトリを指定して起動
claude -p "README情報を生成" --plugin-dir ~/my-plugins --output-format json | jq -r '.result'

次に試してみよう

まずは --agents で「API Reference Agent」「Tutorial Agent」「FAQ Agent」の3つを定義し、READMEの異なるセクションを分担生成してみましょう。--system-prompt と --append-system-prompt の出力品質の違いを比較するのも良い練習です。

まとめ

• --system-prompt / --append-system-prompt でパイプライン専用のプロンプトを設定できる
• --file は外部サービスのファイルリソースをダウンロードするオプション。ローカルファイルには --add-dir を使う
• --add-dir でカレントディレクトリ外のファイルへのアクセスを許可できる
• --mcp-config でMCPサーバーに接続し、外部ツール・データソースを活用できる
• --strict-mcp-config で接続先を限定し、セキュリティを強化できる
• --agents / --agent でカスタムエージェントを定義し、専門化されたタスクを実行できる
• --plugin-dir でプラグインを読み込み、機能を拡張できる

さらに深く学びたい方へ
Claude Codeの Skills・MCP・Agent・Hooks・Plugin を体系的に学べる有料教材を Zenn で公開しています。
Claude Code 実践ガイド（Zenn Book）