【Agent专题】MCP架构实战：开发者必藏！最全MCP智能代理构建指南，附实操解析

Python_金钱豹

于 2025-07-13 10:45:00 发布

阅读量524

点赞数 9

CC 4.0 BY-SA版权

文章标签：架构人工智能 langchain 数据库知识图谱大数据

本文链接：https://blog.youkuaiyun.com/Python_cocola/article/details/149299141

MCP代理正在颠覆智能体的边界，它不再只是“对话专家”，而是真正能与真实应用沟通并完成任务的AI大脑。

从代码调用、任务调度，到插件执行、决策控制，MCP（Model Context Protocol）让大模型从“只会聊天”进化为“能干活的助手”。但——问题也随之而来：

想要搭建一个MCP代理，真的太复杂了！

你不仅要搞懂多层交互架构，还要处理模型、记忆体、协议、工具链之间的配合。如果缺乏系统的知识与实践路径，分分钟踩坑。

所以我们写下这篇全网最全、最硬核的实战指南。

本文将带你从0开始搞懂什么是MCP，它如何架构代理系统，当前主流有哪些框架，并教你一步步用 OpenAI SDK 从头构建出一个属于你自己的 MCP Agent。

最后我们还准备了可运行的实战代码和案例讲解，让你不仅看得懂，还能马上做起来。

MCP 及其核心组件简介

模型上下文协议（MCP） 是一种全新的开放协议，旨在标准化应用程序向大语言模型（LLM）提供上下文信息和工具调用的方式。

你可以把它理解为 AI 的“通用连接器”。MCP 像一个插件系统，服务于不同的 MCP 客户端（例如 Cursor、Claude、Windsurf 等），通过将 Agent 连接到各种数据源和工具，来大幅扩展其能力边界。

MCP 可帮助您在 LLM 之上构建代理和复杂的工作流程。例如，Obsidian 的 MCP 服务器可帮助 AI 助手搜索和阅读 Obsidian 保险库中的笔记。

MCP 的核心遵循客户端-服务器架构，其中主机应用程序可以连接到多个服务器。

在任何通用的 MCP 架构中，通常都包含以下几个核心组件：

MCP 主机：
如 Claude Desktop、Cursor、Windsurf 等 AI 应用，或者其他希望通过 MCP 协议访问数据的智能工具。它们是请求发起方，代表“谁”在使用 MCP。

MCP 客户端：
这些是与 MCP 服务器保持一对一连接的协议客户端，起到通信桥梁的作用。它们负责在主机与功能模块之间传递请求和响应。

MCP 服务器：
是一些轻量级程序，每个服务器负责开放一类标准化能力，例如读取本地文件、查询数据库、调用插件等。这些能力通过 MCP 协议统一暴露，便于接入。

本地数据源：
指的是你计算机上的文件、数据库或服务，MCP 服务器可以安全访问它们。比如浏览器自动化相关的 MCP 服务器，就需要访问你的浏览器实例才能发挥作用。

远程服务：
除了本地资源，MCP 服务器也可以连接外部 API 或基于云的服务，实现更广泛的数据交互与任务执行能力。

MCP Agent 的架构

在 MCP 架构中，MCP 代理 是真正的“智能中枢”，它们通过 MCP 协议实现推理、调用工具、使用记忆，并执行各类任务。

如果说 MCP 协议定义了“应用程序和数据源如何连接语言模型”，那么 MCP 代理就是借助这一结构运行、思考并执行任务的“大脑”——它们既可以自主运行，也可以与你交互协作。

从更高的抽象层面来看，一个 MCP 代理由以下三大核心层级构成：

1）模型上下文层：大脑

在这一层，语言模型（如 GPT-4、Claude）是代理的核心智力来源，负责理解、推理和生成语言。

它通过上下文（可用的工具与资源）和提示（行为指令）进行引导，例如：

“编辑日历时，请优先检查是否存在时区冲突。”

这就像一位全能秘书在执行任务时，始终遵循既定策略和边界。

2）协议层：神经系统

