Mcp Agent

シンプルで組み合わせ可能なパターンを使って、Model Context Protocol で効果的なエージェントを構築しましょう。

サンプル | 効果的なエージェントの構築 | MCP

概要

mcp-agent は、Model Context Protocol を使用して効果的なエージェントを構築するための、シンプルで組み合わせ可能なフレームワークです。

メモ

mcp-agent のビジョンは、_エージェントの構築には MCP だけで十分であり、高品質なエージェントを提供するうえでは、複雑なアーキテクチャよりもシンプルなパターンのほうが堅牢である_というものです。

mcp-agent では、次のことができます。

1. MCP の完全なサポート：MCP を完全に実装し、MCP サーバー接続のライフサイクル管理という厄介な作業を代わりに処理します。
2. 効果的なエージェントパターン：Anthropic の効果的なエージェントの構築で説明されているすべてのパターンを組み合わせ可能な形で実装しており、これらのパターンを連結できます。
3. 耐久性のあるエージェント：シンプルなエージェントに対応し、Temporal 上に構築された高度なワークフローにも拡張できます。エージェントに API の変更を加えることなく、一時停止、再開、復旧が可能です。

これらを総合すると、堅牢なエージェントアプリケーションを構築するための、最もシンプルで簡単な方法です。

あらゆる種類の貢献、フィードバック、そしてこのプロジェクトの改善へのご協力を歓迎します。

最小限のサンプル

import asyncio

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world")

