# https://github.com/lastmile-ai/mcp-agent 项目说明书

生成时间：2026-07-21 22:14:10 UTC

## 目录

- [项目概览](#page-overview)
- [Server 模块](#page-src-mcp_agent-server)
- [App 模块](#page-src-mcp_agent-cli-cloud-commands-app)
- [Agents 模块](#page-src-mcp_agent-agents)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Server 模块](#page-src-mcp_agent-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/README.md)
- [pyproject.toml](https://github.com/lastmile-ai/mcp-agent/blob/main/pyproject.toml)
- [src/mcp_agent/cli/README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/README.md)
- [src/mcp_agent/workflows/deep_orchestrator/README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/README.md)
- [src/mcp_agent/workflows/orchestrator/README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/orchestrator/README.md)
- [src/mcp_agent/workflows/parallel/README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/README.md)
- [examples/README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/examples/README.md)
</details>

# 项目概览

## 核心定位与设计理念

`mcp-agent` 是由 lastmile-ai 维护的开源 Python 框架，定位为 **基于 Model Context Protocol (MCP) 构建生产级智能体的运行时**。其核心理念是将 MCP 服务器作为工具与数据源暴露给大语言模型（LLM），并在此之上提供经过工程化打磨的执行原语，使开发者能够专注于业务逻辑而非基础设施细节。

框架在 README 中明确强调"Pythonic API with decorators"的易用性，以及面向生产的特性，例如 **Temporal-backed durability（基于 Temporal 的持久化）** 和 **结构化日志**，这使得长时、多步骤的代理任务具备可恢复性与可观测性。资料来源：[README.md]()。从 v0.0.10 开始引入 `session_id` 并贯穿整个系统，进一步强化了会话追踪能力。资料来源：[v0.0.10 release notes]()。

## 核心架构与组件

`mcp-agent` 采用分层架构，主要由以下几部分组成：

- **MCPApp**：应用入口与生命周期管理容器，负责装配 MCP 服务器连接、LLM 适配器与工作流实例，并通过 `session_id` 串联请求上下文。资料来源：[README.md]()。
- **AugmentedLLM**：LLM 适配层，统一封装不同厂商模型（包括 OpenAI、Anthropic、Azure OpenAI、AWS Bedrock、Google Gemini、Ollama），在 v0.0.21 中加入了 `OllamaAugmentedLLM` 以支持结构化类型生成。资料来源：[v0.0.21 release notes]()、资料来源：[v0.0.15 release notes]()。
- **Workflows（工作流原语）**：包括 `parallel`（并行）、`sequential`（顺序）、`orchestrator-workers`（编排器-工作者）、`router`（路由器）、`evaluator-optimizer`（评估-优化）等模式，封装在 `src/mcp_agent/workflows/` 目录下的独立模块中。资料来源：[src/mcp_agent/workflows/orchestrator/README.md]()、资料来源：[src/mcp_agent/workflows/parallel/README.md]()。
- **CLI**：`src/mcp_agent/cli/` 提供项目脚手架、模板初始化与本地调试命令。资料来源：[src/mcp_agent/cli/README.md]()。

```mermaid
graph TD
    A[MCPApp] --> B[AugmentedLLM]
    A --> C[MCP Servers]
    A --> D[Workflows]
    D --> D1[Parallel]
    D --> D2[Sequential]
    D --> D3[Orchestrator]
    D --> D4[Router]
    D --> D5[Evaluator-Optimizer]
    B --> E[LLM Providers]
    E --> E1[OpenAI]
    E --> E2[Anthropic]
    E --> E3[Bedrock / Gemini / Ollama]
```

## 主要功能特性

1. **多厂商 LLM 支持**：通过 `AugmentedLLM` 抽象层屏蔽差异；v0.0.15 起逐步集成 Azure OpenAI、AWS Bedrock、Google Gemini，v0.0.21 补齐 Ollama。资料来源：[v0.0.15 release notes]()、资料来源：[v0.0.21 release notes]()。
2. **MCP 传输灵活**：自 v0.0.16 起支持 SSE 与 WebSocket 连接，并允许通过 HTTP headers 传递鉴权信息。资料来源：[v0.0.16 release notes]()。
3. **装饰器风格 API**：使用 `@app.workflow` 等装饰器即可将异步函数注册为工作流节点，降低样板代码。资料来源：[README.md]()。
4. **示例库**：`examples/` 目录收录了从基础到高级的示例，覆盖 Basic、Decorator、YAML 三种使用方式。资料来源：[examples/README.md]()。
5. **深度编排**：`deep_orchestrator` 模块针对复杂多步骤任务提供增强的推理与子任务调度能力。资料来源：[src/mcp_agent/workflows/deep_orchestrator/README.md]()。

## 社区生态与发展

社区方面，`mcp-agent` 已被外部项目用于生产场景，例如 **ApeRAG**（基于 mcp-agent 构建的 GraphRAG 平台）。资料来源：[Issue #426]()。与此同时，社区也反馈了若干待完善的方向：

- **流式输出**（streaming token output）仍是关注点，见 Issue #307。
- **LMStudio 等本地推理平台**的支持请求，见 Issue #596。
- **可靠性模式**：包括幂等性、`evaluator-optimizer` 终止条件与部分失败后的恢复，见 Issue #640。
- **安全审计与跨组织代理身份**：分别见 Issue #641 与 Issue #673。
- **缺失的工作流模式**：例如对抗式/辩论模式（两个代理对立论证），见 Issue #668。

版本演进方面，项目目前迭代至 v0.0.21，与上游 MCP v1.8.0 保持兼容；据 v0.0.18 release notes，团队正在 `feature/temporal_prime` 与 `feature/app_server` 分支上筹备重大更新。资料来源：[v0.0.18 release notes]()、资料来源：[v0.0.21 release notes]()。依赖声明见 `pyproject.toml`，可作为对接下游环境的依据。资料来源：[pyproject.toml]()。

---

<a id='page-src-mcp_agent-server'></a>

## Server 模块

### 相关页面

相关主题：[项目概览](#page-overview), [App 模块](#page-src-mcp_agent-cli-cloud-commands-app)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp_agent/server/app_server.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/server/app_server.py)
- [src/mcp_agent/server/app_server_types.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/server/app_server_types.py)
- [src/mcp_agent/server/token_verifier.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/server/token_verifier.py)
- [src/mcp_agent/server/tool_adapter.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/server/tool_adapter.py)
- [src/mcp_agent/server/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/server/__init__.py)
</details>

# Server 模块

## 模块概述

`Server 模块`（路径：`src/mcp_agent/server/`）为 mcp-agent 提供远程化部署能力。它把本地 `MCPApp` 中声明的代理（Agent）、工具（Tool）以及工作流（Workflow）封装为可通过 HTTP/JSON-RPC 调用的端点，使同一份代理配置既能在本地进程内运行，也能被其他进程或组织内的客户端远程复用——这恰好对应社区议题 #673 所讨论的「跨组织编排」场景。模块整体基于异步 Web 框架（FastAPI/Starlette 风格）实现，并通过依赖注入把 `Context`、会话、LLM 等运行时对象绑定到具体请求的处理函数中。资料来源：[src/mcp_agent/server/app_server.py:1-40]()、[src/mcp_agent/server/__init__.py:1-20]()。

## 核心组件

### 主服务入口 app_server.py

`app_server.py` 是模块入口，定义路由表、请求处理流水线以及 `create_app()` 工厂函数。它在启动阶段把 `TokenVerifier`、序列化器与异常处理器以中间件或依赖项的形式挂入应用，使得每一次入站请求在进入业务逻辑前都先经过身份校验——这与社区 #641 安全审计议题所关注的「纵深防御」诉求一致。资料来源：[src/mcp_agent/server/app_server.py:50-130]()、[src/mcp_agent/server/token_verifier.py:20-70]()。

### 类型契约 app_server_types.py

该文件集中存放对外暴露的 Pydantic 模型：包括请求体（携带代理名、输入消息、参数覆盖）、响应体（包含执行结果、token 用量、错误结构）以及会话元数据。所有外部可见字段、必填约束与默认值都由此处单一来源（single source of truth）决定，从而保证 OpenAPI/JSON Schema 与运行时校验保持一致；任何修改都会直接成为对外契约变更。资料来源：[src/mcp_agent/server/app_server_types.py:1-90]()。

### 身份验证 token_verifier.py

`token_verifier.py` 实现 `TokenVerifier` 接口，把签名校验、过期检查、scope 解析等步骤封装为统一函数供 `app_server` 调用。它是社区 #693「调用前信任校验」能力的事实落地点——上层可以在路由层注入「先校验 token → 再校验服务器健康/可信度」的两段式钩子，使不可靠的远端 MCP 服务器在多步工作流中被尽早拦截。资料来源：[src/mcp_agent/server/token_verifier.py:30-100]()。

### 工具适配 tool_adapter.py

`tool_adapter.py` 负责把本地 MCP 工具对象转换为可在远端调用上下文中序列化的形式：入参 JSON 化、出参反序列化、错误包装以及为后续流式响应预留的分片策略。通过该适配层，远端客户端能够透明地复用所有通过 `MCPApp` 注册的工具，而无需关心内部实现。资料来源：[src/mcp_agent/server/tool_adapter.py:15-80]()。

## 请求生命周期

下面以「客户端调用远端 Agent」为例，展示一次请求在 Server 模块内的流转：

```mermaid
sequenceDiagram
    participant C as 客户端
    participant V as TokenVerifier
    participant R as Router
    participant D as 依赖注入
    participant A as Agent

    C->>V: 携带 Bearer Token
    V-->>C: 校验通过/拒绝
    C->>R: POST 请求(代理名 + 输入)
    R->>D: 解析 Context/LLM/Session
    D->>A: 实例化并执行 generate()
    A-->>C: 返回 AgentRunResponse
```

资料来源：[src/mcp_agent/server/app_server.py:130-200]()、[src/mcp_agent/server/app_server_types.py:40-110]()。

## 与社区议题的关联

- **跨组织身份（#673）**：当 Orchestrator 跨边界调用远端 Agent 时，远端 Server 必须经 `token_verifier` 校验调用方身份；`app_server_types` 中用于承载代理身份信息的字段是该能力的数据载体。
- **服务可信度（#693）**：`app_server` 在路由层支持注入预调用校验钩子，与 `token_verifier` 形成「认证 + 信任」纵深防御。
- **流式输出（#307）**：`tool_adapter` 已为流式响应预留分片接口，是社区所关心的 streaming token 路线的承接点。
- **安全审计（#641）**：模块把鉴权、依赖解析、异常包装显式分层，便于第三方审计者快速定位边界。

## 使用要点

1. 通过 `create_app(config=...)` 启动服务，应用读取 `mcp_agent.config.yaml` 中的 server 段以决定监听端口与启用的中间件。资料来源：[src/mcp_agent/server/app_server.py:60-90]()。
2. 自定义鉴权：实现 `TokenVerifier` 子类并在工厂中替换默认注入即可生效。资料来源：[src/mcp_agent/server/token_verifier.py:80-120]()。
3. 扩展工具：在 `tool_adapter.py` 中注册新的序列化器，新工具即被自动暴露给远端。资料来源：[src/mcp_agent/server/tool_adapter.py:60-100]()。

---

<a id='page-src-mcp_agent-cli-cloud-commands-app'></a>

## App 模块

### 相关页面

相关主题：[Server 模块](#page-src-mcp_agent-server), [Agents 模块](#page-src-mcp_agent-agents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp_agent/cli/cloud/commands/app/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/__init__.py)
- [src/mcp_agent/cli/cloud/commands/app/delete/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/delete/__init__.py)
- [src/mcp_agent/cli/cloud/commands/app/delete/main.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/delete/main.py)
- [src/mcp_agent/cli/cloud/commands/app/status/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/status/__init__.py)
- [src/mcp_agent/cli/cloud/commands/app/status/main.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/status/main.py)
- [src/mcp_agent/cli/cloud/commands/app/workflows/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/app/workflows/__init__.py)
</details>

# App 模块

## 概述

`App` 模块是 `mcp-agent` 命令行工具（CLI）中针对云端部署应用的子命令集合，位于 `src/mcp_agent/cli/cloud/commands/app/` 目录下。该模块负责对部署在 `mcp-agent` 云平台上的应用（App）进行生命周期管理，包括查询运行状态、删除应用以及管理工作流配置等操作。`App` 模块作为云命令树的一级分组，将其下各子命令以 Click 命令的形式暴露给用户，使用户能够通过 `mcp-agent cloud app <subcommand>` 的形式对远端应用进行控制 资料来源：[src/mcp_agent/cli/cloud/commands/app/__init__.py:1-50]()。

`App` 模块的核心定位是"远端应用管理平面"，它并不直接实现智能体或 MCP 服务器的运行逻辑，而是封装了与 `mcp-agent` 云服务后端交互的细节，将 HTTP 请求、鉴权、错误处理等通用能力收敛到子命令内部，对外暴露简洁的命令行接口。

## 模块结构与子命令

`App` 模块采用"包级聚合 + 子包分发"的结构。`app/__init__.py` 作为入口文件，使用 Click 框架组织命令组，并在其中声明并注册各子命令 资料来源：[src/mcp_agent/cli/cloud/commands/app/__init__.py:1-80]()。每一个子命令对应一个独立的子目录，子目录内包含 `__init__.py` 与 `main.py` 两个文件，前者负责将命令函数注册到 Click 组中，后者则承载命令的具体实现逻辑。

目前已实现的子命令包括：

| 子命令 | 路径 | 主要职责 |
| --- | --- | --- |
| `delete` | `app/delete/` | 删除指定的云端应用及其关联资源 |
| `status` | `app/status/` | 查询应用运行状态、健康度等元信息 |
| `workflows` | `app/workflows/` | 列出或配置与应用关联的工作流 |

`App` 模块通过 Click 的命令组机制实现可扩展性，新功能只需新增一个子包并在 `app/__init__.py` 中注册即可加入命令树。

### delete 子命令

`delete` 子命令用于永久删除一个云端应用。该命令通过调用云后端的删除接口完成清理工作。命令入口在 `app/delete/__init__.py` 中以 Click 装饰器声明，其内部逻辑（如鉴权、参数解析、确认提示、删除请求）均委托给 `app/delete/main.py` 中的函数 资料来源：[src/mcp_agent/cli/cloud/commands/app/delete/__init__.py:1-40]() 资料来源：[src/mcp_agent/cli/cloud/commands/app/delete/main.py:1-120]()。

### status 子命令

`status` 子命令负责拉取并展示指定应用的当前运行状态，包括部署阶段、运行健康度、最近活动时间等关键指标。该子命令在交互场景中常被用来确认应用是否就绪或排查异常原因 资料来源：[src/mcp_agent/cli/cloud/commands/app/status/__init__.py:1-40]() 资料来源：[src/mcp_agent/cli/cloud/commands/app/status/main.py:1-150]()。`status` 命令通常只读，不会对远端状态产生副作用，因此可以安全地反复调用。

### workflows 子命令

`workflows` 子命令用于查看或管理与某个应用绑定的工作流定义，是连接"应用"与"工作流原语（parallel / sequential / orchestrator-workers 等）"的桥梁 资料来源：[src/mcp_agent/cli/cloud/commands/app/workflows/__init__.py:1-40]()。社区曾讨论过 `mcp-agent` 中缺失 adversarial/debate 等工作流模式（详见 issue #668），`workflows` 子命令未来有望承载更多模式的可视化与下发能力。

## 命令注册与执行流程

下面以 `mcp-agent cloud app status <app_id>` 为例，描述 `App` 模块从 CLI 入口到云后端的调用流程：

```mermaid
flowchart LR
    A[用户输入 CLI] --> B[Click 解析命令树]
    B --> C[app/__init__.py 命令组]
    C --> D[status/__init__.py 注册函数]
    D --> E[status/main.py 业务实现]
    E --> F[构造 HTTP 请求]
    F --> G[调用云后端 API]
    G --> H[解析响应并格式化输出]
    H --> I[回显至终端]
```

`App` 模块不直接处理底层网络与鉴权细节，而是将这部分能力下沉到共享的客户端工具中，从而使每个子命令的实现保持轻量、可读 资料来源：[src/mcp_agent/cli/cloud/commands/app/__init__.py:1-80]()。

## 设计要点与扩展方式

`App` 模块在设计上遵循了几个明确的原则：

1. **关注点分离**：每个子命令对应一个独立子包，命令声明（`__init__.py`）与具体逻辑（`main.py`）解耦，便于单测与维护。
2. **可发现性**：所有子命令都挂载在 `app` 这一 Click 组下，用户可通过 `mcp-agent cloud app --help` 一次性发现全部可用操作。
3. **远端无状态假设**：命令实现假设云端是事实来源（source of truth），本地 CLI 仅作为查询与控制平面，避免在本地持久化应用状态导致不一致。

社区中关于跨组织编排中代理身份验证（issue #673）与 MCP 服务器信任验证（issue #693）的讨论，未来也可能通过新增 `app trust`、`app identity` 等子命令在 `App` 模块中落地，使其在保证远端控制能力的同时，提供更细粒度的安全语义。

## 小结

`App` 模块是 `mcp-agent` 云端 CLI 的核心组成之一，承担"应用生命周期管理平面"的角色。它通过 `delete`、`status`、`workflows` 等子命令为开发者提供查询、清理与配置远端应用的能力，并借助 Click 命令组模式保持良好的扩展性。对于希望将本地工作流发布到 `mcp-agent` 云平台的团队而言，理解 `App` 模块是构建可运维部署流程的第一步。

---

<a id='page-src-mcp_agent-agents'></a>

## Agents 模块

### 相关页面

相关主题：[App 模块](#page-src-mcp_agent-cli-cloud-commands-app)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp_agent/agents/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/__init__.py)
- [src/mcp_agent/agents/agent.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/agent.py)
- [src/mcp_agent/agents/agent_spec.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/agent_spec.py)
- [src/mcp_agent/core/agent_types.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/core/agent_types.py)
- [src/mcp_agent/core/augmented_llm.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/core/augmented_llm.py)
- [src/mcp_agent/mcp_app.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/mcp_app.py)
- [examples/basic/agent_orchestrator/main.py](https://github.com/lastmile-ai/mcp-agent/blob/main/examples/basic/agent_orchestrator/main.py)
</details>

# Agents 模块

## 概述

`mcp_agent/agents/` 子包是 mcp-agent 框架中用于承载"代理（Agent）"抽象的核心模块。它的职责是把一个 LLM（经由 [AugmentedLLM](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/core/augmented_llm.py)）与一组 MCP 服务器工具组合起来，对外暴露统一的 `generate` / `generate_str` 接口，让上层工作流（Parallel、Sequential、Orchestrator-Workers、Router 等）可以以"代理 + 工具"为最小单元进行编排。资料来源：[src/mcp_agent/agents/agent.py:1-40]()
该模块用声明式 `AgentSpec` 与命令式 `Agent` 双形态覆盖常见使用场景，便于在配置文件中描述代理、再在代码中实例化执行。资料来源：[src/mcp_agent/agents/agent_spec.py:1-30]()

## 核心组件

### AgentSpec（声明式代理规格）

`AgentSpec` 是一个轻量级的数据类，用于描述代理的"是什么"，而不关心"怎么运行"。它集中保存代理名、注入的指令、可访问的 MCP 服务器列表，以及按需附加的 LLM 参数。资料来源：[src/mcp_agent/agents/agent_spec.py:30-80]()
通过该 spec，用户既能在 YAML/JSON 里静态声明代理，也能直接在 Python 中以 `AgentSpec(name="finder", instruction="...", server_names=["fetch", "search"])` 的方式构造，再交给 `Agent` 实例化。资料来源：[src/mcp_agent/agents/agent_spec.py:80-120]()

### Agent（运行时代理）

`Agent` 类是真正承载执行上下文的实体，封装以下要素：
- 对底层 [MCPApp](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/mcp_app.py) / Context 的引用，保证 logger、tracer、session_id 在整个调用链中可被复用。资料来源：[src/mcp_agent/agents/agent.py:60-110]()
- 关联的 `AgentSpec`，在实例化时用来解析服务器连接与默认指令。资料来源：[src/mcp_agent/agents/agent.py:110-160]()
- 可选的 `AugmentedLLM` 实例（如 `OpenAIAugmentedLLM`、`AnthropicAugmentedLLM`、`OllamaAugmentedLLM`、`BedrockAugmentedLLM`），由工厂方法按 provider 选择创建。资料来源：[src/mcp_agent/agents/agent.py:160-220]()
- 工具调用循环：调用 `llm.generate(...)` → 解析 tool call → 通过 MCP 客户端分发到对应服务器 → 把 ToolMessage 追加回对话历史。资料来源：[src/mcp_agent/agents/agent.py:220-300]()

`agent.py` 顶部以 dataclass 风格聚合属性，便于在调试时直接读取当前代理绑定的服务器、上下文窗口与多模态能力。资料来源：[src/mcp_agent/agents/agent.py:40-60]()

### 类型与工厂

`core/agent_types.py` 定义代理可识别的 provider 枚举（如 `openai`、`anthropic`、`azure`、`bedrock`、`gemini`、`ollama`），并提供 `resolve_llm_class(...)` 这类映射函数，使 `Agent` 不必硬编码各家 SDK。资料来源：[src/mcp_agent/core/agent_types.py:20-90]()
这层抽象是社区推动云厂商支持（#40、v0.0.15）与本地模型支持（OllamaAugmentedLLM、LMStudio 请求 #596）的关键支点。资料来源：[src/mcp_agent/core/augmented_llm.py:1-40]()

## 生命周期与编排集成

```mermaid
flowchart LR
    A[AgentSpec] --> B[Agent.__init__]
    B --> C[加载 MCP 服务器]
    B --> D[AugmentedLLM 工厂]
    D --> E[OpenAI / Anthropic / Ollama ...]
    B --> F[agent.generate/prompt]
    F --> G{是否需要工具}
    G -- 是 --> H[调用 MCP 工具]
    H --> F
    G -- 否 --> I[返回结构化结果]
```

代理的生命周期由 `Agent.initialize()` 启动，期间会连接 `server_names` 中列出的 MCP 服务器，并构造首个默认 LLM；运行结束后建议显式 `close()` 以释放连接。资料来源：[src/mcp_agent/agents/agent.py:90-110]()
上层 Orchestrator、Router 等高级工作流在 `examples/basic/agent_orchestrator/main.py` 等示例中演示了如何把多个 `AgentSpec` 注册到 App，并由 Orchestrator 按需委派任务。资料来源：[examples/basic/agent_orchestrator/main.py:1-40]()

## 常见使用模式

1. **基础代理**：`Agent(name="...", instruction="...", server_names=[...])` 后调用 `await agent.generate_str(prompt)`。资料来源：[src/mcp_agent/agents/agent.py:240-280]()
2. **多代理编排**：在 `MCPApp` 内声明多个 `AgentSpec`，再交给 Parallel/Sequential/Orchestrator 模式组合。资料来源：[src/mcp_agent/mcp_app.py:60-120]()
3. **自定义 LLM**：通过 `context_aware_get_llm()` 或工厂覆盖注入自定义 `AugmentedLLM` 子类，以适配云厂商或本地模型。资料来源：[src/mcp_agent/core/augmented_llm.py:80-140]()

## 局限与社区关切

- 尚未内置"对抗/辩论"（adversarial/debate）原语，社区 #668 建议扩展 Agents 模块以支持两两代理的相互质询。
- 跨组织编排场景下，缺少代理身份校验机制（#673），当前 `AgentSpec` 未携带 issuer/audience 等声明字段。
- 工具层暂无统一的"信任验证"钩子（#693），需要在上层工作流或 MCP 服务器侧补齐。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：lastmile-ai/mcp-agent

摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Agent identity for cross-org orchestration workflows。

## 1. 安全/权限坑 · 来源证据：Agent identity for cross-org orchestration workflows

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent identity for cross-org orchestration workflows
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/673 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：Missing workflow pattern: adversarial/debate — two agents argue opposite positions

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Missing workflow pattern: adversarial/debate — two agents argue opposite positions
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/668 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：[Security] MCP core: SSRF across all network transports, environment leakage, and unguarded sampling

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] MCP core: SSRF across all network transports, environment leakage, and unguarded sampling
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/721 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安全/权限坑 · 来源证据：feat: Add persistent memory example using Dakera MCP — addresses long-term memory gap (#12)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: Add persistent memory example using Dakera MCP — addresses long-term memory gap (#12)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/713 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：Add TheCrawler as example MCP tool — web extraction with structured errors

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add TheCrawler as example MCP tool — web extraction with structured errors
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/692 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：Resource: Clarvia AEO Scanner — measure MCP server quality for agents using mcp-agent

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Resource: Clarvia AEO Scanner — measure MCP server quality for agents using mcp-agent
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/655 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：[RFC] Cryptographic agent identity for MCP agents via WTRMRK — who is this agent?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[RFC] Cryptographic agent identity for MCP agents via WTRMRK — who is this agent?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/658 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 配置坑 · 来源证据：Feature: Add trust verification for MCP servers before orchestration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Feature: Add trust verification for MCP servers before orchestration
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/693 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 配置坑 · 来源证据：deploy command executes arbitrary user code by importing project main.py in-process

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：deploy command executes arbitrary user code by importing project main.py in-process
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/670 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 配置坑 · 来源证据：get_capabilities_task silently returns exception objects in ServerCapabilities dict under partial server failure

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：get_capabilities_task silently returns exception objects in ServerCapabilities dict under partial server failure
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/671 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 能力坑 · 来源证据：[Question] Reliability patterns under noisy conditions

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Question] Reliability patterns under noisy conditions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/640 | 来源类型 github_issue 暴露的待验证使用条件。

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/lastmile-ai/mcp-agent | README/documentation is current enough for a first validation pass.

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/lastmile-ai/mcp-agent | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/lastmile-ai/mcp-agent | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：Example: Using cowork-to-code-bridge with mcp-agent for local code execution

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Example: Using cowork-to-code-bridge with mcp-agent for local code execution
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/706 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 17. 安全/权限坑 · 来源证据：Live API key printed in plain text to terminal on deploy

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Live API key printed in plain text to terminal on deploy
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/669 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：Security Audit Offer - MCP Agent Framework

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Audit Offer - MCP Agent Framework
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/641 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：Support OAuth Dynamic Client Registration (DCR) for traditional OAuth Providers

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support OAuth Dynamic Client Registration (DCR) for traditional OAuth Providers
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/667 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent | release_recency=unknown

<!-- canonical_name: lastmile-ai/mcp-agent; human_manual_source: deepwiki_human_wiki -->