这一层负责“感知世界”和“信息传输”。它是 MCP 代理与外部环境沟通的桥梁，主要包括：

MCP 客户端：如 Cursor、Claude Desktop，承担通信中枢角色；
MCP 服务器：连接特定工具和数据源，如 Gmail、Notion、本地文件系统等；
采用标准化的 JSON-RPC 接口，完成指令下达与结果返回；
管理认证权限、请求响应的协调；
具备容错与重试机制，确保系统稳定运行。

这一层就像人体的神经网络，负责接收指令、传递感知、调动行动。

3）运行时层：肌肉

代理的“行动力”体现在这一层。

这里是工具和 API 的实际运行环境，负责：

执行具体操作（如发邮件、写文档、改代码）；
保持短期工作状态，比如处理草稿、跟踪多步骤任务的中间结果；
管理流程中临时的数据缓存与状态切换。

如果说大脑在思考，神经在传输信息，那么“肌肉”就是执行动作、真正完成工作的实体。

正是这三层架构的协同配合，让 MCP 代理不仅能“理解你的需求”，还能接入外部工具、管理状态并完成真实任务，从“语言模型”进化为“任务执行体”。

当 MCP 代理启动时，客户端会连接到服务器以获取可用的工具、资源和提示。根据用户的请求，它选择要向模型显示的内容。当模型选择作时，客户端通过服务器执行该作，并在此过程中处理授权和数据流。

所有可用于构建MCP代理的框架和SDK

如果你想构建自己的 MCP 代理，市面上已经有不少优秀的框架与工具可以帮助你快速入门。

选择哪种方式，主要取决于以下几个因素：

你使用的编程语言或技术栈
是偏好托管方案（上手简单、但控制力较低），还是自托管部署（灵活自由，但设置稍复杂）
是否开箱即用支持你想连接的工具与应用

以下是目前最流行、支持 MCP 协议的框架与 SDK，一应俱全：

✅ OpenAI Agents SDK

OpenAI 官方推出的 Agent 构建工具，支持 MCP 原生接入，提供如 MCPServerStdio 和 MCPServerSse 等类，适合生产环境使用，是早期 Swarm 实验的成熟版本。
📦 安装命令：pip install openai-agents

✅ Composio with OpenAI

一个轻量级 SDK，用于将 OpenAI Agent 与 Composio 的托管式 MCP 服务器集成，自动完成工具注册、身份验证与通信对接。
📦 安装命令：pip install composio-openai openai

✅ mcp-agent by LastMile AI

一个可组合的简单框架，基于 MCP 协议和工作流模式构建代理，同时兼容 OpenAI 的 Swarm 多代理编排思路，但对模型类型不设限。
📦 安装命令：pip install mcp-agent

✅ MCP Python SDK

官方推出的 Python SDK，完整实现了 MCP 协议规范，提供快速创建 MCP 服务器的类（如 FastMCP）以及客户端连接组件。
📦 安装命令：pip install "mcp[cli]"

✅ MCP TypeScript SDK

官方 TypeScript/Node SDK，适用于 JavaScript/TypeScript 生态，可用 McpServer 快速构建 MCP 服务端及客户端。
📦 安装命令：npm install @modelcontextprotocol/sdk

✅ Google ADK

Google 开源的 Agent 开发工具包（ADK），原生集成 MCP 服务器与工具支持，还可接入其多智能体运行框架。
📦 安装命令：pip install google-adk

✅ CopilotKit MCP 支持

一行命令即可将前端变成 MCP 客户端，快速连接任意 MCP 兼容服务器，实现工具共享、代理协作、多智能体编排。
📦 启动命令：npx copilotkit@latest init -m MCP

✅ LangChain MCP Adapters

将 MCP 工具封装成 LangChain 可识别组件，便于在 LangGraph 等代理工作流中调用，非常适合已有 LangChain 项目的开发者。
📦 安装命令：pip install langchain-mcp-adapters

✅ Strands Agents SDK

由 AWS 开源的 Agent 构建框架，支持 MCP，并兼容主流模型平台：Amazon Bedrock、Anthropic、LiteLLM、Llama、Ollama、OpenAI 等。
📦 安装命令：pip install strands-agents strands-agents-tools

✅ fast-agent

支持 MCP 协议的全功能框架，覆盖工具调用、采样、多模态（图片/PDF）输入等，兼容 OpenAI 和 Anthropic 模型。
📦 安装命令：pip install fast-agent-mcp

✅ PraisonAI

一个主打低代码体验的多智能体框架，支持单行代码接入 MCP，附带丰富文档与示例，支持 Brave、GitHub、Perplexity、Slack 等集成。
📦 安装命令：pip install praisonaiagents mcp

✅ Semantic Kernel

微软推出的智能体编排 SDK，现已通过官方适配器支持 MCP 工具注册与调用，配合 Semantic Kernel Pipeline 使用效果更佳。
📦 安装命令：pip install semantic-kernel

✅ Vercel AI SDK

Vercel 出品的 AI SDK 现已集成 MCP，可在定义 Schema 时，仅拉取显式声明的工具，提升安全与可控性。
📦 示例代码（TypeScript）：

import { experimental_createMCPClient as createMCPClient } from 'ai';import { openai } from '@ai-sdk/openai';const mcpClient = await createMCPClient({  transport: {    type: 'sse',    url: 'https://my-server.com/sse',  },});const response = await generateText({  model: openai('gpt-4o'),  tools: await mcpClient.tools(),  prompt: 'Find products under $100',});

此外，还有一些项目如 Agent-MCP，因社区活跃度与成熟度较低，本文暂不推荐。

如果你偏好图形化使用 MCP，还可以使用以下 MCP 客户端软件来对接 MCP 服务器：

Cursor
Claude Desktop
Windsurf
Cline
Witsy 等

想查看更多客户端？可以前往官方列出的 20+ MCP Clients 清单一探究竟。

使用OpenAI SDK构建您的第一个MCP的Agent

OpenAI Agents SDK 是 OpenAI 于 2025 年 3 月推出的官方开源框架，旨在帮助开发者构建由 OpenAI 模型驱动的智能代理。

这些代理不仅可以调用工具，还支持内存管理、函数调用、流式输出、重试机制等完整的工作流能力，真正实现“能思考、会执行”的智能体。

除了基础功能，你还可以使用适配器（如 composio_openai）来更灵活地控制 MCP（Model Compatibility Protocol）生态。该适配器允许 OpenAI Agents SDK 客户端与 MCP 协议兼容的服务器通信，进一步拓展能力边界：

⚡ 将 OpenAI 代理连接到任意 MCP 服务器提供的工具
⚡ 在代理内部直接调用如 Composio Cloud 等平台上的工具
⚡ 在保留 OpenAI 原生代理运行时的基础上，实现对 MCP 的兼容扩展

让我们从零开始，使用原生 OpenAI SDK 构建第一个 MCP Agent！

第 1 步：准备环境

请确保你已安装 Python 3.8 及以上版本，并拥有 OpenAI API Key。

第 2 步：创建项目并设置虚拟环境

在开发过程中使用虚拟环境（virtualenv）可以避免全局依赖冲突，推荐启用。

# macOS / Linux:python3 -m venv env        # 创建名为 'env' 的本地虚拟环境source env/bin/activate    # 激活虚拟环境# Windows:python -m venv env.\env\Scripts\activate     # 在 PowerShell 或 CMD 中激活

激活后你会在终端前缀看到 (env)，代表环境已就绪。

项目结构如下：

mcp-openai-agent/├── agent.py                 # 定义带工具能力的 OpenAI 代理├── run_agent.py             # 主运行入口├── requirements.txt         # 依赖包清单├── .env                     # 存储 API 密钥与配置└── README.md

第 3 步：安装依赖并配置 API Key

本项目依赖两个关键库：

openai-agents：官方 OpenAI SDK，内置支持函数调用、内存、工具使用等
python-dotenv：加载 .env 文件中的环境变量，方便管理密钥等信息

安装命令如下：

pip install openai-agents python-dotenv

安装完后，将当前虚拟环境下的依赖写入 requirements.txt：

pip freeze > requirements.txt

这样就可以通过以下命令快速复现依赖环境：

pip install -r requirements.txt

为避免将敏感文件上传 GitHub，请添加 .gitignore，忽略虚拟环境目录及 .env 文件。

接下来，在 .env 文件中添加你的 OpenAI API Key：

OPENAI_API_KEY=你的 OpenAI 密钥

第 4 步：获取 MCP Server 地址

我们将使用 Composio 提供的 MCP Server，因为它支持内置认证（OAuth、API Key、JWT、Basic Auth），免去了你自己构建登录系统的麻烦。

Composio 提供完全托管的服务器，已经集成了 250+ 工具（如 Gmail、Slack、Notion、Linear 等），并支持本地或远程运行。每个 MCP 工具都附带以下信息：

当前活跃用户数
工具版本和更新时间
所有支持的动作（actions）
安装指引（TypeScript、Python 等）

同时支持的主机包括：Claude（Mac）、Windsurf、Cursor 等。

第 5 步：编写 Agent 主体（agent.py）

我们将在 agent.py 中定义主代理逻辑。它将连接 MCP 工具服务器，并返回 Agent 与 Server 实例。

import osimport openaifrom agents import Agentfrom agents.mcp import MCPServerSsefrom dotenv import load_dotenvload_dotenv()openai.api_key = os.getenv("OPENAI_API_KEY")TOOL_URL = os.getenv("MCP_TOOL_URL")# return openai agent connected to mcp tooldef build_agent():    mcp_server = MCPServerSse({"url": TOOL_URL})    agent = Agent(        name="GitHub Agent",        instructions="You help the user manage GitHub by creating issues, updating repos, and handling PRs using the connected GitHub tool.",        mcp_servers=[mcp_server],    )    return agent, mcp_server

代码说明：

MCPServerSse(...)：通过 SSE 协议连接 MCP 工具服务器
Agent(...)：实例化代理，包括名称、指令说明、可连接的 MCP 工具列表
build_agent()：返回一个连接好 MCP 工具的代理实例和服务器对象

你需要在 .env 文件中添加 MCP 工具的 URL，例如：

MCP_TOOL_URL=https://mcp.composio.dev/github/sse?customerId=xyz

第 6 步：运行代理（run_agent.py）

接下来，我们在 run_agent.py 中添加主执行逻辑，用于启动代理完成任务。

import asynciofrom agent import build_agentfrom agents import Runner# main task with the use caseTASK = "Create an issue in the repository 'Anmol-Baranwal/mcp-agents' with the title 'Feat: MCP Server Implemented' and body 'just testing stuff.'"async def main():    agent, mcp_server = build_agent()    try:        await mcp_server.connect()        result = await Runner.run(agent, TASK)        print("✅ Final Output:\n", result.final_output)    finally:        await mcp_server.cleanup()if __name__ == "__main__":    asyncio.run(main())

代码说明如下：

main()：以异步方式运行整个代理工作流
build_agent()：初始化 agent 与 MCP server
await mcp_server.connect()：连接远程 MCP 工具服务器
Runner.run(...)：发送任务，自动处理函数调用、工具选择、重试机制等
result.final_output：代理完成任务后的最终结果
cleanup()：优雅关闭连接

第 7 步：执行结果与连接验证

当你运行 run_agent.py，系统将尝试建立到 GitHub 工具的连接。第一次使用时，你需要在浏览器中打开 OAuth 链接进行授权。

验证连接成功后，可再次运行脚本，代理就能真正创建 GitHub issue。请确保目标仓库为公开状态，否则可能由于权限不足导致操作失败。

恭喜！你已从零成功构建了一个兼容 MCP 协议的 OpenAI 代理。

一旦 GitHub 工具通过 Composio 完成认证，你就可以通过 Agent 实现以下功能：

创建或关闭 GitHub Issue
更新仓库描述、Metadata
协助处理 PR 流程
整合至开发者自动化流程中

我尝试了多种方式，每次都能顺利完成任务。

一些带有源代码的真实示例

在本示例中，我们将构建一个可以汇总博客文章为推文的智能代理（Agent）。该代理由 OpenAI LLM 驱动，能够访问本地文件系统和网页内容，并将结果浓缩为一句 Twitter 内容。

所有需要的服务器组件已经包含在仓库中，因此你需要先克隆项目。

此外，请记得在 mcp-agent/examples/basic/mcp_basic_agent/mcp_agent.secrets.yaml 中添加你的 OpenAI API 密钥和 Anthropic API 密钥。

示例代理代码

import asyncioimport osfrom mcp_agent.app import MCPAppfrom mcp_agent.agents.agent import Agentfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLMapp = MCPApp(name="hello_world_agent")async def example_usage():    async with app.run() as mcp_agent_app:        logger = mcp_agent_app.logger        # 创建一个支持读取文件系统与抓取网页的代理        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 工具服务器        )        async with finder_agent:            # 自动初始化 MCP 服务器并加载工具            tools = await finder_agent.list_tools()            logger.info(f"Tools available:", data=tools)            # 绑定一个 OpenAI 增强型 LLM            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)            # 读取 README.md 文件内容            result = await llm.generate_str(                message="Show me what's in README.md verbatim"            )            logger.info(f"README.md contents: {result}")            # 抓取博客文章前两段内容            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}")            # 总结成一条 128 字符推文            result = await llm.generate_str("Summarize that in a 128-char tweet")            logger.info(f"Tweet: {result}")if __name__ == "__main__":    asyncio.run(example_usage())

以下是对上述代码模块的简要解析：

MCPApp
管理整个 MCP 运行环境，处理事件循环、日志等核心框架。
OpenAIAugmentedLLM
使用 OpenAI 模型（默认 GPT-4o）实现智能任务规划与工具交互能力。
Agent（智能代理）
创建一个名为 finder 的代理，拥有以下功能：
- 接入两个 MCP 工具服务器：fetch（抓取网页内容）和 filesystem（读取本地文件）；
- 根据指令读取文件或访问 URL，返回对应内容。
异步运行代理任务：
- 自动初始化所连接的 MCP 服务器；
- 列出并记录当前可用的工具；
- 绑定一个具备工具调用能力的 OpenAI LLM；
- 执行以下三个任务：
1. 显示 README.md 文件内容；
2. 提取 Anthropic 博客页面前两段文字；
3. 将博客摘要浓缩成一条 Twitter 推文（128 字符内）。
日志输出
每一步的结果都会通过日志打印，便于调试和结果回溯。

OpenAI SDK：使用 MCP 服务器发送电子邮件。您需要从 Composio Gmail MCP 服务器生成 SSE URL。让我们创建一个可以使用 OpenAI SDK 发送电子邮件的代理。

import asyncioimport osfrom dotenv import load_dotenvimport openaifrom agents import Agent, Runnerfrom agents.mcp import MCPServerSse
load_dotenv()
openai.api_key = os.getenv("OPENAI_API_KEY")
TOOL_URL = os.getenv("MCP_TOOL_URL")async def main():    gmail_server = MCPServerSse({"url": TOOL_URL})    try:        await gmail_server.connect()        agent = Agent(            name="Gmail Agent",            instructions="You help the user manage their emails using the connected Gmail tool.",            mcp_servers=[gmail_server]        )
        task = "send an email to hi@anmolbaranwal.com with subject 'Hello from MCP Agent' and body 'This is a test email sent via the Gmail MCP server.'"        result = await Runner.run(agent, task)        print(result.final_output)    finally:        await gmail_server.cleanup()if __name__ == "__main__":    asyncio.run(main())

尽管 MCP（Model Context Protocol）仍在不断发展完善中，但其核心理念和架构设计已趋于稳定。随着更多边缘案例被探索，未来还会诞生更多新框架和工具，拓展 MCP 的应用边界。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

在这里插入图片描述