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

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

摘要：MCP 就是 AI 世界的 REST API------你写好服务，Claude 来调。前一篇聊了 AI Agent 的学习路线，这篇落到具体动作：用 Python 写一个 MCP Server，把自己的 API 包装成 Agent 能认识的标准工具。不讲协议规范，讲后端最关心的事------怎么让 AI 调你的服务。

---

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

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

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

说实话，适配到想吐。

后来 Anthropic 搞了个 MCP（Model Context Protocol），把这事统一了。2024 年底提出，2025 年生态炸开，到 2026 年已经成了 Agent 工具调用的标配（来源：Anthropic 官方博客，2024年11月）。跟 HTTP 之于 Web 一样------大家都认这个协议，你写一次，所有支持 MCP 的模型都能调。

上篇聊了 AI Agent 的学习路线，这篇不聊概念，聊代码。

---

MCP 是什么，用后端的话说

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

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

前端发起 HTTP 请求，你的 Controller 处理逻辑，返回 JSON------这条路你走了十年，闭着眼睛都能写。

MCP 干的事一模一样，只是调用方从浏览器换成了 AI。

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

架构拆开来看：

┌──────────────────┐                      ┌──────────────────┐
│   MCP Client     │   JSON-RPC 2.0       │   MCP Server     │
│                  │ ◄──────────────────► │                  │
│  Claude Desktop  │   stdio / HTTP/SSE   │  你写的 Python    │
│  Claude Code     │                      │   服务            │
│  Cursor / Cline  │                      │                  │
└──────────────────┘                      └─────────┬────────┘
                                                    │
                                                    ▼
                                          ┌─────────────────┐
                                          │   你的业务 API    │
                                          │                  │
                                          │  天气接口         │
                                          │  数据库查询       │
                                          │  搜索引擎         │
                                          └─────────────────┘

三个要点，用后端的类比就够了：

MCP Server = 你写的微服务。 用 @server.tool() 装饰器注册工具函数，跟 Spring 的 @RestController 一样------声明这个方法对外暴露，MCP 框架自动处理协议细节。

MCP Client = 调用方。 Claude Desktop、Claude Code、Cursor 这些 AI 工具都内置了 MCP 客户端。你配好 Server 地址，它们自动发现你的工具、看懂工具描述、在需要的时候调用。

通信协议 = JSON-RPC 2.0。 跟 REST 的 HTTP + JSON 一样，MCP 用 JSON-RPC 做序列化，支持 stdio（本地进程通信）和 HTTP/SSE（远程部署）。本机调试用 stdio，部署到服务器换成 SSE。

一句话：以前你写 REST API 给浏览器调，现在写 MCP Server 给 AI 调。换的是调用方，不换的是"定义接口 → 处理请求 → 返回结果"这套逻辑。

为什么要用 MCP 而不是直接把 API 丢给 AI？两个原因。第一，MCP 是标准协议。AI 客户端不用知道你的 API 地址、认证方式、参数格式------它只认 MCP 协议，你的 Server 负责把内部 API 包装成标准工具。第二，工具发现是自动的。你加了新工具，AI 自动感知；你改了工具描述，AI 下次调用就用新的描述。不用通知任何一个客户端。

---

动手写：天气查询 MCP Server

理论够了，写代码。

环境准备

Python 3.10+（3.10 以下跑不了，后面踩坑会说），装一个包：

pip install mcp

就一个依赖。FastMCP 把协议细节全封好了，你只关心工具函数怎么写。

核心代码

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")


@mcp.tool()
async def get_weather(city: str) -> str:
    """查询指定城市的实时天气信息，返回温度、湿度、风向和天气概况"""
    # 这里接真实的天气 API，示例用模拟数据
    return f"{city}：晴，26°C，湿度 60%，北风 3 级"


if __name__ == "__main__":
    mcp.run(transport="stdio")

就这么几行。拆一下：

1. FastMCP("weather-server") ------ 创建一个 MCP Server 实例，名字随便起。
2. @mcp.tool() ------ 装饰器注册工具，跟 Spring 的 @GetMapping 一个意思。
3. 函数签名 (city: str) -> str ------ 参数类型和返回值 MCP 框架会自动转成 JSON Schema，AI 客户端用它来判断什么时候调用。
4. 函数的 docstring ------ 这个不是注释，是 AI 看的东西。写什么、怎么写，直接决定 AI 调不调用你的工具。后面专门说。
5. mcp.run(transport="stdio") ------ 启动服务。stdio 走标准输入输出，本机调试用；部署到服务器换成 transport="sse"。

三十行不到，一个能跑的 MCP Server 就出来了。

再加一个工具：网页搜索

只有一个工具太单薄。再加一个搜索工具，让 AI 能查实时信息：

import httpx


@mcp.tool()
async def search_web(query: str) -> str:
    """在互联网上搜索指定关键词，返回前 3 条搜索结果摘要和链接。

    适用于需要实时信息的问题，比如新闻、股价、最新动态。
    """
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.search.example.com/v1/search",
            params={"q": query, "limit": 3},
        )
        data = resp.json()
        return "\n".join(
            f"- {r['title']}: {r['snippet']} ({r['url']})" for r in data["results"]
        )

两个工具注册完，你的 MCP Server 就有了两样本事：查天气、搜网页。AI 拿到这两个工具，碰到"今天北京热不热"会调天气工具，碰到"最近 AI 圈有什么新闻"会调搜索工具。

先自己测一下

接 Claude 之前，先确认 Server 本身能跑。FastMCP 内置了调试模式：

python server.py --debug

