【MCP Tool Calling Agent 开发实战】从零构建高效 AI 代理

目录

引言

若对您有帮助的话，请点赞收藏加关注哦，您的关注是我持续创作的动力！有问题请私信或联系邮箱：funian.gm@gmail.com

在2026年的AI开发领域，Model Context Protocol（MCP）已成为构建工具调用代理（Tool Calling Agent）的核心协议。
作为一个开放标准，MCP 标准化了LLM与外部工具的交互方式，让AI代理能够安全、高效地访问数据源、API和服务，而无需每次加载海量上下文。根据Anthropic和Composio的最新报告，MCP 已帮助开发者将代理的token消耗降低98%以上，同时提升了代理的自主性和可扩展性。

本文基于2026年最新的MCP SDK和框架（如FastMCP、OpenAI Agents SDK），从实战角度带你一步步构建一个支持工具调用的AI代理。我们将覆盖从环境搭建到真实场景应用的全过程，包括代码执行优化、文件系统集成和数据库查询。无论你是初学者还是资深工程师，这篇指南都能让你快速上手。

MCP 概述：为什么选择 MCP 构建 Tool Calling Agent？

MCP（Model Context Protocol）是一个客户端-服务器架构的协议，专为LLM提供上下文和工具访问。它通过JSON-RPC接口标准化工具执行，支持工具发现、认证和错误处理。相比传统工具调用，MCP的优势在于：

• 高效性：代理只需按需加载工具定义，避免上下文爆炸。
• 安全性：内置沙箱和路径验证，防止越权访问。
• 可扩展性：支持文件系统、数据库、API等资源，支持动态资源（如file://logs/{date}）。
• 兼容性：集成OpenAI、Anthropic、Google ADK等主流LLM和框架。

在Agent开发中，MCP扮演“神经系统”角色：LLM（大脑）决策，MCP执行工具调用（肌肉）。典型架构包括：

• MCP Server：暴露工具和资源（如Composio托管的GitHub工具）。
• MCP Client：连接服务器，代理LLM调用。
• Agent：结合LLM，处理任务如“创建GitHub Issue”。

2026年，MCP已演进到v2.1，支持进度报告和多模态工具。

环境安装与项目设置

Prerequisites

• Python 3.10+
• OpenAI/Anthropic API Key
• pip安装：pip install fastmcp openai-agents python-dotenv

创建项目目录：

mcp-agent-demo/ ├── agent.py ├── server.py ├── run.py ├── .env └── requirements.txt

在.env中配置：

OPENAI_API_KEY=sk-xxx MCP_TOOL_URL=https://mcp.composio.dev/github/sse?customerId=your_id

生成requirements.txt：

pip freeze>requirements.txt

构建 MCP Server 和 Tool

首先，创建一个简单的MCP Server，使用FastMCP框架。这是一个10行代码的起点：

fromfastmcpimportFastMCP mcp=FastMCP("Simple Calculator Server")@mcp.tool()defadd_numbers(a:int,b:int)->int:"""Add two numbers together"""returna+bif__name__=="__main__":mcp.run()

运行后，Server监听本地端口，暴露add_numbers工具。LLM可以通过MCP Client调用它。

实战：集成数据库查询工具

扩展到真实场景：构建一个安全的SQL查询工具。只允许SELECT查询，防止注入。

fromfastmcpimportFastMCP,ToolErrorfrompydanticimportBaseModelimportsqlite3# 假设使用SQLitemcp=FastMCP("Database Query Server")classQueryResult(BaseModel):rows:list[dict]count:int@mcp.tool()defquery_db(sql:str,limit:int=100)->QueryResult:"""Execute safe SQL query"""ifany(kwinsql.upper()forkwin["DROP","DELETE","UPDATE"]):raiseToolError("Only SELECT queries allowed")conn=sqlite3.connect('example.db')cursor=conn.cursor()cursor.execute(sql)rows=cursor.fetchall()conn.close()returnQueryResult(rows=rows[:limit],count=len(rows))if__name__=="__main__":mcp.run()