async def main():
    async with app.run():
        agent = Agent(
            name="finder",
            instruction="Use filesystem and fetch to answer questions.",
            server_names=["filesystem", "fetch"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            answer = await llm.generate_str("Summarize README.md in two sentences.")
            print(answer)


if __name__ == "__main__":
    asyncio.run(main())

# Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.
# The [Getting Started guide](https://docs.mcp-agent.com/get-started/overview) walks through configuration and secrets in detail.

概要

LLM を使ったドキュメント参照と構築

mcp-agent の完全なドキュメントは docs.mcp-agent.com で確認できます。SDK の完全ガイド、CLI リファレンス、高度なパターンなどを掲載しています。この README では、使い始めるための概要を説明します。

• llms-full.txt：ドキュメント全体が含まれています。
• llms.txt：ドキュメント内の主要ページを一覧にしたサイトマップです。
• ドキュメント用 MCP サーバー

目次

• 概要
• 最小限の例
• クイックスタート
• mcp-agent を使う理由
• コアコンセプト
  • MCPApp
  • エージェントと AgentSpec
  • 拡張 LLM
  • ワークフローとデコレーター
  • 設定とシークレット
  • MCP 統合
• ワークフローパターン
• CLI リファレンス
• 認証
• 高度な機能
  • 可観測性と制御
  • ワークフローの構成
  • 耐久性のある実行
  • エージェントサーバー
  • シグナルと人間による入力
  • アプリ設定
  • アイコン
  • MCP サーバー管理
• クラウドへのデプロイ
• サンプル
• よくある質問
• コミュニティと貢献

はじめに

ヒント

CLI は uvx mcp-agent で利用できます。 すぐに使い始めるには、 uvx mcp-agent init でプロジェクトをスキャフォールドし、uvx mcp-agent deploy my-agent でデプロイしてください。

次のコマンドを実行すれば、2 分で使い始められます。

mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
# openai API key を `mcp_agent.secrets.yaml` に追加するか、`OPENAI_API_KEY` を設定します
uv run main.py

インストール

Python プロジェクトの管理には uv（uv init）の使用をおすすめします。

uv add "mcp-agent"

または、次の方法もあります。

pip install mcp-agent

LLM プロバイダー向けのオプションパッケージも追加してください（例：uv add "mcp-agent[openai, anthropic, google, azure, bedrock]"）。

クイックスタート

ヒント

examples ディレクトリには、使い始めるためのサンプルアプリケーションがいくつかあります。 サンプルを実行するには、このリポジトリをクローンするか、uvx mcp-agent init --template basic --dir my-first-agent で生成してください。

cd examples/basic/mcp_basic_agent # または任意のサンプル
# オプション A：シークレット YAML
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
uv run main.py

以下は、fetch サーバーと filesystem サーバーを使用してファイルを検索し、ブログを読み、ツイートを書く基本的な「finder」エージェントです。サンプルへのリンク：

import asyncio
import os

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world_agent")

async def example_usage():
    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        # This agent can read the filesystem or fetch URLs
        finder_agent = Agent(
            name="finder",
            instruction="""You can read local files or fetch URLs.
                Return the requested information when asked.""",
            server_names=["fetch", "filesystem"], # MCP servers this Agent can use
        )

        async with finder_agent:
            # Automatically initializes the MCP servers and adds their tools for LLM use
            tools = await finder_agent.list_tools()
            logger.info(f"Tools available:", data=tools)

            # Attach an OpenAI LLM to the agent (defaults to GPT-4o)
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # This will perform a file lookup and read using the filesystem server
            result = await llm.generate_str(
                message="Show me what's in README.md verbatim"
            )
            logger.info(f"README.md contents: {result}")

            # Uses the fetch server to fetch the content from URL
            result = await llm.generate_str(
                message="Print the first two paragraphs from https://www.anthropic.com/research/building-effective-agents"
            )
            logger.info(f"Blog intro: {result}")

            # Multi-turn interactions by default
            result = await llm.generate_str("Summarize that in a 128-char tweet")
            logger.info(f"Tweet: {result}")

if __name__ == "__main__":
    asyncio.run(example_usage())

execution_engine: asyncio
logger:
  transports: [console] # You can use [file, console] for both
  level: debug
  path: "logs/mcp-agent.jsonl" # Used for file transport
  # For dynamic log filenames:
  # path_settings:
  #   path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
  #   unique_id: "timestamp"  # Or "session_id"
  #   timestamp_format: "%Y%m%d_%H%M%S"

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args:
        [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "<add_your_directories>",
        ]

openai:
  # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored
  default_model: gpt-4o

エージェントの出力

mcp-agent を使う理由

AI フレームワークはすでに数多くあります。しかし、mcp-agent は共有プロトコルである MCP 専用に構築された唯一のフレームワークです。mcp-agent は、Anthropic の Building Effective Agents のパターンと、必要な機能が一通りそろった MCP ランタイムを組み合わせているため、定型コードではなく振る舞いに集中できます。チームに選ばれる理由は次のとおりです。

• 組み合わせ可能 – すべてのパターンが再利用可能なワークフローとして提供され、自由に組み合わせられます。
• MCP ネイティブ – あらゆる MCP サーバー（filesystem、fetch、Slack、Jira、FastMCP アプリ）にカスタムアダプターなしで接続できます。
• 本番環境対応 – Temporal による耐久性、構造化ログ、トークンの使用量管理、クラウドへのデプロイを標準でサポートします。
• Python らしい設計 – 少数のデコレーターとコンテキストマネージャーですべてを連携できます。

ドキュメント：mcp-agent の紹介 • 効果的なパターンの概要。

コアコンポーネント

すべてのプロジェクトは、設定を読み込み、エージェントと MCP サーバーを登録し、ツールやワークフローを公開する単一の MCPApp ランタイムを中心に構成されます。コアコンポーネントのガイドでは、これらの構成要素について説明しています。

MCPApp

設定、ログ、トレーシング、実行エンジンを初期化し、すべてで単一のコンテキストを共有します。

from mcp_agent.app import MCPApp

app = MCPApp(name="finder_app")

async def main():
    async with app.run() as running_app:
        logger = running_app.logger
        logger.info("App ready", data={"servers": list(running_app.context.server_registry.registry)})

ドキュメント：MCPApp • サンプル：examples/basic/mcp_basic_agent。

エージェントと AgentSpec

エージェントは、指示と、呼び出し可能な MCP サーバー（およびオプションの関数）を組み合わせます。AgentSpec 定義はディスクから読み込み、ファクトリーヘルパーを使ってエージェントや拡張 LLM に変換できます。

from pathlib import Path
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.factory import load_agent_specs_from_file

agent = Agent(
    name="researcher",
    instruction="Research topics using web and filesystem access",
    server_names=["fetch", "filesystem"],
)

async with agent:
    tools = await agent.list_tools()

async with app.run() as running_app:
    specs = load_agent_specs_from_file(
        str(Path("examples/basic/agent_factory/agents.yaml")),
        context=running_app.context,
    )

ドキュメント：エージェント • エージェントファクトリーヘルパー • サンプル：examples/basic/agent_factory。

拡張 LLM

拡張 LLM は、プロバイダー SDK をエージェントのツール、メモリ、構造化出力ヘルパーでラップします。エージェントに追加すると、generate、generate_str、generate_structured を利用できるようになります。

from pydantic import BaseModel
from mcp_agent.workflows.llm.augmented_llm import RequestParams
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

class Summary(BaseModel):
    title: str
    verdict: str

async with agent:
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    report = await llm.generate_str(
        message="Draft a 3-sentence release note from CHANGELOG.md",
        request_params=RequestParams(maxTokens=400, temperature=0.2),
    )
    structured = await llm.generate_structured(
        message="Return a JSON object with `title` and `verdict` summarising the README.",
        response_model=Summary,
    )

ドキュメント：拡張 LLM • 例：examples/basic/mcp_basic_agent および gallery.md に記載されているワークフロープロジェクト。

ワークフローとデコレーター

MCPApp デコレーターは、コルーチンを永続的なワークフローとツールに変換します。同じアノテーションを asyncio と Temporal の両方での実行に使用できます。

from datetime import timedelta
from mcp_agent.executor.workflow import Workflow, WorkflowResult

@app.workflow
class PublishArticle(Workflow[WorkflowResult[str]]):
    @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5))
    async def draft(self, topic: str) -> str:
        return f"- intro to {topic}\n- highlights\n- next steps"

    @app.workflow_run
    async def run(self, topic: str) -> WorkflowResult[str]:
        outline = await self.draft(topic)
        return WorkflowResult(value=outline)

