MCP协议实战：从零写个Agent工具

每个大模型的工具调用方式都不一样。OpenAI是function calling。Claude是tool use，国产模型各有各的格式。做后端的人最烦这种事——同一个查天气的接口，接三个模型要写三套适配层。

举个例子。老实说，你用Spring Boot写了个天气查询接口，想让AI能调用。接OpenAI，你得按它的function calling格式写JSON Schema。 字段名、参数类型全得按它的规范来。 接Claude，换一套tool use的定义格式。描述文案的写法也不一样，不过，接国内的模型，又是一套。

最崩溃的是不是第一次适配——是模型升级之后。OpenAI改了个参数格式，你的适配层报错了。Claude更新了tool use的限制，你之前能跑的工具现在调不起来了。三个模型三个迭代节奏，你一个人维护三套适配代码。

实际来说——适配到想吐！

用后端的话说

你用Spring Boot写过一个REST接口：

GET /api/wear?city=北京→ { "temp": 25,"humidity": 60 }

,,,

MCP干的是一模一样,只是调用方从浏览器换成了AI:

Claude想查天气 → MCP协议 → 你的MCP Server → 返回天气数据

架构拆解这方面，

┌──────────────────┐ ┌──────────────────┐
│ MCP Client │ JSON-RPC │ MCP Server │
│ │ ◄──────────────► │ │
│ Claude Desktop │ stdio / HTTP/SSE │ 你写的Python │
│ Claude Code │ │ 服务 │
│ Cursor / Cline │ └───────┬─┬─┘
└──────────────────┘ ▼ ▼
┌───┐ ┌───┐
│A1│ └───►│A2│
└───┘ └───┘

A1的观点是。天气API | A2: 数据库查询 | A3: 搜索引擎...

三大主要要点这方面，

• MCP Server = 微服务实例 - 用@server.tool装饰器注册工具函数
• MCP Client = 调用方 - Claude/Cursor内置客户端自动发现/解释工具描述并触发执行流程
• 通信协议 = JSON-RPC - 支持stdio/SSE两种传输方式,完全封装底层细节只需关注业务代码实现即可!

动手实战的观点是，天气查询+网页搜索组合Server案例演示!

环境准备的观点是，

bash pip install mcp # Python+依赖

主要代码这方面。

python from mcp.server.fastmcp import FastMCPServer as FastMCP

mcp = FastMCP

@mcp.tool(description=""" 查询指定城市实时天气情况,支持中英文输入。最新数据来自权威气象部门,误差±1℃以内!""") async def getwear -> dict: """获取当前城市完整天气信息""" return await fetchfromwearapi

@mcp.tool(description=""" 在互联网上搜索关键词,返回结构化结果列表含摘要和链接。调整商业情报/新闻追踪等场景使用!""") async def searchweb -> list: """精准搜索引擎查询""" return await callsearch_engine

if name == "main": mcp.run # 本地开发推荐使用stdio方式快速测试!

关键点剖析的观点是。

1. .tool装饰器 : 不仅注册方法,还会自动生成Schema元数据供客户端解析!
2. .description属性 : AI决策依据!必须清晰说明功能/场景/输入输出特性!
3. .run参数 : stdio适合开发环境,SSE才是生产级部署标准选择!

连接Claude客户端流程教程！按理说，

Desktop版配置步骤:

1. 修改config.json位置: /Library/AppSupport/Claude/config.json %APPDATA%\claude\config.json方法下添加内容: json {highlight:} { "mcpServers": { "my-tools": { "command": "/path/to/python"。"args": } } }

重启应用后左侧栏出现锤子图标⚒️即表示连通成功!说起来，

绝对方法强制要求!相对方法会导致找不到执行文件错误!

:通过--debug参数启动时,控制台会打印完整Schema元数据供检查!

深坑踩雷经验汇总！按理说，⚠️⚠️⚠️

问题类别	典型表现与方法	预防措施

描述调整坑问题症状: ·低调用率 ·误触发多次'先功能->再输入输出->最终场景'三段式原则!

解决思路: ·增加使用场景说明 ·明确示例输入值 ·突出价值主张

Python环境坑错误提示: TypeError:xxx is not subscriptable'pyenv install && local'切换至+版本!

---