这个工具使用Pydantic验证输出，确保结构化返回。运行Server后，代理可查询如“SELECT * FROM users”。

文件系统资源集成

MCP支持资源路径，如动态日志读取：

importosfrompathlibimportPathfromfastmcpimportFastMCP,ToolError mcp=FastMCP("File System Server")BASE_DIR=Path("/safe/workspace")defvalidate_path(path:str)->Path:full_path=(BASE_DIR/path).resolve()ifnotstr(full_path).startswith(str(BASE_DIR)):raiseToolError("Access denied")returnfull_path@mcp.resource("file://{path}")defget_file(path:str)->str:file_path=validate_path(path)ifnotfile_path.exists():raiseToolError("File not found")returnfile_path.read_text()if__name__=="__main__":mcp.run()

代理可请求file://logs/2026-01-10获取日志，内置验证防止目录穿越。

集成 LLM 与 Agent 开发

使用OpenAI Agents SDK构建Agent，连接MCP Server。

在agent.py中：

importosfromdotenvimportload_dotenvfromagentsimportAgentfromagents.mcpimportMCPServerSse load_dotenv()TOOL_URL=os.getenv("MCP_TOOL_URL")defbuild_agent():mcp_server=MCPServerSse({"url":TOOL_URL})agent=Agent(name="GitHub Manager",instructions="Manage GitHub repos: create issues, update PRs using MCP tools.",mcp_servers=[mcp_server],model="gpt-4o"# 或 claude-4.5)returnagent,mcp_server

在run.py中异步运行：

importasynciofromagentimportbuild_agentfromagentsimportRunner TASK="Create an issue in repo 'user/repo' with title 'Bug Fix' and body 'Details here'."asyncdefmain():agent,mcp_server=build_agent()try:awaitmcp_server.connect()result=awaitRunner.run(agent,TASK)print("Result:",result.final_output)finally:awaitmcp_server.cleanup()if__name__=="__main__":asyncio.run(main())

首次运行会提示OAuth认证。Agent会自动推理、调用工具（如GitHub API），并返回结果。

代码执行优化：Anthropic风格

根据Anthropic的工程实践，使用MCP进行代码执行以减少token：

# 在Agent中添加代码执行工具@mcp.tool()asyncdefexecute_code(code:str)->str:"""Run Python code in sandbox"""# 使用restrictedpython或类似沙箱执行fromrestrictedpythonimportcompile_restricted_exec globs={"__builtins__":{}}compile_restricted_exec(code,globs)returnstr(globs.get('result','No result'))

这允许Agent编写循环/过滤代码，如处理大CSV文件而无需全传上下文。

实战示例：构建 GitHub + Database Agent

结合以上，构建一个端到端Agent：查询数据库，生成报告，创建GitHub Issue。

1. 查询DB获取数据。
2. 处理/过滤数据。
3. 通过MCP GitHub工具创建Issue。

完整代码片段：

# 在Agent instructions中添加逻辑instructions=""" 1. Query DB for sales data. 2. Filter pending orders. 3. Create GitHub issue with summary. """# 运行结果示例result=awaitRunner.run(agent,"Generate sales report and log to GitHub.")

在生产中，使用进度报告：

fromfastmcpimportProgress@mcp.tool()asyncdefprocess_data(data:list,progress:Progress)->dict:total=len(data)processed=0foritemindata:# 处理processed+=1ifprocessed%10==0:awaitprogress.update(processed=processed,total=total)return{"done":True}

最佳实践与注意事项

• 安全：始终验证输入，使用ToolError处理异常。限制率（如10 calls/min）。
• 测试：用MCPTestClient写单元测试。

importpytestfromfastmcp.testingimportMCPTestClient@pytest.mark.asyncioasyncdeftest_query():asyncwithMCPTestClient(mcp)asclient:result=awaitclient.call_tool("query_db",{"sql":"SELECT 1"})assertresult.count>0

• 性能：使用异步工具，避免阻塞。2026年推荐MoE模型如Claude 4.5以提升推理。
• 常见坑：认证失败？检查OAuth。上下文溢出？用代码执行过滤数据。
• 框架对比：