MCP 基本概念与最小 Python 实践

【技术专栏】 AI开发
【内容摘要】 了解 Model Context Protocol 的主机、客户端与服务器边界，并用官方 Python SDK 写出可被 Inspector 调试的最小工具服务器。

前面的 Tool Calling 文章里，我们在应用内部声明工具、执行函数，再把结果回传给模型。当工具越来越多时，每个 AI 应用都重复编写连接、发现和调用代码，数据与能力也很难复用。MCP（Model Context Protocol，模型上下文协议）就是为这类连接定义的一套开放协议：服务器以统一方式暴露工具、资源和提示词，支持 MCP 的 AI 应用可以发现并使用它们。本篇只聚焦“如何写一个最小 MCP 服务器”，不讨论 Agent 编排或生产部署。

MCP 解决的是什么问题

可以把 MCP 理解成面向模型交互的标准接口，但它不等于某个模型 SDK，也不是让服务器直接控制模型。一次交互中有三个角色：Host 是用户实际使用的 AI 应用；Client 由 Host 管理，负责与某个服务器建立 MCP 会话；Server 负责提供工具、资源或提示词。模型通常位于 Host 内部，Host 根据模型的判断调用 Client，再由 Client 请求 Server。

这个边界带来两个好处。第一，工具提供方只需实现一次服务器，多个支持 MCP 的 Host 都可以接入。第二，模型只能提出调用意图，真正的文件访问、数据库查询或外部 API 请求仍由服务器代码执行；权限、参数检查和副作用控制不能交给模型。

MCP 的能力可以先记住三类：Tools 是可执行的函数，适合查询或操作；Resources 是可读取的上下文数据，例如文档或配置；Prompts 是可复用的提示词模板。初学时先实现一个只读工具，先看清“发现—调用—返回”的协议边界。

安装官方 Python SDK

官方 Python SDK 要求 Python 3.10 或更高版本。推荐在项目虚拟环境中安装带命令行工具的 extra：

1

uv add "mcp[cli]"

如果只是临时运行而不想修改项目依赖，也可以使用：

1

uv run --with "mcp[cli]" mcp dev server.py

本文代码使用 SDK 当前稳定的 2.x 写法。SDK 版本升级时，优先以其文档和 API 参考为准，不要把不同大版本的示例混用。

写一个最小工具服务器

新建 server.py，内容如下。这里的 add 不访问网络和数据库，只做整数相加，因此可以把注意力放在 MCP 本身：

1
2
3
4
5
6
7
8
9

from mcp.server import MCPServer

mcp = MCPServer("Calculator")


@mcp.tool()
def add(a: int, b: int) -> int:
    """计算两个整数的和。"""
    return a + b

MCPServer("Calculator") 创建服务器实例。@mcp.tool() 将 Python 函数登记为工具；函数的类型标注让 SDK 生成参数 Schema，文档字符串则帮助 Host 或模型理解工具用途。函数返回值是普通整数，SDK 会负责把它转换为协议响应，因此不需要手写 JSON-RPC 请求解析。

安全上仍有一条不可省略的原则：类型标注不是完整的业务授权。把 add 换成读文件或执行命令后，还要在函数内部限制路径、校验身份和控制资源消耗。工具注册成功，不代表任何调用都应该被允许。

用 Inspector 验证发现与调用

在包含 server.py 的目录执行：

1

uv run mcp dev server.py

官方 SDK 的 CLI 会启动开发调试流程，并打开 MCP Inspector。连接建立后，在工具列表中应能看到 add，参数应包含整数 a 和 b。输入 a=1、b=2 发起调用，Inspector 会展示服务器返回的结果 3。这不是模型生成的答案，而是 Python 函数实际计算出的协议结果。

用 Inspector 验证的价值在于把问题分层：如果工具没有出现在列表中，先检查服务器是否启动和装饰器是否执行；如果工具出现但调用失败，再检查参数类型和函数异常；只有协议调用成功后，才需要排查 Host 如何把工具交给模型选择。

常见问题

MCP 和 Tool Calling 是不是同一个东西？ 不是。Tool Calling 描述模型如何请求一个工具，通常由单个应用直接处理；MCP 描述 Host、Client 与 Server 之间如何发现并调用能力。一个 Host 可以把 MCP 服务器发现的工具转换为模型可用的工具，但两层职责不同。

为什么只写函数却没有手动写 Schema？ 官方 SDK 根据类型标注生成基础 Schema。它减少了样板代码，但不会理解“用户是否有权限”“文件是否敏感”等业务规则，这些必须在服务器函数或其下游服务中检查。

为什么服务器能启动，模型却不会调用？ 服务器启动只证明 MCP 连接和工具注册可能正常。Host 还需要支持 MCP、完成客户端配置，并把工具提供给模型。先用 Inspector 验证，再检查 Host 的连接配置、传输方式和模型是否支持工具使用。

stdio 进程里为什么不能随便打印调试信息？ 使用标准输入输出传输时，协议消息也要占用标准流。把日志写到标准输出可能破坏通信；实际项目应使用标准错误或日志文件，并避免输出密钥、用户数据和完整请求内容。

工具能不能直接执行高风险操作？ 不应该默认允许。删除、写入、付款和部署等有副作用的能力，应增加身份授权、参数白名单、审计日志和人工确认；最小示例选择只读或纯计算工具，正是为了降低验证成本。

小结

MCP 的核心价值是把 AI 应用与外部能力之间的连接标准化：Host 管理模型和用户体验，Client 负责会话，Server 暴露工具、资源或提示词。借助官方 Python SDK，只需类型标注、文档字符串和一个装饰器，就能写出可被 Inspector 发现和调用的工具服务器。先用调试器确认协议闭环，再把真实业务接入，并始终把权限与副作用控制留在程序侧。

技术分享自：时光笔记 (wxy.email) | 华为云开发者社区