或者在代码里用 mcp dev 命令启动一个本地测试界面，直接在浏览器里手动调工具、看返回结果。这个调试界面还显示了 AI 看到的工具 Schema------你会看到你的 docstring 是怎么被转成 JSON Schema 的，参数类型、返回值描述一目了然。这时候如果发现 Schema 不对，回去改 docstring 就行。

测通了再接 Claude，省得配完配置才发现 Server 起不来，两头排查更费劲。

---

接 Claude：让 AI 真正用起来

服务写好了，接下来让 Claude 认识它。

Claude Desktop 配置

macOS 上配置文件在这里：

~/Library/Application Support/Claude/claude_desktop_config.json

打开加上这一段：

{
  "mcpServers": {
    "weather-server": {
      "command": "python",
      "args": ["/Users/tangyuewei/mcp-server/server.py"]
    }
  }
}

command 是启动命令，args 是脚本路径。保存，重启 Claude Desktop。

重启后，Claude 对话框左下角会出现一个锤子图标------点开能看到你的两个工具：get_weather 和 search_web，描述就是你写的 docstring。这时候你问 Claude "北京今天天气怎么样"，它会自动调你的 get_weather。

Claude Code 配置

如果你用的是 Claude Code（终端里的 Claude），配法更简单。在项目根目录加一个 .mcp.json：

{
  "mcpServers": {
    "weather-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

然后在 Claude Code 里 /mcp 就能看到连接状态。绿点代表连上了，可以调。

HTTP 部署

如果你想把服务部署到服务器上，让团队共用，把 stdio 换成 SSE：

if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8080)

客户端配置对应改成 URL：

{
  "mcpServers": {
    "weather-server": {
      "url": "http://your-server:8080/sse"
    }
  }
}

跟 REST 服务的部署套路一样------本机开发用 stdio，上线换成 HTTP。

---

踩过的坑

写了几个 MCP Server 之后，我把踩过的坑说三个。

坑一：工具描述写模糊了，AI 不调用

这个是最大的坑。@mcp.tool() 的 docstring，AI 是当"工具说明书"来读的。你说得越清楚，AI 越知道什么时候调。

我做过对比。描述写"查询天气信息"------调用率 70% 左右。改成了"查询指定城市的实时天气信息，返回温度、湿度、风向和天气概况"------调用率跳到 95% 以上。加了"适用于查询天气相关问题"这句使用场景描述后，误调用也少了。

为什么差这么多？因为 LLM 靠语义匹配决定调哪个工具。你写"查询天气"，它只在用户明确说"天气"的时候调；你写了"温度、湿度、风向"，用户说"今天热不热"它也能匹配上。

经验：docstring 写三行------第一行说功能，第二行说输入输出，第三行说适用场景。别省这个功夫，这是你跟 AI 之间唯一的接口文档。

还有一个容易被忽略的点：工具名也是有语义的。get_weather 比 fetch_wx 好，因为 AI 能直接从名字推断功能。如果你用缩写或项目内部代号当工具名，AI 看不懂，调用率就低。工具名 + 描述一起决定了 AI 的调用意愿。

坑二：Python 版本

MCP 官方依赖要求 Python 3.10+。macOS 自带的 Python 3.9 跑不了。我第一次装了之后启动报 TypeError，查了半小时才反应过来是版本问题。

装个 pyenv 切到 3.12 解决：

pyenv install 3.12
pyenv local 3.12
pip install mcp

坑三：配置文件路径

Claude Desktop 的配置路径 macOS 和 Windows 不一样。macOS 是 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 在 %APPDATA%\Claude\ 下面。网上很多教程只贴 mac 路径，用 Windows 的同事照着找半天找不到。

还有一个点：配置文件里的 args 必须是绝对路径，写相对路径 Claude Desktop 找不到。用 pwd 看完整路径再填进去。

---

后端看 MCP

写了一圈，回到一个朴素的问题：MCP 对后端工程师到底意味着什么。

它不是什么新东西。本质上跟你写了十年的 REST API 一样------定义接口、处理请求、返回结果。MCP 不过是把请求方从浏览器换成了 AI。

但换个角度想，这意味着你的代码能力直接延伸到了 AI 的世界。以前你写的接口只有前端能调------用户点按钮 → 前端发请求 → 后端处理。现在你写的接口 AI 也能调------用户说句话 → AI 理解意图 → AI 调你的工具 → 返回结果。这条链路上，你的代码是最后一公里------它连接着 AI 的理解能力和真实世界的业务数据。

回头看那个类比：MCP 就是 AI 世界的 REST API。 十年前后端学 REST，现在后端学 MCP------逻辑没变，能力范围变了。

有一件事值得多想一步。REST API 的时代，你的接口能力边界是前端决定的------前端能调什么，你的系统就能做什么。MCP 时代，你的接口能力边界是 AI 的理解能力决定的------AI 能理解用户的意图、能组合调用你的工具、能在多个工具之间做决策。同样是你的后端代码，在 REST 时代是被动等调用，在 MCP 时代是主动参与 AI 的推理链。

这不只是"换个调用方"的事。它意味着你写的每一个工具，都可能被 AI 以一种你没想到的方式组合使用------今天它拿天气工具查天气，明天可能用天气工具 + 搜索工具 + 数据库工具自动生成一份出差报告。工具的排列组合效应，是 MCP 区别于 REST 最本质的地方。

上篇说关注 MCP 和 A2A 两个协议，这篇算是把 MCP 从概念到代码走了一遍。A2A（Agent-to-Agent）是 Agent 之间的通信协议，场景不一样，后面再写。

---

tangyuewei，从后端出发，用 AI 拓展到全栈的工程师。