Mcp Agent

使用简单、可组合的模式，通过 Model Context Protocol 构建高效的 Agent。

示例 | 构建高效的 Agent | MCP

概述

mcp-agent 是一个简单、可组合的框架，可使用 Model Context Protocol 构建高效的 Agent。

说明

mcp-agent 的愿景是：构建 Agent 只需 MCP；与复杂架构相比，简单模式更能可靠地交付高质量 Agent。

mcp-agent 为你提供以下功能：

1. 全面支持 MCP：它_完整_实现了 MCP，并负责管理 MCP 服务连接的生命周期，让你无需操心这些繁琐事务。
2. 高效的 Agent 模式：它以_可组合_的方式实现了 Anthropic 构建高效的 Agent 中介绍的所有模式，让你可以将这些模式串联起来。
3. 持久化 Agent：它既适用于简单的 Agent，也能扩展到基于 Temporal 构建的复杂工作流，让你无需更改 Agent 的任何 API，即可暂停、恢复和还原。

总而言之，这是构建可靠 Agent 应用最简单、最轻松的方式。

我们欢迎各种形式的贡献、反馈，以及帮助改进此项目。

最简示例

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.

一览

文档与使用大模型构建

mcp-agent 的完整文档可在 docs.mcp-agent.com 查阅，其中包括完整的 SDK 指南、CLI 参考和高级模式。本自述文件提供高层概览，帮助你入门。

• llms-full.txt：包含全部文档。
• llms.txt：列出文档中关键页面的站点地图。
• 文档 MCP 服务

目录

• 概览
• 最简示例
• 快速入门
• 为何选择 mcp-agent
• 核心概念
  • MCPApp
  • Agents 与 AgentSpec
  • 增强型大模型
  • 工作流与装饰器
  • 配置与密钥
  • MCP 集成
• 工作流模式
• CLI 参考
• 身份验证
• 高级主题
  • 可观测性与控制
  • 组合工作流
  • 持久执行
  • Agent 服务
  • 信号与人工输入
  • 应用配置
  • 图标
  • 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 密钥添加到 `mcp_agent.secrets.yaml`，或设置 `OPENAI_API_KEY`
uv run main.py

安装

我们建议使用 uv 管理 Python 项目（uv init）。

uv add "mcp-agent"

或者：

pip install mcp-agent

还需添加大模型提供商的可选软件包（例如 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：secrets YAML
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
uv run main.py

下面是一个基本的“finder” Agent，它使用 fetch 和 filesystem 服务来查找文件、阅读博客并撰写推文。示例链接：

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

Agent 输出

为什么使用 mcp-agent？

现有的 AI 框架已经太多了。但 mcp-agent 是唯一专为一种共享协议——MCP——打造的框架。mcp-agent 将 Anthropic 的 Building Effective Agents 模式与开箱即用的 MCP 运行时相结合，让你专注于行为，而非样板代码。团队选择它，是因为它：

• 可组合 —— 每种模式都以可复用的工作流形式提供，你可以自由组合。
• 原生支持 MCP —— 任何 MCP 服务（filesystem、fetch、Slack、Jira、FastMCP 应用）均可直接连接，无需自定义适配器。
• 可用于生产环境 —— 基于 Temporal 的持久性、结构化日志记录、令牌核算和云部署均是内置功能。
• 符合 Python 风格 —— 只需少量装饰器和上下文管理器即可完成所有连接。

文档：欢迎使用 mcp-agent • 有效模式概览。

核心组件

每个项目都围绕单个 MCPApp 运行时构建，它负责加载配置、注册 Agent 和 MCP 服务，并公开工具和工作流。核心组件指南将介绍这些构建模块。

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。

Agents 和 AgentSpec

Agent 将指令与其可调用的 MCP 服务（以及可选函数）关联起来。AgentSpec 定义可以从磁盘加载，并通过工厂辅助函数转换为 Agent 或增强型大模型。

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,
    )

文档：Agents • Agent 工厂辅助函数 • 示例：examples/basic/agent_factory。

增强型 LLM

增强型 LLM 将提供商 SDK 与 Agent 的工具、记忆和结构化输出辅助功能封装在一起。将其附加到 Agent，即可使用 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 服务，或将多个服务聚合到一个外观中。

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。

工作流模式

关键 Agent 模式以 AugmentedLLM 的形式实现。使用工厂辅助函数进行配置，或查看 gallery.md 中列出的可运行项目。

模式	辅助函数	概要	文档
并行（Map-Reduce）	create_parallel_llm(...)	并行分派给多个专家，再汇总生成报告。	并行
路由器	create_router_llm(...) / create_router_embedding(...)	将请求路由到最合适的 Agent、服务或函数。	路由器
意图分类器	create_intent_classifier_llm(...) / create_intent_classifier_embedding(...)	在自动化处理前，将用户输入归类为不同意图。	意图分类器
编排器-工作者	create_orchestrator(...)	制定计划并协调工作者 Agent。	规划器
深度研究	create_deep_orchestrator(...)	进行长期研究，提取知识并检查策略。	深度研究
评估器-优化器	create_evaluator_optimizer_llm(...)	持续迭代，直到评估器批准结果。	评估器-优化器
群体协作	create_swarm(...)	与 OpenAI Swarm 兼容的多 Agent 交接机制。	群体协作

持久化执行

将 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()

文档：持久化 Agent • Temporal 后端 • 示例：examples/temporal。

Agent 服务

将 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()

文档：Agent 服务 • 示例：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 可跟踪 Agent、工作流和 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"}' 恢复。文档：部署 Agent – 人工输入 • 示例：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)

文档：配置应用。

图标

为 Agent 和工具添加图标，让支持图像的 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 Agent。

MCP 的抽象层级较低，而这个框架负责处理连接服务、使用大模型、处理外部信号（如人工输入），以及通过持久化执行支持持久状态等机制。这样，作为开发者，你就可以专注于 AI 应用的核心业务逻辑。

核心优势：

• 🤝 互操作性：确保任意数量的 MCP 服务所公开的工具都能无缝接入你的 Agent。
• ⛓️ 可组合性与可定制性：实现定义明确的工作流，同时支持以可组合的方式构建复合工作流，并全面自定义模型提供商、日志记录、编排器等。
• 💻 程序化控制流：让事情保持简单，开发者只需编写代码，无须考虑图、节点和边。对于分支逻辑，编写 if 语句；对于循环，使用 while 循环。
• 🖐️ 人工输入与信号：支持暂停工作流以等待外部信号，例如人工输入；这些信号会作为 Agent 可调用的工具公开。

使用 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 deploy <app-name>，登录命令为 uvx mcp-agent login。CLI 会打包你的项目、配置密钥，并提供由持久化 Temporal 运行时支持的 MCP 端点。请参阅 [Cloud 快速入门](https://docs.mcp-agent.com/get-started/ cloud)，了解分步骤的截图和 CLI 输出。

API 参考在哪里？

docs.mcp-agent.com 记录了所有类、装饰器和 CLI 命令。API 参考 和 llms-full.txt 专为便于大模型（或你）完整读取整个 API 而设计。

讲个有趣的事实

我曾考虑将这个项目命名为 silsila（سلسلہ），在乌尔都语中意为事件链。mcp-agent 这个名字更加直白，不过项目中仍有一个致敬 silsila 的彩蛋。

贡献

欢迎任何形式的贡献，无论是修复 Bug、添加示例、编写文档还是提出功能请求。请从 CONTRIBUTING.md 开始，也可以发起讨论，或加入 Discord。

mcp-agent 的诞生离不开众多开源贡献者的不懈努力。感谢大家！