mcp-agent MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

パターンライブラリ: Orchestrator、Router、Evaluator、Swarm、Parallel、Deep Research
Temporalによる耐久ワークフロー（同じコードのままエグゼキューターを切り替えるだけ）
MCPAppライフサイクルがサーバー接続をクリーンに管理
デコレーター: @app.workflow、@app.tool、@app.workflow_task

ライブデモ

実際の動作

mcp-agent.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent",
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-agent"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add mcp-agent -- uvx mcp-agent

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： mcp-agent

リサーチタスク向けのオーケストレーター・ワーカーエージェントを構築する

👤 マルチステップエージェントを構築するPython開発者 ⏱ ~60 min advanced

使うタイミング： 1回のLLMパスでは処理しきれないが、並列サブタスクに分解可能なタスク（例: 競合10社のリサーチ）。

前提条件

Python 3.10+ — standard
エージェントに使用させたいMCPサーバー — mcp-agentのコンフィグに記載する

フロー

ワーカーエージェントを定義する

2つのAgentを作成 — firecrawlサーバーを使うscraperと、filesystemを使うwriter。それぞれに特化したインストラクションセットを設定します。✓ コピーしました

→ 2つのAgentインスタンス
オーケストレーターを接続する

create_orchestrator(planner_llm=..., workers=[scraper, writer])でラップします。最大イテレーション数 = 10。✓ コピーしました

→ Orchestratorがプランと実行ハンドルを返す
実際のタスクを実行する

実行: 'GitHub上で評価の高いPostgres MCPトップ5をリサーチし、それぞれについて1ページのサマリーを./reports/<slug>.mdに書き出してください。'✓ コピーしました

→ 一貫性のある内容で5ファイルが生成される

結果： 手動のマルチステップ作業で30分かかるものを3〜5分で完了できる並列化エージェント。

注意点

Orchestratorがサブタスクを多すぎるまたは少なすぎる数に分割する — プランナーLLMに明示的なガイダンスを与える: '3〜7個のサブタスクに分割し、各タスクは5分以内の作業量にすること'
ワーカーが同じデータを重複取得する — アプリステートを通じてキャッシュを共有するか、プランを通じて結果を明示的に受け渡す

組み合わせ： mcp-use · fastmcp

高品質なライティングのためのエバリュエーター・オプティマイザーエージェントを構築する

👤 コンテンツパイプラインを運用するチーム ⏱ ~45 min advanced

使うタイミング： 初稿のLLM出力がプロダクション品質に達していない場合。'合格するまで自動的にイテレーションを繰り返す'ループが必要なとき。

フロー

ライターとエバリュエーターを定義する

ライター: ブリーフに基づいてドラフトを生成。エバリュエーター: [正確性、明瞭性、トーン]を1〜5で採点し、根拠を示す。✓ コピーしました

→ 2つのエージェントが定義される
ループを設定する

EvaluatorOptimizerを使用し、全基準でmin_rating=4、max_iterations=5に設定。ブリーフを入力として渡す。✓ コピーしました

→ ループが実行され、イテレーションがログに表示される
収束を観察する

多様な10件のブリーフについて、初期スコア、最終スコア、必要イテレーション数をログに記録。収束しないブリーフはあるか？✓ コピーしました

→ 外れ値が特定された統計データ

結果： 人間によるレビューなしで、一貫した品質の出力を実現。

注意点

エバリュエーターが甘く、イテレーション1で中途半端な出力のまま終了する — エバリュエーターをキャリブレーションする — システムプロンプトに3つの入力例と期待スコアを提示する
max_iterationsが高いとコストが膨れ上がる — 3〜4回に制限する。それまでに収束しない場合、問題はモデルではなくブリーフにある

Temporalでエージェントワークフローを耐久化する

👤 プロダクション環境でエージェントを運用するプラットフォームエンジニア ⏱ ~90 min advanced

使うタイミング： エージェントフローが長時間実行（数分〜数時間）で、ノード障害時にゼロからやり直す余裕がない場合。

前提条件

稼働中のTemporalクラスター — ローカルはtemporal server start-dev、本番はTemporal Cloudまたはセルフホスト

フロー

ワークフローにアノテーションを付ける

既存のオーケストレーター関数に@app.workflowデコレーターを、個別のステップに@app.workflow_taskデコレーターを付与します。✓ コピーしました