ドキュメント：デコレーターリファレンス • 例：examples/workflows。

設定とシークレット

設定は mcp_agent.config.yaml、mcp_agent.secrets.yaml、環境変数、および任意のプリロード文字列から読み込まれます。シークレットをソース管理に含めないでください。

# mcp_agent.config.yaml
execution_engine: asyncio
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
openai:
  default_model: gpt-4o-mini

# mcp_agent.secrets.yaml (gitignored)
openai:
  api_key: "${OPENAI_API_KEY}"

ドキュメント：設定リファレンス • シークレットの指定。

MCP 連携

既存の MCP サーバーにプログラムから接続するか、複数のサーバーを 1 つのファサードに集約できます。

from mcp_agent.mcp.gen_client import gen_client

async with app.run():
    async with gen_client("filesystem", app.server_registry, context=app.context) as client:
        resources = await client.list_resources()
        app.logger.info("Filesystem resources", data={"uris": [r.uri for r in resources.resources]})

ドキュメント：MCP 連携の概要 • 例：examples/mcp。

ワークフローパターン

主要なエージェントパターンは AugmentedLLM として実装されています。ファクトリーヘルパーを使って構成するか、gallery.md に記載されている実行可能なプロジェクトを確認してください。

パターン	ヘルパー	概要	ドキュメント
並列（Map-Reduce）	create_parallel_llm(...)	専門エージェントに処理を分配し、集約されたレポートを統合します。	並列
ルーター	create_router_llm(...) / create_router_embedding(...)	リクエストを最適なエージェント、サーバー、または関数に振り分けます。	ルーター
インテント分類器	create_intent_classifier_llm(...) / create_intent_classifier_embedding(...)	自動化の前にユーザー入力をインテントごとに分類します。	インテント分類器
オーケストレーター／ワーカー	create_orchestrator(...)	計画を生成し、ワーカーエージェントを調整します。	プランナー
ディープリサーチ	create_deep_orchestrator(...)	ナレッジの抽出とポリシーチェックを伴う、長期的な調査を行います。	ディープリサーチ
評価器／オプティマイザー	create_evaluator_optimizer_llm(...)	評価器が結果を承認するまで反復します。	評価器／オプティマイザー
スウォーム	create_swarm(...)	OpenAI Swarm と互換性のあるマルチエージェント間の引き継ぎを行います。	スウォーム

耐久性のある実行

execution_engine を temporal に切り替えると、ワークフローのコードを変更せずに、一時停止／再開、再試行、人間からの入力、永続的な履歴を利用できます。アプリと並行してワーカーを実行し、アクティビティをホストします。

from mcp_agent.executor.temporal import create_temporal_worker_for_app

async with create_temporal_worker_for_app(app) as worker:
    await worker.run()

ドキュメント：耐久性のあるエージェント • Temporal バックエンド • 例：examples/temporal。

エージェントサーバー

MCPApp を標準の MCP サーバーとして公開すると、Claude Desktop、Cursor、またはカスタムクライアントからツールやワークフローを呼び出せます。

from mcp_agent.server import create_mcp_server_for_app

@app.tool
def grade_story(story: str) -> str:
    return "Report..."

if __name__ == "__main__":
    server = create_mcp_server_for_app(app)
    server.run_stdio()

