Pydantic AI MCP Agent 实战:基于 Model Context Protocol 无缝接入外部工具
Pydantic AI MCP Agent 实战:基于 Model Context Protocol 无缝接入外部工具
导读
本文将围绕 pydantic-ai-mcp-agent 项目,系统讲解如何基于 Pydantic AI 框架构建一个可动态接入任意 MCP(Model Context Protocol)工具服务器的 AI Agent。读完本文,你将掌握 MCP 客户端与 Pydantic AI 工具的自动转换原理、与 Claude Desktop 完全一致的 mcp_config.json 配置方法、交互式 CLI 与 FastAPI 服务的搭建方式,以及如何将其部署到 Live Agent Studio 平台。
一、项目概览:MCP 与 Pydantic AI 的组合
Model Context Protocol(MCP)是当前 AI 应用接入外部工具的事实标准接口协议。本项目的核心思路是:让 Pydantic AI 构建的 Agent 通过 MCP 协议访问外部工具服务器,从而获得文件系统、数据库、网络服务等能力。其 MCP 配置格式与 Claude Desktop、Windsurf、Cline 等工具完全一致,这意味着你此前为这些桌面工具编写过的任何 MCP 服务器配置,都可以原样复用到自己的 Python Agent 中。
项目由两套实现组成:
- CLI 实现(仓库根目录):面向本地交互式聊天场景,包含 pydantic_mcp_agent.py(主程序)、mcp_client.py(MCP 连接客户端)和 mcp_config.json(MCP 服务器配置)。
- Live Agent Studio 集成(studio-integration-version 目录):面向平台化部署,包含 pydantic_mcp_agent_endpoint.py(FastAPI 端点)、简化版 pydantic_mcp_agent.py 以及 Dockerfile。
核心依赖版本(以仓库 requirements.txt 为准):pydantic-ai==0.0.41、mcp==1.5.0、openai==1.66.3,另含 rich(终端美化)、python-dotenv(环境变量加载)等。注意:仓库中该文件为 UTF-16 编码,阅读时需以 UTF-16 方式打开。
二、工作原理:从配置到工具调用的六步链路
2.1 整体架构
系统的工作流程可概括为六个环节:
- 配置:在
mcp_config.json中声明一个或多个 MCP 服务器(命令、参数、环境变量); - 连接:通过 stdio 建立与 MCP 服务器的进程间通信连接;
- 工具发现:调用 MCP 的
list_tools接口获取服务器暴露的全部工具; - 工具转换:将每个 MCP 工具包装成 Pydantic AI 兼容的
Tool对象; - Agent 初始化:用转换后的工具列表创建 Pydantic AI Agent;
- 执行:Agent 接收用户输入,自主决定调用哪些 MCP 工具完成任务。
2.2 关键组件
- MCPClient:管理一个或多个 MCP 服务器的连接生命周期(配置加载、批量启动、统一清理);
- MCPServer:封装与单个 MCP 服务器的通信细节(stdio 传输、会话初始化、工具列表获取、工具调用);
- Tool Conversion:负责 MCP 工具到 Pydantic AI 工具的类型与 Schema 映射;
- Agent:由 Pydantic AI 提供的推理核心,负责解析用户请求并编排工具调用。
三、快速开始:三步为你的 Agent 接入 MCP 工具
如果你只想在自己的项目中快速复用这套能力,README 提供了极简的三步路径。
3.1 复制客户端并安装依赖
把 mcp_client.py 复制到你的项目,然后安装两个核心包:
pip install pydantic-ai mcp
3.2 编写 MCP 服务器配置
创建 mcp_config.json,其结构与 Claude Desktop 的 MCP 配置完全一致,可直接参考 mcp_config_example.json:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\colem\\oTTomator\\ottomator-agents\\pydantic-ai-mcp-agent"
]
},
"sqlite": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"./data:/mcp",
"mcp/sqlite",
"--db-path",
"/mcp/test.db"
]
}
}
}
3.3 创建带工具的 Agent
import mcp_client
from pydantic_ai import Agent
async def get_pydantic_ai_agent():
client = mcp_client.MCPClient()
client.load_servers("mcp_config.json")
tools = await client.start()
return client, Agent(model='your-llm-here', tools=tools)
在主函数中按需取用:
client, agent = await get_pydantic_ai_agent()
此后,这个 Pydantic AI Agent 便自动获得了 mcp_config.json 中所有 MCP 服务器暴露的全部工具——无需手动注册任何工具函数,配置即工具。
四、配置详解:与 Claude Desktop 兼容的 mcp_config.json
4.1 配置结构与字段语义
每个 MCP 服务器条目包含三个核心字段:
| 字段 | 说明 | 示例值 |
|---|---|---|
command |
启动 MCP 服务器的可执行命令 | npx、docker、python、node 等 |
args |
传给命令的参数列表 | ["-y", "@modelcontextprotocol/server-filesystem", "./"] |
env |
注入服务器进程的环境变量(可省略) | {} 或 {"KEY": "value"} |
4.2 示例服务器解析
示例配置展示了两种典型启动方式:
- filesystem 服务器:通过
npx -y @modelcontextprotocol/server-filesystem <路径>启动,第二个参数是允许服务器访问的根目录。它依赖 Node.js 环境(这也是项目前置要求中包含 Node.js 的原因)。 - sqlite 服务器:通过
docker run --rm -i -v ./data:/mcp mcp/sqlite --db-path /mcp/test.db启动,将宿主机./data目录挂载进容器,数据库文件落在/mcp/test.db。注意--rm -i保证容器用完即销毁且保持交互流。
4.3 底层命令解析逻辑
从 mcp_client.py 的源码可以看到,MCPServer.initialize 会对 command 做特殊处理:
command = (
shutil.which("npx")
if self.config["command"] == "npx"
else self.config["command"]
)
即:当命令是 npx 时,会先通过 shutil.which 解析出 npx 的绝对路径,再构造 StdioServerParameters 交给 stdio_client 建立传输;若 command 解析失败(如系统未安装 Node.js),会抛出 ValueError。env 字段为空或缺失时会被置为 None,交由 MCP 客户端使用默认环境。
五、源码级解析:MCP 工具到 Pydantic AI 工具的自动转换
5.1 MCPClient:多服务器管理器
MCPClient 的三个核心方法构成完整生命周期:
load_servers(config_path):读取 JSON 配置,为每个条目创建MCPServer实例(此时不建立连接,属于懒加载);start():依次initialize每个服务器并调用create_pydantic_ai_tools()收集工具;任一服务器初始化失败时记录logging.error并调用cleanup_servers()回滚已建立的连接,返回空列表;cleanup():先逐个关闭服务器,再关闭自身持有的AsyncExitStack,确保进程退出时不留孤儿子进程。
5.2 MCPServer:单服务器通信与工具转换
MCPServer 是转换机制的核心,值得关注三处实现细节:
初始化与资源管理:initialize 使用 AsyncExitStack.enter_async_context 依次挂载 stdio_client 和 ClientSession,并调用 session.initialize() 完成 MCP 握手;失败时自动 cleanup 并重新抛出异常。cleanup 方法内部用 asyncio.Lock 保护,避免并发清理竞态。
工具发现与转换:create_pydantic_ai_tools 通过 (await self.session.list_tools()).tools 一次性拉取服务器声明的全部工具,然后逐个调用 create_tool_instance:
def create_tool_instance(self, tool: MCPTool) -> PydanticTool:
async def execute_tool(**kwargs: Any) -> Any:
return await self.session.call_tool(tool.name, arguments=kwargs)
async def prepare_tool(ctx: RunContext, tool_def: ToolDefinition) -> ToolDefinition | None:
tool_def.parameters_json_schema = tool.inputSchema
return tool_def
return PydanticTool(
execute_tool,
name=tool.name,
description=tool.description or "",
takes_ctx=False,
prepare=prepare_tool
)
这里的转换包含两层关键适配:
- 执行层:每个 MCP 工具被包装成一个
async def execute_tool(**kwargs)闭包,运行时通过session.call_tool(tool.name, arguments=kwargs)将参数转发给远程服务器——Pydantic AI 的调用结果即是 MCP 服务器的原始返回。 - Schema 层:利用 Pydantic AI 的
prepare钩子,在工具定义生成阶段把 MCP 工具自带的inputSchema(JSON Schema)注入tool_def.parameters_json_schema,从而让 Agent 获得与远程工具完全一致的参数校验与描述信息。takes_ctx=False表示该工具不接收RunContext。
5.3 六步链路与源码的对应关系
| 流程环节 | 源码落点 |
|---|---|
| 配置加载 | MCPClient.load_servers(mcp_client.py) |
| stdio 连接 | MCPServer.initialize 中 stdio_client(server_params)(mcp_client.py) |
| 工具发现 | session.list_tools()(mcp_client.py) |
| 工具转换 | create_tool_instance 的闭包与 prepare 钩子(mcp_client.py) |
| Agent 初始化 | Agent(model=..., tools=tools)(pydantic_mcp_agent.py) |
| 工具执行 | execute_tool → session.call_tool |
六、运行交互式 CLI
6.1 环境变量
CLI 应用通过 pydantic_mcp_agent.py 中的 get_model() 读取以下环境变量(均有默认值):
| 变量 | 作用 | 默认值 |
|---|---|---|
MODEL_CHOICE |
模型名称 | gpt-4o-mini |
BASE_URL |
LLM API 基础地址 | https://api.openai.com/v1 |
LLM_API_KEY |
API 密钥 | no-api-key-provided |
PROVIDER |
提供商标识(README 列出) | 无默认值 |
项目使用 OpenAIModel 统一承载模型,因此 BASE_URL 可以指向 OpenAI、OpenRouter 等 OpenAI 兼容端点;配合本地 Ollama 服务时则无需 API Key。环境变量通过 python-dotenv 的 load_dotenv() 从 .env 文件加载。
6.2 完整启动步骤
# 1. 创建并激活虚拟环境(Windows)
python -m venv venv
venv\Scripts\activate
# 2. (macOS/Linux)
python -m venv venv
source venv/bin/activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置 .env(参考 .env.example)
# PROVIDER=openai / openrouter / ollama
# BASE_URL=<你的 API 地址>
# LLM_API_KEY=<你的密钥>
# MODEL_CHOICE=gpt-4o-mini
# 5. 配置 mcp_config.json(参考 mcp_config_example.json)
# 6. 启动 CLI
python pydantic_mcp_agent.py
6.3 CLI 交互体验
main() 的实现展示了完整的聊天循环:
- 输入
exit、quit、bye、goodbye任意一个即退出; - 使用
rich.live.Live配合agent.run_stream()实现流式 Markdown 输出——stream_text(delta=True)逐段累积 token,live.update(Markdown(curr_message))让终端实时渲染; - 每轮对话通过
result.all_messages()累积message_history,使 Agent 具备多轮上下文记忆; try/finally保证退出时必然调用mcp_client.cleanup(),正确释放 MCP 子进程资源。
七、如何扩展
README 给出了四条扩展路径,结合源码可进一步明确做法:
- 添加更多 MCP 服务器:在
mcp_config.json的mcpServers对象中追加新条目即可,MCPClient.start()会自动批量发现并合并所有服务器的工具,无需改动业务代码。 - 创建自定义工具:遵循 MCP 规范开发自己的服务器,只要实现 stdio 协议即可被本客户端无缝接入;也可以不依赖 MCP,直接在 Agent 中注册 Pydantic AI 原生工具(参考 extras/non_mcp_agent.py 的对照实现)。
- 增强 Agent:替换
get_model()中的模型配置、调整Agent(...)参数,即可针对检索、代码审查等场景定制行为。 - 添加记忆能力:集成 Mem0 等外部记忆系统,让 Agent 跨会话记住用户偏好。
此外 extras 目录还提供了 basic_mcp_agent.py(最简接入示例)、experimental_mcp_client.py(实验版客户端,使用并发清理与 asyncio.gather)以及 pydantic_mcp_streamlit.py(Streamlit Web 界面示例),可供对照学习。
八、Live Agent Studio 集成:FastAPI + Supabase + Docker
8.1 端点架构
studio-integration-version 中的 pydantic_mcp_agent_endpoint.py 将同一套 MCP Agent 包装成生产可用的 HTTP 服务,包含四个关键设计:
- 生命周期管理:FastAPI
lifespan在应用启动时异步初始化全局mcp_agent,保证每个请求复用同一 Agent 实例; - Bearer Token 认证:
verify_token依赖HTTPBearer校验请求头中的 token 是否等于环境变量API_BEARER_TOKEN;该变量未配置时返回 500,token 不匹配返回 401; - CORS 全开:
allow_origins=["*"],便于前端跨域调用; - 请求模型:
POST /api/pydantic-mcp-agent,请求体包含query、user_id、request_id、session_id四个字段,响应体仅返回success布尔值(异步任务式设计)。
8.2 Supabase 会话存储
端点依赖 Supabase 持久化多轮对话,核心逻辑在 fetch_conversation_history 与 store_message 两个函数中:
- 读取:按
session_id过滤、按created_at倒序取最近 10 条,再反转得到时间正序的历史,转换为 Pydantic AI 的ModelRequest/ModelResponse消息格式传入agent.run(..., message_history=messages); - 写入:用户消息以
type="human"、Agent 回复以type="ai"写入messages表,data字段可携带request_id、错误详情等附加信息; - 错误兜底:Agent 执行异常时仍会写入一条致歉回复,并把
error与request_id存入data。
需要在 Supabase 中预先创建 messages 表,字段结构如下:
| 字段 | 类型 | 说明 |
|---|---|---|
id |
UUID | 主键 |
created_at |
Timestamp with time zone | 创建时间 |
session_id |
Text | 会话标识 |
message |
JSON | 含 type、content 及可选 data |
8.3 环境变量与部署
在 studio-integration-version 目录配置 .env:
MODEL_CHOICE=gpt-4o-mini
BASE_URL=<你的 API 地址>
LLM_API_KEY=<你的密钥>
SUPABASE_URL=<Supabase 项目地址>
SUPABASE_SERVICE_KEY=<Supabase 服务角色密钥>
API_BEARER_TOKEN=<自定义的 API 认证令牌>
本地启动:
cd studio-integration-version
python pydantic_mcp_agent_endpoint.py
服务默认监听 0.0.0.0:8001(见 uvicorn.run(app, host="0.0.0.0", port=8001))。
8.4 Docker 部署
仓库提供的 Dockerfile 基于 ottomator/base-python:latest 基础镜像:
cd studio-integration-version
docker build -t pydantic-mcp-agent .
docker run -p 8001:8001 --env-file .env pydantic-mcp-agent
Dockerfile 将 PORT 作为构建参数(默认 8001)写入 ENV,最后通过 uvicorn pydantic_mcp_agent_endpoint:app --host 0.0.0.0 --port ${PORT} 启动,--env-file 负责把本地 .env 注入容器。
九、环境要求与注意事项
- Python 3.9+:项目基于
pydantic-ai 0.0.41与mcp 1.5.0,异步接口(AsyncExitStack、asyncio.Lock)依赖较新的 Python 版本; - Node.js:若使用
npx启动类 filesystem 的 MCP 服务器,需确保 Node.js 可用;initialize中对npx做了shutil.which探测,缺失时会直接报错; - LLM 服务:OpenAI API Key 为默认前提;OpenRouter 等兼容端点只需修改
BASE_URL;本地 Ollama 可免除 Key; - Docker:示例中的 sqlite 服务器以容器方式运行,需要本机 Docker 环境;
- 仓库中根目录与 studio-integration-version 的
requirements.txt均为 UTF-16 编码,若直接以 UTF-8 读取会报解码错误,请按 UTF-16 解析或使用iconv转换。
十、总结
通过本文可以完整掌握:MCP 协议与 Pydantic AI 组合下的 Agent 工具接入范式、与 Claude Desktop 兼容的 mcp_config.json 配置、基于 prepare 钩子的工具 Schema 自动注入原理、流式 CLI 的构建方法,以及 FastAPI + Supabase + Docker 的生产化部署链路。整个项目最核心的价值在于一次编写、随处复用——任何符合 MCP 标准的服务器(文件系统、SQLite、GitHub、Slack 等)都能通过同一套 mcp_client.py 瞬间接入你的 Pydantic AI Agent,让工具扩展从"写代码"变成"改配置"。