→ ワークフローがTemporalに登録される
エグゼキューターを切り替える

アプリコンフィグをexecutor: 'temporal'に変更。ワーカーを登録し、ワークフローを開始します。✓ コピーしました

→ Temporal UIに実行中のワークフローが表示される
クラッシュリカバリを検証する

ワークフロー実行中にPythonワーカーを強制終了。再起動し、最後に完了したアクティビティからワークフローが再開されることを確認します。✓ コピーしました

→ 重複作業なし、状態ロストなし

結果： エージェントワークフローがプロセス再起動、デプロイ、OOMを乗り越えて継続します — 数時間のリサーチタスクには不可欠です。

注意点

アクティビティが冪等でなく、再開時に二重書き込みが発生する — すべてのアクティビティをリトライセーフにする — 外部書き込みには冪等キーを使用すること

組み合わせ

他のMCPと組み合わせて10倍の力を

mcp-agent + mcp-use

mcp-useでクライアント接続を処理し、mcp-agentでワークフローパターンを適用

mcp-useでfilesystem + gitを接続。mcp-agentのOrchestratorでラップして、マルチリポジトリのリファクタリングを計画する。✓ コピーしました

mcp-agent + fastmcp

FastMCPでカスタムMCPを構築し、mcp-agentワークフローから利用する

社内のランキングAPIをFastMCPで公開し、顧客の質問を分類するmcp-agentのRouterで使用する。✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
MCPApp	config_path or config object	トップレベル — プロセスごとに1つ	free
Agent(name, instruction, server_names)	configured with which MCP servers it can use	各ワーカー/ロールを定義する際に使用	free
AugmentedLLM.generate / generate_str / generate_structured	messages, optional schema	MCPツールが接続されたLLMを直接呼び出す場合	LLM tokens
create_parallel_llm / create_router_llm / create_orchestrator	agents + planner LLM	組み込みパターンのいずれかをインスタンス化する場合	LLM tokens × pattern fan-out
@app.workflow / @app.workflow_task	decorator on async function	Temporalエグゼキューター使用時	free
EvaluatorOptimizer	writer_agent, evaluator_agent, min_rating, max_iterations	品質が重要な出力に使用	expensive — cap max_iterations

コストと制限

運用コスト

APIクォータ: mcp-agent自体のクォータなし。LLM + MCPのコストはパススルー
呼び出しあたりのトークン: パターンはトークンを増幅する — 5ワーカーのParallelは単一LLMコールの5倍のトークンを消費
金額: ライブラリは無料。LLM + オプションのTemporalインフラが実コスト
ヒント: Orchestratorなどのパターンはファンアウトする — プランナーLLMのシステムプロンプトに明示的なトークン予算チェックを組み込むこと

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： LLMキーとMCPごとのシークレットは環境変数で管理

データ送信先： LLMプロバイダー + 設定済みの各MCPサーバー + Temporal（有効時）

トラブルシューティング

よくあるエラーと対処法

ワークフローが開始時にログなしでハングする

MCPサーバーの起動に失敗しています。デバッグログを有効にしてください: コンフィグでlogger: {level: 'DEBUG'}を設定。通常、サーバーエントリのコマンドまたは環境変数の設定ミスが原因です。

Orchestratorがプランを返すが実行されない

.generate()ではなく.plan()を呼び出しています。プランを実行するにはフルメソッドを使用してください。

Temporalワークフローがserialization errorで失敗する

アクティビティがシリアライズ不可能なオブジェクト（例: MCPクライアントハンドル）を返しています。アクティビティはJSONシリアライズ可能な値を返す必要があります。

LLMが利用可能なツールを無視してハルシネーションする

システムプロンプトが切り詰められているか、ツールリストが欠落している可能性があります。ツール使用に強いモデル（Sonnet、GPT-4o）にアップグレードし、実行前にlist_toolsでツールを確認してください。

代替案

mcp-agent 他との比較

代替案	代わりに使う場面	トレードオフ
mcp-use	パターンライブラリなしで軽量なクライアント接続だけが必要な場合	オーケストレーションのコードは自分で書く必要がある
LangGraph	タイムトラベルデバッグ付きのステートフルグラフが必要な場合	LangChain寄りの設計。MCPは後付けの統合
CrewAI	ロールベースのエージェントクルーを独自の設計思想で構築したい場合	異なるメンタルモデル。MCPサポートは二次的な位置付け

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る