ドキュメント：エージェントサーバー • 例：examples/mcp_agent_server。

CLI リファレンス

uvx mcp-agent はプロジェクトのひな形を作成し、シークレットを管理し、ワークフローを検査し、Cloud にデプロイします。

uvx mcp-agent init --template basic             # Scaffold a new project
uvx mcp-agent deploy my-agent                   # Deploy to mcp-agent Cloud

ドキュメント：CLI リファレンス • スタートガイド。

認証

シークレットファイルから API キーを読み込むか、組み込みの OAuth クライアントを使って MCP サーバーのトークンを取得し、保存できます。

# mcp_agent.config.yaml excerpt
oauth:
  providers:
    github:
      client_id: "${GITHUB_CLIENT_ID}"
      client_secret: "${GITHUB_CLIENT_SECRET}"
      scopes: ["repo", "user"]

ドキュメント：高度な認証 • サーバー認証 • 例：examples/basic/oauth_basic_agent。

高度な機能

可観測性と制御

設定を通じて構造化ログと OpenTelemetry を有効にし、トークンの使用状況をプログラムから追跡できます。

# mcp_agent.config.yaml
logger:
  transports: [console]
  level: info
otel:
  enabled: true
  exporters:
    - console

TokenCounter は、エージェント、ワークフロー、LLM ノードのトークン使用状況を追跡します。ウォッチャーをアタッチして更新をストリーミングしたり、アラートをトリガーしたりできます。

# Inside `async with app.run() as running_app:`
# token_counter lives on the running app context when tracing is enabled.
token_counter = running_app.context.token_counter

class TokenMonitor:
    async def on_token_update(self, node, usage):
        print(f"[{node.name}] total={usage.total_tokens}")

monitor = TokenMonitor()
watch_id = await token_counter.watch(
    callback=monitor.on_token_update,
    node_type="llm",
    threshold=1_000,
    include_subtree=True,
)

await token_counter.unwatch(watch_id)

ドキュメント：可観測性 • 例：examples/tracing。

ワークフローの合成

ファクトリーヘルパー（ルーター、並列パイプライン、オーケストレーターなど）を使って AgentSpec を組み合わせ、より高度なワークフローを構築できます。

from mcp_agent.workflows.factory import create_router_llm

# specs are loaded via load_agent_specs_from_file as shown above.
async with app.run() as running_app:
    router = await create_router_llm(
        agents=specs,
        provider="openai",
        context=running_app.context,
    )

ドキュメント：ワークフローの合成 • 例：examples/basic/agent_factory。

シグナルと人間からの入力

承認や追加データのためにワークフローを一時停止できます。Temporal は、オペレーターが実行を再開するまで状態を永続的に保存します。

from mcp_agent.human_input.types import HumanInputRequest

response = await self.context.request_human_input(
    HumanInputRequest(
        prompt="Approve the draft?",
        required=True,
        metadata={"workflow_id": self.context.workflow_id},
    )
)

mcp-agent cloud workflows resume … --payload '{"content": "approve"}' を使って再開します。ドキュメント：エージェントのデプロイ – 人間による入力 • 例：examples/human_input/temporal。

アプリケーション設定

YAML ファイルではなく動的な設定が必要な場合（テスト、マルチテナントホストなど）は、Settings オブジェクトをプログラムから構築できます。

from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(
    execution_engine="asyncio",
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),
        }
    ),
)
app = MCPApp(name="configured_app", settings=settings)

ドキュメント：アプリケーションの設定。

アイコン

エージェントやツールにアイコンを追加すると、画像に対応した MCP クライアント（Claude Desktop、Cursor）で、よりリッチな UI を表示できます。

from base64 import standard_b64encode
from pathlib import Path
from mcp_agent.icons import Icon

icon_data = standard_b64encode(Path("my-icon.png").read_bytes()).decode()
icon = Icon(src=f"data:image/png;base64,{icon_data}", mimeType="image/png", sizes=["64x64"])

app = MCPApp(name="my_app_with_icon", icons=[icon])

@app.tool(icons=[icon])
async def my_tool() -> str:
    return "Hello with style"

ドキュメント：MCPApp のアイコン • 例：examples/mcp_agent_server/asyncio。

MCP サーバーの管理

MCPAggregator または gen_client を使って MCP サーバーへの接続を管理し、統合されたツールセットを公開できます。

from mcp_agent.mcp.mcp_aggregator import MCPAggregator

async with MCPAggregator.create(server_names=["fetch", "filesystem"]) as aggregator:
    tools = await aggregator.list_tools()

