5分钟上手mcp-agent：从安装到运行你的第一个AI代理

2026-02-04 05:03:16作者：范垣楠Rhoda

你还在为构建AI代理（Agent）时的复杂配置和多工具集成而头疼吗？本文将带你快速上手mcp-agent，通过简单几步即可搭建并运行你的第一个AI代理，无需深入技术细节，让你轻松体验AI代理的强大功能。读完本文，你将掌握mcp-agent的安装方法、项目初始化流程、配置文件设置以及如何运行和调试你的第一个AI代理。

准备工作

在开始之前，请确保你的环境满足以下要求：

Python 3.10+：mcp-agent基于Python开发，需要Python 3.10或更高版本。
Node.js（可选）：部分MCP服务器（如文件系统服务器）通过npx分发，需要Node.js环境。

安装mcp-agent

使用uvx快速运行CLI

你可以使用uvx工具在不全局安装的情况下直接运行mcp-agent命令，这对于快速试用非常方便：

uvx mcp-agent --version

首次运行时，uvx会将mcp-agent包下载到缓存中，后续运行将瞬间启动。

在项目中添加mcp-agent

如果你希望在项目中集成mcp-agent，可以按照以下步骤进行：

创建项目文件夹并进入：

mkdir mcp-agent-demo
cd mcp-agent-demo

使用uv初始化项目并添加mcp-agent依赖：

uv init
uv add mcp-agent

如果你习惯使用pip，可以执行：

pip install mcp-agent

安装LLM提供商扩展（可选）

mcp-agent支持多种LLM提供商，你可以根据需要安装相应的扩展：

OpenAI：uv add "mcp-agent[openai]" 或 pip install "mcp-agent[openai]"
Anthropic：uv add "mcp-agent[anthropic]"
Azure OpenAI：uv add "mcp-agent[azure]"
AWS Bedrock：uv add "mcp-agent[bedrock]"
Google Gemini：uv add "mcp-agent[google]"

如果你需要支持所有提供商，可以执行：

uv add "mcp-agent[openai,anthropic,azure,bedrock,google]"

初始化项目

完成安装后，我们需要初始化一个mcp-agent项目。在项目文件夹中执行以下命令：

uvx mcp-agent init

该命令会生成项目所需的基本文件结构，包括配置文件和示例代码。初始化完成后，你的项目文件夹中会包含以下关键文件：

mcp_agent.config.yaml：mcp-agent的配置文件
mcp_agent.secrets.yaml.example：密钥配置示例文件
main.py：主程序文件

配置你的AI代理

修改配置文件

首先，将密钥配置示例文件复制为正式的密钥配置文件：

cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml

然后，编辑mcp_agent.secrets.yaml文件，添加你的LLM提供商API密钥。以OpenAI为例：

openai:
  api_key: "你的OpenAI API密钥"

接下来，编辑mcp_agent.config.yaml文件，配置执行引擎和MCP服务器：

execution_engine: asyncio
logger:
  transports: [console]
  level: info

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-demo/
├── mcp_agent.config.yaml
├── mcp_agent.secrets.yaml
├── main.py
├── pyproject.toml
└── uv.lock

其中，main.py是我们实现AI代理逻辑的主要文件。

编写你的第一个AI代理

打开main.py文件，我们将实现一个简单的AI代理，该代理能够连接到MCP服务器，获取工具列表并执行基本操作。以下是一个示例代码：

import asyncio

from mcp_agent.app import MCPApp
from mcp_agent.mcp.gen_client import gen_client
from mcp_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
from mcp_agent.mcp.mcp_connection_manager import MCPConnectionManager

app = MCPApp(name="mcp_hello_world")


async def example_usage():
    async with app.run() as hello_world_app:
        context = hello_world_app.context
        logger = hello_world_app.logger

        logger.info("Hello, world!")
        logger.info("Current config:", data=context.config.model_dump())

        # 使用异步上下文管理器连接到fetch服务器
        async with gen_client(
            "fetch", server_registry=context.server_registry
        ) as fetch_client:
            logger.info("fetch: Connected to server, calling list_tools...")
            result = await fetch_client.list_tools()
            logger.info("Tools available:", data=result.model_dump())

            # 使用持久连接连接到文件系统服务器
            connection_manager = MCPConnectionManager(context.server_registry)
            await connection_manager.__aenter__()

            try:
                filesystem_client = await connection_manager.get_server(
                    server_name="filesystem",
                    client_session_factory=MCPAgentClientSession,
                )
                logger.info(
                    "filesystem: Connected to server with persistent connection."
                )

                fetch_client = await connection_manager.get_server(
                    server_name="fetch", client_session_factory=MCPAgentClientSession
                )
                logger.info("fetch: Connected to server with persistent connection.")

                result = await filesystem_client.session.list_tools()
                logger.info("filesystem: Tools available:", data=result.model_dump())

                result = await fetch_client.session.list_tools()
                logger.info("fetch: Tools available:", data=result.model_dump())
            finally:
                await connection_manager.disconnect_server(server_name="filesystem")
                logger.info("filesystem: Disconnected from server.")
                await connection_manager.disconnect_server(server_name="fetch")
                logger.info("fetch: Disconnected from server.")
                await connection_manager.__aexit__(None, None, None)


if __name__ == "__main__":
    asyncio.run(example_usage())

代码解析

上述代码创建了一个名为"mcp_hello_world"的MCP应用，并实现了以下功能：

初始化MCP应用和上下文
连接到"fetch"和"filesystem"两个MCP服务器
获取并打印服务器提供的工具列表
演示了两种连接服务器的方式：异步上下文管理器和持久连接

运行你的AI代理

完成代码编写后，执行以下命令运行你的AI代理：

uv run main.py

如果一切正常，你将看到类似以下的输出：

INFO: Hello, world!
INFO: Current config: {'execution_engine': 'asyncio', 'logger': {'transports': ['console'], 'level': 'info'}, ...}
INFO: fetch: Connected to server, calling list_tools...
INFO: Tools available: [{'name': 'fetch', 'description': 'Fetch content from a URL', ...}]
INFO: filesystem: Connected to server with persistent connection.
INFO: fetch: Connected to server with persistent connection.
INFO: filesystem: Tools available: [{'name': 'read_file', 'description': 'Read a file from the filesystem', ...}]
INFO: fetch: Tools available: [{'name': 'fetch', 'description': 'Fetch content from a URL', ...}]
INFO: filesystem: Disconnected from server.
INFO: fetch: Disconnected from server.

这表明你的AI代理已成功连接到MCP服务器，并能够获取工具列表。