/ 目录 / 演练场 / mcp-agent
← 全部服务器 ↗ GitHub
● 社区 lastmile-ai ⚡ 即开即用

mcp-agent

作者 lastmile-ai · lastmile-ai/mcp-agent

基于 MCP 的生产级代理模式（Orchestrator、Router、Evaluator、Swarm）— 可选支持 Temporal 持久化。

mcp-agent 来自 lastmile-ai，是一个 Python 框架，用于使用经过验证的模式组合 MCP 代理：Parallel、Router、Intent Classifier、Orchestrator-Workers、Deep Research、Evaluator-Optimizer、Swarm。无论你在 asyncio 还是 Temporal 上运行，都提供相同的 API 来实现持久执行。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

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

为研究任务构建 orchestrator-workers 代理

👤 构建多步骤代理的 Python 开发者 ⏱ ~60 min advanced

何时使用： 任务太大，单个 LLM 无法完成，但可以分解为并行的子任务（例如研究 10 个竞争对手）。

前置条件
  • Python 3.10+ — 标准
  • 代理要使用的 MCP 服务器 — 在 mcp-agent 配置中列出它们
步骤
  1. 定义 worker 代理
    创建 2 个 Agent — scraper 使用 firecrawl 服务器，writer 使用文件系统。为每个提供集中的指令集。✓ 已复制
    → 两个 Agent 实例
  2. 连接 orchestrator
    使用 create_orchestrator(planner_llm=..., workers=[scraper, writer]) 包装它们。最大迭代次数 = 10。✓ 已复制
    → Orchestrator 返回计划和执行句柄
  3. 运行真实任务
    运行：'研究 GitHub 上排名前 5 的 Postgres MCPs。对于每一个，写一份 1 页的总结到 ./reports/<slug>.md'✓ 已复制
    → 生成 5 个内容连贯的文件

结果： 一个并行化的代理，完成本来需要 30 分钟的手工多步骤工作在 3-5 分钟内完成。

注意事项
  • Orchestrator 创建的子任务过多或过少 — 给规划器 LLM 明确指导：'分解为 3-7 个子任务，每个工作量 <5 分钟'
  • Worker 重复获取相同数据 — 通过应用状态共享缓存，或在计划中显式传递结果
搭配使用： mcp-use · fastmcp

为高质量写作构建 evaluator-optimizer 代理

👤 发布内容管道的团队 ⏱ ~45 min advanced

何时使用： LLM 初稿太粗糙无法用于生产。你需要一个自动的'持续迭代直到通过'循环。

步骤
  1. 定义写手和评估器
    写手：根据简报生成草稿。评估器：根据 [准确性、清晰度、语气] 评分 1-5，附上原因。✓ 已复制
    → 定义了两个代理
  2. 设置循环
    使用 EvaluatorOptimizer，min_rating=4（所有标准），max_iterations=5。将简报作为输入。✓ 已复制
    → 循环运行，日志中可见迭代
  3. 观察收敛
    对 10 个不同的简报，记录：初始分数、最终分数、所需迭代次数。有永不收敛的简报吗？✓ 已复制
    → 统计数据和已识别的异常值

结果： 不需要人工审核循环，输出质量始终如一。

注意事项
  • 评估器太宽松，第 1 次迭代退出，输出平庸 — 校准评估器 — 在系统提示中给它 3 个示例输入和预期分数
  • max_iterations 较高时，预算爆炸 — 限制在 3-4；如果到那时还没收敛，问题在简报，不在模型

使用 Temporal 使代理工作流持久化

👤 在生产环境运行代理的平台工程师 ⏱ ~90 min advanced

何时使用： 代理流长时间运行（分钟到小时），无法承受节点宕机时从头重启。

前置条件
  • 运行中的 Temporal 集群 — 本地用 temporal server start-dev，生产用 Temporal Cloud 或自建