ドキュメント：MCP サーバーへの接続 • 例：examples/basic/mcp_server_aggregator。

Cloud へのデプロイ

mcp-agent Cloud にデプロイすると、管理された Temporal 実行、シークレット、HTTPS 対応の MCP エンドポイントを利用できます。

uvx mcp-agent login
uvx mcp-agent deploy my-agent
uvx mcp-agent cloud apps list

ドキュメント：Cloud の概要 • デプロイのクイックスタート • 例：examples/cloud。

例

gallery.md では、実行可能な例、デモ動画、コンセプト別にまとめられたコミュニティプロジェクトをご覧いただけます。各項目には、ローカルで実行するために必要なドキュメントページとコマンドが記載されています。

よくある質問

mcp-agent を使う主なメリットは何ですか？

mcp-agent は、MCP（Model Context Protocol）サーバーが公開する機能を利用して、AI エージェントを構築するための合理化された方法を提供します。

MCP はかなり低レベルですが、このフレームワークはサーバーへの接続、LLM の利用、人間からの入力などの外部シグナルの処理、永続的な実行による状態の保持といった仕組みを担います。そのため、開発者は AI アプリケーションの中核となるビジネスロジックに集中できます。

主なメリット：

• 🤝 相互運用性：任意の数の MCP サーバーが公開するツールを、どのような組み合わせでもエージェントにシームレスに組み込めます。
• ⛓️ 合成可能性とカスタマイズ性：明確に定義されたワークフローを実装しつつ、ワークフローを合成して複合的なワークフローを構築できます。また、モデルプロバイダー、ロギング、オーケストレーターなどを全面的にカスタマイズできます。
• 💻 プログラムによる制御フロー：グラフ、ノード、エッジについて考える必要はなく、開発者はコードを書くだけでよいため、シンプルです。分岐ロジックにはif文を、繰り返し処理にはwhileループを使います。
• 🖐️ 人間の入力とシグナル：エージェントが呼び出せるツールとして公開される人間の入力など、外部シグナルを受け取るためにワークフローを一時停止できます。

mcp-agent を使うには MCP クライアントが必要ですか？

いいえ。mcp-agent が MCPClient の作成を担うため、どこでも利用できます。そのため、Claude Desktop のような MCP ホスト以外でも MCP サーバーを活用できます。

mcp-agent アプリケーションのセットアップ方法は次のとおりです。

MCP-Agent サーバー

mcp-agent アプリケーション自体を MCP サーバーとして公開できます（例を参照）。これにより、MCP クライアントは MCP サーバーの標準ツール API を使って、高度な AI ワークフローを利用できます。これは実質的に、サーバーのサーバーです。

MCP クライアントまたはホスト

mcp-agent を MCP クライアントに直接組み込み、複数の MCP サーバーにまたがるオーケストレーションを管理できます。

スタンドアロン

mcp-agent アプリケーションをスタンドアロンで使用できます（つまり、MCP クライアントの一部としてではなく利用できます）。examplesにあるアプリケーションはすべてスタンドアロンです。

Cloud にデプロイするにはどうすればよいですか？

uvx mcp-agent loginでログインした後、uvx mcp-agent deploy <app-name>を実行します。CLI がプロジェクトをパッケージ化し、シークレットを設定して、耐久性のある Temporal ランタイムを基盤とする MCP エンドポイントを公開します。手順ごとのスクリーンショットと CLI の出力については、[Cloud クイックスタート](https://docs.mcp-agent.com/get-started/ cloud)をご覧ください。

API リファレンスはどこにありますか？

すべてのクラス、デコレーター、CLI コマンドはdocs.mcp-agent.comに記載されています。API リファレンスとllms-full.txtは、LLM（またはあなた）が API の全体像を簡単に取り込めるように設計されています。

ちょっとした豆知識はありますか？

このプロジェクトを silsila（سلسلہ）と名付けることも検討していました。これはウルドゥー語で「連鎖する出来事」を意味します。mcp-agent はより実用的な名前ですが、プロジェクトには silsila への敬意を込めたイースターエッグが今もあります。

貢献

バグ修正、新しい例、ドキュメント、機能のリクエストなど、どのような規模の貢献も歓迎します。CONTRIBUTING.mdから始めるか、ディスカッションを開くか、Discordにお立ち寄りください。

多くのオープンソース貢献者のたゆまぬ努力なしに、mcp-agent は実現できませんでした。ありがとうございます！