总结一下大模型的MCP技术(附 Python实战指南)

• 一、你可能已经遇到过这个尴尬
• 二、MCP 在解决什么问题？
• 三、先搞清三个能力：你能在 Server 上开放什么？
• 四、Python 实战：30 分钟做一个可调用的天气服务
• 1）初始化与请求封装
• 2）用装饰器注册工具
• 3）通过 stdio 启动服务
• 五、实战里最容易踩的坑：STDIO 日志污染
• 六、从 Demo 到生产：你还需要这 5 件事
• 七、读完这篇文章，你可以立刻做什么？
• 参考链接（官方优先）

一、你可能已经遇到过这个尴尬

你让 AI 助手查本机日志、调一次内部 API、或者从数据库拉一张表。它答得再漂亮，最后往往补一句：「我接不到你的系统，只能基于公开知识推测。」

不是模型不够聪明，而是缺了一条稳定、标准、可复用的「外设连接线」。

Model Context Protocol（MCP，模型上下文协议）要做的，就是这件事。官方文档里有一个非常形象的比喻：MCP 就像 AI 应用的 USB-C 接口。接口标准化后，换主机、换外设，不必每次重写一套私有集成。详见 MCP 简介。

这篇文章会从「为什么需要 MCP」走到「Python 怎么落地」，最后给你一份可上线的实践清单。目标很明确：读完就能做出第一个可用 MCP 服务。

先看全景图：

二、MCP 在解决什么问题？

Anthropic 在发布文章里说得很直白：过去把 AI 接到业务系统，通常要做很多碎片化、一次性的定制。MCP 提供的是一种开放、统一的协议，让 AI 应用可以标准化连接数据、工具和工作流，从而拿到更相关上下文，输出更可靠结果。详见 Introducing the Model Context Protocol。

用工程视角看，核心其实只有两层：

• MCP Server（服务端）：把你的数据与能力开放出来（查库、调 API、读文件、触发自动化）。
• MCP Client（客户端/宿主）：消费这些能力（AI 聊天应用、IDE、Agent 平台等）。

对开发者来说，价值非常直接：减少重复对接成本，让「写一次服务，多端复用」成为可能。生态层面，Claude、ChatGPT、VS Code、Cursor 等都在支持或扩展 MCP。客户端信息见 MCP 官网 Clients。

一句话总结这一节：MCP 不是“又一个框架”，而是 AI 与外部世界交互的通用协议层。

三、先搞清三个能力：你能在 Server 上开放什么？

官方将 MCP Server 能力分为三类（官方教程重点演示了 Tools）：

1. Resources可读资源，像文件、文档、接口返回内容，适合“读多写少”的场景。

2. Tools可调用函数，适合封装查询、执行、提交工单、触发流程等动作。

3. Prompts预置提示模板，适合把企业内部最佳实践“产品化”。

更细说明见 Server 概念 与 Build an MCP server。实战建议：先从 Tools 入手，因为它最接近业务价值，也最容易做出可见成果。

mindmap  root((MCP Server))    Tools      查询天气      查询订单      提交工单    Resources      API 响应      文档片段      文件内容    Prompts      报告模板      排障模板      审核模板

四、Python 实战：30 分钟做一个可调用的天气服务

官方维护了 Python SDK（modelcontextprotocol/python-sdk）。在官方教程里，推荐使用 FastMCP，它的优势是：函数类型标注和 docstring 会自动转换为工具定义，减少大量样板代码。

环境要求与官方一致：Python 3.10+，mcp[cli] 建议 1.2.0+。依赖安装示例（基于官方 quickstart）：

uv init weathercd weatheruv venv# Windows: .venv\Scripts\activate# macOS/Linux: source .venv/bin/activateuv add "mcp[cli]" httpx

代码结构来自官方天气示例（完整示例见 quickstart-resources/weather-server-python）。我们把美国国家气象局（NWS）的 API 封装成两个工具：get_alerts 与 get_forecast。

1）初始化与请求封装

from typing import Anyimport httpxfrom mcp.server.fastmcp import FastMCPmcp = FastMCP("weather")NWS_API_BASE = "https://api.weather.gov"USER_AGENT = "weather-app/1.0"asyncdefmake_nws_request(url: str) -> dict[str, Any] | None:    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}asyncwith httpx.AsyncClient() as client:try:            response = await client.get(url, headers=headers, timeout=30.0)            response.raise_for_status()return response.json()except Exception:returnNone

2）用装饰器注册工具

@mcp.tool()asyncdefget_alerts(state: str) -> str:"""Get weather alerts for a US state.    Args:        state: Two-letter US state code (e.g. CA, NY)    """    url = f"{NWS_API_BASE}/alerts/active/area/{state}"    data = await make_nws_request(url)ifnot data or"features"notin data:return"Unable to fetch alerts or no alerts found."ifnot data["features"]:return"No active alerts for this state."# 生产环境中建议格式化每条告警，返回更结构化内容return"Alerts found (simplified in blog snippet)."@mcp.tool()asyncdefget_forecast(latitude: float, longitude: float) -> str:"""Get weather forecast for a location."""    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"    points_data = await make_nws_request(points_url)ifnot points_data:return"Unable to fetch forecast data for this location."    forecast_url = points_data["properties"]["forecast"]    forecast_data = await make_nws_request(forecast_url)ifnot forecast_data:return"Unable to fetch detailed forecast."return"Forecast OK (simplified in blog snippet)."

3）通过 stdio 启动服务

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

本地可执行：uv run weather.py。然后在 Claude Desktop 等宿主中，把该进程配置到 mcpServers。JSON 结构可直接参考官方 Build an MCP server。

调用链路如下：

五、实战里最容易踩的坑：STDIO 日志污染

官方教程专门强调：如果使用 STDIO 传输，不要向 stdout 打业务日志。原因是 MCP 消息本身通过标准流传输，日志混进去会污染 JSON-RPC，导致连接异常。正确做法是写到 stderr 或文件。

import sysimport logging# 错误（STDIO 下会破坏协议消息）# print("Processing request")# 可接受print("Processing request", file=sys.stderr)logging.info("Processing request")

HTTP 传输没有这个限制，但统一日志规范仍然很有必要。

六、从 Demo 到生产：你还需要这 5 件事

1. 权限边界每个工具都做最小权限设计，例如只读查询与写操作拆分。

2. 参数校验所有外部输入都做白名单与范围校验，避免“工具被误用”。

3. 超时与重试给外部 API 设置超时、重试与熔断策略，避免工具调用拖垮会话体验。

4. 可观测性记录调用时延、错误率、工具命中率，优先优化高频工具。

5. 结果可解释性工具结果尽量结构化，便于模型生成可追溯答案。

七、读完这篇文章，你可以立刻做什么？

• 今天就能完成：跑通官方 weather demo，理解完整调用链路。
• 本周就能落地：把 get_forecast 替换为你们内部查询接口。
• 本月可以上线：补齐权限、日志、观测与异常处理，变成稳定服务。

如果只做一件事：先跑通官方 weather-server-python，再把一个工具替换成你的真实业务接口。你会非常直观地感受到：模型不再“猜”，而是在“连接你的系统之后执行任务”。

参考链接（官方优先）

• What is the Model Context Protocol (MCP)?
• Model Context Protocol Specification
• Anthropic: Introducing the Model Context Protocol
• Build an MCP server（含 Python 与 Claude Desktop 配置）
• Python SDK（GitHub）