步骤
  1. 注解工作流
    使用 @app.workflow 装饰现有 orchestrator 函数，各步骤用 @app.workflow_task 装饰。✓ 已复制
    → 工作流在 Temporal 中注册
  2. 切换执行器
    在应用配置中改 executor: 'temporal'。注册 worker。启动工作流。✓ 已复制
    → Temporal UI 显示运行中的工作流
  3. 验证崩溃恢复
    在工作流运行中途杀死 Python worker。重启它。确认工作流从最后完成的活动恢复。✓ 已复制
    → 没有重复工作，没有丢失状态

结果： 代理工作流能度过进程重启、部署和 OOM — 对于耗时数小时的研究任务至关重要。

注意事项
  • Activity 不是幂等的，恢复导致双写 — 每个 activity 都必须安全可重试 — 在外部写操作上使用幂等性密钥

组合

与其他 MCP 搭配，撬动十倍杠杆

mcp-agent + mcp-use

mcp-use 用于客户端管道 + mcp-agent 用于工作流模式

使用 mcp-use 连接文件系统和 git。用 mcp-agent 的 Orchestrator 包装来规划多仓库重构。✓ 已复制
mcp-agent + fastmcp

用 FastMCP 构建自定义 MCP，由 mcp-agent 工作流使用

通过 FastMCP 公开内部排名 API，然后在 mcp-agent Router 中使用它来分类客户问题。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
MCPApp config_path or config object 顶层 — 每个进程一个 free
Agent(name, instruction, server_names) 配置了它可以使用哪些 MCP 服务器 定义每个 worker/角色 free
AugmentedLLM.generate / generate_str / generate_structured messages，可选 schema 直接 LLM 调用，MCP 工具已连接 LLM tokens
create_parallel_llm / create_router_llm / create_orchestrator agents + planner LLM 实例化一个内置模式 LLM tokens × 模式扇出倍数
@app.workflow / @app.workflow_task 在 async 函数上的装饰器 使用 Temporal 执行器时 free
EvaluatorOptimizer writer_agent, evaluator_agent, min_rating, max_iterations 质量至关重要的输出 成本较高 — 限制 max_iterations

成本与限制

运行它的成本

API 配额
mcp-agent 没有额度限制；LLM + MCP 成本是直接的
每次调用 Token 数
模式会放大 — 有 5 个 worker 的 Parallel 是单个 LLM 调用的 5 倍 token
费用
免费库；LLM + 可选的 Temporal 基础设施是实际成本
提示
Orchestrator 这样的模式会扇出 — 在规划器 LLM 的系统提示中放一个显式的 token 预算检查

安全

权限、密钥、影响范围

凭据存储： LLM 密钥用环境变量 + 每个 MCP 的特定密钥
数据出站： LLM 提供商 + 各配置的 MCP 服务器 + Temporal（如果启用）

故障排查

常见错误与修复

工作流启动时挂起，无日志

MCP 服务器启动失败。启用调试日志：在配置中加 logger: {level: 'DEBUG'}。通常是服务器项中命令/env 错误。

Orchestrator 返回计划但没有执行

你调用的是 .plan() 而不是 .generate()。使用完整的方法来执行计划。

Temporal 工作流以序列化错误失败

Activity 返回了不可序列化的对象（例如 MCP 客户端句柄）。Activity 必须返回 JSON 可序列化的值。

LLM 忽略可用工具并幻觉

系统提示可能被截断或缺少工具列表。升级到工具使用能力强的模型（Sonnet、GPT-4o），运行前在 list_tools 中验证工具。

替代方案

mcp-agent 对比其他方案

替代方案何时用它替代权衡
mcp-use你想要更轻的客户端管道而不需要模式库自己编写编排代码
LangGraph你想要带时间旅行调试的有状态图更多 LangChain 中心；MCP 是附加的
CrewAI你想要固执己见的基于角色的代理团队不同的思维模式；MCP 支持是次要的

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills