MCP代理构建完整指南

MCP代理现在可以与真正的应用程序进行交互并实际完成任务。

然而，构建一个 MCP 代理可能非常复杂。它涉及到许多层、模型、内存、协议和工具。

本指南将详细讲解 MCP 的所有内容。您将了解 MCP 的定义、MCP 代理的架构、所有可用的框架，以及如何使用 OpenAI SDK 从零开始构建自己的 MCP 代理。最后，我还提供了包含源代码的实际示例。

这正是我当初入门时梦寐以求的指南。

涵盖哪些内容？

简而言之，我们将详细介绍这些主题。

MCP及其核心组成部分简介。
MCP代理的架构。
可用于构建 MCP 代理的所有框架和 SDK。
如何使用 OpenAI SDK 构建您的第一个 MCP 代理的分步指南。
一些附带源代码的实际示例。

我将使用来自mcp.composio.dev的 MCP 服务器，因为它们是完全托管的，并且带有内置的身份验证。

我们将涵盖很多内容，那么让我们开始吧。

1. MCP及其核心组成部分的介绍。

模型上下文协议 (MCP) 是一种新的开放协议，它规范了应用程序如何向 LLM 提供上下文和工具。

您可以将其视为人工智能的通用连接器。MCP 作为一个插件系统，可与不同的 MCP 客户端（例如 Cursor、Claude、Windsurf）配合使用，从而允许您通过将其连接到各种数据源和工具来扩展代理的功能。

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

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

核心组件。

以下是任何通用 MCP 服务器的核心组件。

MCP hosts- 像 Claude Desktop、Cursor、Windsurf 或 AI 工具这样的应用程序想要通过 MCP 访问数据。
MCP Clients- 与 MCP 服务器保持 1:1 连接的协议客户端，充当通信桥梁。
MCP Servers- 轻量级程序，每个程序都通过标准化的模型上下文协议公开特定的功能（如读取文件、查询数据库等）。
Local Data Sources- 您计算机上的文件、数据库和服务，MCP 服务器可以安全地访问这些文件、数据库和服务。例如，浏览器自动化 MCP 服务器需要访问您的浏览器才能正常工作。
Remote Services- MCP 服务器可以连接的外部 API 和基于云的系统。

如果您对架构感兴趣，请查阅官方文档。文档中还涵盖了协议层、连接生命周期和错误处理以及整体实现。

2. MCP 代理的架构。

MCP 代理旨在通过 MCP 协议进行推理、访问工具、使用内存和采取行动。

brainsMCP 定义了应用程序和数据源如何连接到语言模型，而 MCP 代理则是能够使用 MCP 提供的结构自主或交互式运行的实际主体。

从宏观层面来看，MCP代理由三层构成：

1）模型上下文层——Brain

语言模型（LLM）是智能体的大脑。
LLM（例如 GPT-4、Claude）处理自然语言请求
在 context （可用工具/资源）和 prompts （行为指导）的指导下
例如：“编辑日历事件时，请先检查时区冲突”

2）协议层——Nervous System

这就是智能体感知外部世界并与外部世界沟通的方式。
包括：
- MCP客户端作为通信桥梁（Cursor、Claude Desktop）
- MCP 服务器作为特定工具（例如 Gmail、Notion、文件系统）的连接器
使用标准化的 JSON-RPC 接口执行工具。
把手：
- 请求/响应协调
- 身份验证和访问
- 错误处理和重试逻辑

3）运行时层——Muscles

这是起作用的部分
工具/API的执行环境
维护操作之间的短期状态（例如草稿消息、中间步骤）

例如：

def send_email(recipient, body):
    # MCP server translates this to Gmail API calls
    gmail_service.users().messages().send(...)

总之：

大脑会思考。
神经系统负责连接和协调。
肌肉执行动作。

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

每一层都相互配合，使整个系统能够正常运作。

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

如果您想构建自己的 MCP 代理，可以使用多种框架和工具来帮助您入门。选择合适的框架和工具取决于：

您使用的编程语言或技术栈。
无论您想要托管式部署（易于使用，但控制较少）还是自托管式部署（控制较多，但设置较多）环境
它是否开箱即用就支持您想要连接的应用程序

以下是支持 MCP 的最流行的框架和 SDK：

OpenAI Agents SDK为使用 OpenAI 平台构建助手提供官方支持。它内置了对 MCP 的支持，例如 `Match`MCPServerStdio和 ` Match` 类。这是 OpenAI 之前用于智能体实验的SwarmMCPServerSse的正式升级版，可用于生产环境。

pip install openai-agents

Composio 与 OpenAI 集成——轻量级 SDK，用于将 OpenAI 代理与 Composio 管理的 MCP 服务器集成。自动处理工具注册、身份验证和通信。

pip install composio-openai openai

LastMile AI 的 mcp-agent是一个简单易用的框架，可用于构建基于 MCP 和简单工作流模式的智能体。它还负责管理 MCP 服务器连接的生命周期，让您无需为此操心。此外，它以与模型无关的方式实现了 OpenAI 的 Swarm 多智能体编排模式。

pip install mcp-agent

MCP Python SDK——官方 Python SDK，实现了完整的 MCP 规范。它提供服务器类（例如FastMCP），用于快速创建 MCP 服务器（定义工具、提示、资源），以及客户端类，用于连接服务器。

pip install "mcp[cli]"

MCP TypeScript SDK - 官方的 TypeScript/Node SDK，实现了完整的 MCP 规范。它允许您使用McpServerJavaScript/TypeScript 构建 MCP 服务器和 MCP 客户端。

npm install @modelcontextprotocol/sdk

Google ADK——谷歌的开源代理开发工具包 (ADK) 内置了对 MCP 服务器和工具的支持。您还可以将其与谷歌的多代理运行时集成。

pip install google-adk

CopilotKit MCP 支持——只需一条命令即可提供内置的 MCP 集成。您可以将前端转换为 MCP 客户端，与任何兼容的 MCP 服务器通信。这使您的应用程序能够访问共享工具集、与外部代理协调并接入多代理工作流。

npx copilotkit@latest init -m MCP

LangChain MCP 适配器——一个轻量级封装器，可将 MCP 工具转换为可与 LangGraph 代理一起使用的LangChain 工具。它有助于将 MCP 工具集成到基于 LangChain 的工作流中。

pip install langchain-mcp-adapters

Strands Agents SDK是一款 AWS 开源 SDK，用于以模型驱动的方式构建 AI 代理。它内置 MCP 支持，并支持 Amazon Bedrock、Anthropic、LiteLLM、Llama、Ollama、OpenAI 和自定义提供程序。

pip install strands-agents strands-agents-tools

fast-agent是一个框架，它提供完整、经过端到端测试的 MCP 特征支持，包括采样。它同时支持 Anthropic 模型（Haiku、Sonnet、Opus）和 OpenAI 模型（gpt-4o/gpt-4.1 系列、o1/o3 系列）。

fast-agent它支持多模态，通过提示、资源和 MCP 工具调用结果，为 Anthropic 和 OpenAI 端点提供图像和 PDF。

pip install fast-agent-mcp

PraisonAI是一个 Python 多智能体框架，它提供简洁易用的低代码设计。它通过 API 提供一行 MCP 集成，方便MCP(...)智能体使用。PraisonAI 提供清晰的文档，其中包含连接 Brave、GitHub、Perplexity 和 Slack 等外部工具的代码示例。

pip install praisonaiagents mcp

微软面向 AI 代理的开源编排 SDK Semantic Kernel现已通过官方适配器支持 MCP 工具。您可以在 Semantic Kernel 管道中注册并调用 MCP 工具。官方博客上提供了详细的分步集成指南。

pip install semantic-kernel

Vercel AI SDK - AI SDK 现在支持 MCP，可将您的应用程序连接到不断增长的工具和集成生态系统。当您定义 MCP 时 schemas，即使服务器提供了更多工具，客户端也只会拉取显式定义的工具。

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(), // use MCP tools
  prompt: 'Find products under $100',
});

还有其他选项，例如Agent-MCP，但由于它们的星级不高（星级越高，信誉度越低），所以我决定不将它们列入其中。

您还可以使用Cursor、Claude Desktop、Windsurf、Cline和Witsy等 MCP 客户端来集成 MCP 服务器。如果您想了解更多，请查看官方提供的20 多个 MCP 客户端列表。

4. 使用 OpenAI SDK 构建您的第一个 MCP 代理的分步指南。

OpenAI Agents SDK是一个官方开源框架，于 2025 年 3 月发布，旨在帮助开发者构建由 OpenAI 模型驱动的强大且能使用工具的智能体。它为智能体工作流程提供第一方支持，例如工具调用、内存管理、流式传输、重试等等。

您还可以使用适配器composio_openai来更好地控制您的 MCP 生态系统。例如，此适配器允许 OpenAI Agents SDK 客户端与符合 MCP 标准的服务器通信，从而实现以下功能：

⚡ 将您的 OpenAI 代理连接到任何 MCP 服务器上可用的工具
⚡ 直接在您的代理中使用来自 Composio Cloud 等平台的工具
⚡ 继续使用 OpenAI 的代理运行时，同时使其与 MCP 兼容

让我们从头开始构建它（只使用 OpenAI SDK）。

第一步：先决条件。

请确保您的系统中安装了Python 3.8 或更高版本。
您需要一个 OpenAI API 密钥。

步骤二：设置项目

创建虚拟环境意味着为你的 Python 项目设置一个隔离空间，所有依赖项都安装在本地（而不是系统范围内）。这可以避免版本冲突，并保持全局 Python 安装的整洁。

创建虚拟环境并非绝对必要，但强烈建议这样做。那么，让我们创建一个吧。

# macOS / Linux:
python3 -m venv env  # creates a folder called 'env' with a local Python setup
source env/bin/activate  # activates that environment

# Windows:
python -m venv env    # same as above
.\env\Scripts\activate  # activates it (Windows PowerShell / CMD)

(env)当您在终端提示符开头看到该提示符时，就表示它已激活。

以下是我们将要遵循的项目结构。

mcp-openai-agent/
├── agent.py                 # Defines the OpenAI agent with tool usage
├── run_agent.py             # Entry point to run your agent
├── requirements.txt         # Python dependencies
├── .env                     # API keys and config
└── README.md

步骤 3：安装所需软件包并设置 API 密钥

我们需要两个主要软件包：

openai-agents：OpenAI 官方 SDK，用于构建具有内存、函数调用、重试和流式传输功能的工具型代理。
python-dotenv：将文件中的环境变量加载.env到 Python 中，这对于管理 API 密钥和密钥非常有用。

请使用以下命令安装这些程序。

pip install openai-agents python-dotenv

安装完依赖项后，运行：

pip freeze > requirements.txt

这会将虚拟环境中所有已安装的软件包（包括版本）写入一个文件requirements.txt。之后，您可以使用以下命令使用此文件：

pip install -r requirements.txt

为方便起见，请.gitignore在根目录中添加一个，以避免推送虚拟环境目录和.env文件。

请在文件中添加您的OpenAI API 密钥.env。这将是命名规则。

OPENAI_API_KEY=api_key_value

步骤 4：获取 MCP 服务器 URL

我们将使用 Composio 作为 MCP 服务器，因为它们内置了身份验证功能。您可以在mcp.composio.dev上找到列表。

⚡ 内置身份验证支持 OAuth、API 密钥、JWT 和基本身份验证。这意味着您无需创建自己的登录系统。

⚡ 全托管服务器无需复杂的设置，即可轻松将 AI 代理与 250 多个工具（如 Gmail、Slack、Notion、Linear 等）集成。

⚡ 可根据您的配置需求在本地或远程运行。

每个选项都会显示活跃用户总数、当前版本、最近更新时间以及所有可执行的操作。

您可以使用找到安装说明TypeScript，Python它支持 Claude (MacOS)、Windsurf (MacOS) 和 Cursor 作为 MCP 主机。

我们将在下一步中使用此网址。

步骤 5：构建代理

让我们在这里编写主代理代码agent.py。我们将设置一个基于 OpenAI 的代理，该代理连接到外部工具（MCP 服务器），并返回代理和服务器实例。

import os
import openai
from agents import Agent
from agents.mcp import MCPServerSse
from dotenv import load_dotenv

load_dotenv()

openai.api_key = os.getenv("OPENAI_API_KEY")

TOOL_URL = os.getenv("MCP_TOOL_URL")

# return openai agent connected to mcp tool
def 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({"url": TOOL_URL})：使用提供的 URL 通过服务器发送事件 (SSE) 连接到 MCP 工具。
Agent(...)使用以下方式实例化代理：
- 名称（"MCP Agent"）
- 行为指导（帮助用户）
- mcp_servers可以使用的列表（在这种情况下，只需要一个）。
该build_agent函数同时返回代理和 MCP 服务器实例。

您需要在配置文件中添加 Composio 中的 MCP 工具 URL .env。它看起来会像这样。

MCP_TOOL_URL=https://mcp.composio.dev/<tool>/sse?customerId=xyz

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

我以GitHub服务器为例，你也可以选择其他任何服务器。

让我们把代码添加到run_agent.py. 中。这将作为运行我们 MCP 代理的主要入口点。

import asyncio
from agent import build_agent
from agents import Runner

# main task with the use case
TASK = "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())

以下是代码各部分的功能：

async def main()整个代理循环是异步运行的。
agent, mcp_server = build_agent()：调用来自的函数agent.py。
await mcp_server.connect()：与 MCP 工具服务器建立实时连接。
await Runner.run(agent, TASK)：这是智能体开始推理和使用工具的地方。
- 将任务和上下文发送给 LLM（例如 GPT-4）。
- 让模型决定调用哪个（哪些）工具。
- 处理重试、工具调用和中间步骤。
result.final_output代理完成任务后，这就是最终响应。您可以将其记录、通过 API 返回或集成到您的应用程序中。
await mcp_server.cleanup()这样可以确保 MCP 连接正常关闭。

步骤 6：最终输出

在中run_agent.py，我要求它“在存储库中创建一个问题，Anmol-Baranwal/mcp-agents标题为‘Feat: MCP Server Implemented’，正文为‘just testing stuff’。

由于当前没有活动连接，系统将首先建立一个连接。您需要将 OAuth URL 复制到浏览器中进行身份验证。

您可以调整指令以检查连接是否已建立。然后重新运行代理以完成任务。请确保存储库是公开的，否则由于权限不足，将无法创建问题。

太棒了！🎉 您已成功从零开始创建了一个 MCP 代理。

一旦 GitHub 工具通过 Composio 连接并完成身份验证，您就可以要求代理执行create GitHub issues、update repository descriptions or metadata甚至assist with pull requests and dev workflows。

我尝试了好几种不同的方法，每次都成功了。

在下一节中，我们将构建两个有用的 MCP 代理，每个代理都采用不同的框架。

5. 一些附带源代码的实际示例。

虽然 OpenAI 非常好用，但还有其他框架可供选择。这里有两个构建 MCP 代理的实用示例，第一个使用 Agent-MCP，另一个使用 OpenAI SDK。

✅ MCP-Agent：查找文件、阅读博客并撰写推文

我们将使用mcp-agent，这是一个可组合的框架，用于使用 MCP 和简单的工作流模式构建代理。

它还处理了管理 MCP 服务器连接生命周期的复杂性，并以与模型无关的方式实现了 OpenAI 的 Swarm 多智能体编排模式。

它也是最轻量级的，更接近于代理模式库而非框架。简而言之，您可以构建任何类型的 AI 应用：多代理协作工作流、人机协同工作流、RAG 流水线等等。

您可以使用 uv（推荐）或 pip 进行安装。

uv add "mcp-agent" 

# OR
pip install mcp-agent

这里有一个示例代理，可以将一篇博客文章总结成一条推文。服务器已包含在代码库中，因此您需要克隆该代码库。您需要在代码库中添加OpenAI API 密钥和Anthropologie API 密钥。mcp_agent.secrets.yamlmcp-agent\examples\basic\mcp_basic_agent

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

以下是对上述代码的简要说明。

MCPApp管理整个 MCP 环境。
OpenAIAugmentedLLM集成 OpenAI 模型来解释指令并与工具进行交互。
定义一个名为finder“
- 该代理可以访问两个 MCP 服务器：（fetch用于获取 Web 内容）和filesystem（用于读取本地文件）。
- 它按照指令读取文件或获取 URL 并返回信息。
异步运行代理：
- 自动初始化MCP服务器。
- 列出可用工具（服务器）并记录其日志。
- 将 OpenAI 支持的 LLM（默认 GPT-4o）附加到代理。
使用代理执行任务：
- 读取本地文件的内容README.md。
- 从博客网址中获取并提取前两段。
- 将这篇博客的内容概括成一条简短的推文。
记录每个步骤的输出结果以供审核。

您还可以使用mcp_agent.config.yaml，您可以在快速入门部分查看。

为了这篇博客，我尽量保持简洁。

✅ OpenAI SDK：使用 MCP 服务器发送电子邮件

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

import asyncio
import os
from dotenv import load_dotenv
import openai
from agents import Agent, Runner
from agents.mcp import MCPServerSse

# Load environment variables from the .env file
load_dotenv()

# Set OpenAI API key from .env
openai.api_key = os.getenv("OPENAI_API_KEY")

# MCP tool URL (replace with your actual Notion tool URL from step 4.3)
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]
        )

        # 🔁 You can change the page title and content to suit your project or workflow
        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())