《MCP 协议与实现》前两篇把协议地基打完了:第 1 篇《MCP 协议全景:从三原语到无状态内核》讲清了三原语分工与 JSON-RPC 消息层,第 2 篇《MCP 无状态内核:2026-07 改版详解》拆解了无状态内核的报文细节。从本篇起进入 Server 开发层,不再逐条读规范,开始写能跑的代码。写 server 选官方 Python SDK 最顺:它刚完成 v2 大版本重构,本文写作时(2026 年 11 月)已迭代到 v2.3.0(2026-10-02 发布),配套的独立文档站也上线了。
本篇是全系列第 3 篇,按"SDK 全景 → 安装与最小 Server → 三原语 → 类型即文档 → 低层 API → 运行与调试 → 实战"组织,读完你能独立交付一个可挂进 Claude Code 或 Cursor 的知识库 server。
1、SDK v2 全景
v2 是一次伤筋动骨的重构,不是常规升级。先记四条硬信息:其一,要求 Python 3.11+;其二,文档从 README 内嵌升级为独立文档站;其三,wire 类型(协议报文的 pydantic 模型)拆成独立的 mcp-types 纯 pydantic 包——只想要协议类型定义的项目可以单独依赖它,不必拖上整个 SDK 运行时;其四,高层类 FastMCP 改名 MCPServer(位于 mcp.server.mcpserver),旧导入路径直接删除、不留兼容别名,v1 代码升级必须在 import 层动刀,What's new in v2 与迁移指南逐条列了破坏性变更。
改名背后是一段持续一年的命名迷局。"FastMCP" 这个名字来自 2025 年初的社区项目:作者把第一版捐给官方 SDK 作为高层 API(也就是 v1 里的 FastMCP 类),随后另起门户,在 gofastmcp.com 持续演进独立的 FastMCP 框架,如今已到第 4 版。于是很长一段时间里"FastMCP"同时指官方类与第三方框架,新人十有八九装错包。v2 把官方类改名为 MCPServer,从此官方侧只叫这个名字,"FastMCP"专指 gofastmcp.com 的第三方框架。
装包认准包名:
mcp是官方 SDK,fastmcp是第三方框架——两者都能写 server,本文只讲官方这条线。
两代 SDK 的关键差异对比如下。
| 维度 | v1 | v2 |
|---|---|---|
| 高层类名 | FastMCP | MCPServer |
| 导入路径 | mcp.server.fastmcp | mcp.server.mcpserver |
| wire 类型 | 与 SDK 同包 | 独立 mcp-types 包 |
| 最低 Python | 3.10 | 3.11 |
| 文档 | README 内嵌 | 独立文档站 |
另外,v2 内部是"低层 Server 加高层 MCPServer"的双轨 API,什么时候用哪条轨道,第 5 节专门对照。
2、安装与最小 Server
安装推荐 uv。只把 SDK 当库用,一行 uv add mcp 即可;开发期建议直接装上命令行工具,命令如下。
uv add "mcp[cli]"
[cli] extra 会装出 mcp 命令——mcp dev、mcp run 都靠它,写 server 基本离不开。没有 uv 的环境用 pip install "mcp[cli]" 等价。接着写第一个 server,完整代码如下。
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
if __name__ == "__main__":
mcp.run()
逐行走读:构造器只描述"这个 server 是什么"——名字是第一个位置参数,可选还有版本号与说明;@mcp.tool() 把普通函数注册成工具,函数名就是工具名 add,docstring 就是给模型看的描述,类型提示就是参数 schema;mcp.run() 启动服务并阻塞,不传参数默认走 stdio 传输;if __name__ == "__main__" 守卫不能省——mcp dev 与 mcp run 都是先 import 这个文件再找 server 对象,没有守卫,一 import 就会把服务跑起来。
不到十行代码,一个合规的 MCP server 就完工了。跑起来验证:uv run mcp dev server.py 会拉起 MCP Inspector(需要 PATH 里有 npx,它是个 Node.js 应用),在 Tools 页调用 add、传 a=1 与 b=2,拿回 3——连那个"必填整数"输入表单,都是 Inspector 从你的类型提示现生成的。调试的更多玩法本系列第 5 篇详解。
3、三原语各写一个
第 1 篇给过三原语的对照表:tools 由模型自主调用,resources 由客户端应用按需读取,prompts 由用户显式触发。控制权归属不再重复,本节用三个例子把写法差异走一遍——三者都是装饰器注册,结构同构。
3.1、tool 计算器
工具是模型自己决定何时调用的,参数描述的质量直接决定传参质量。用 pydantic 的 Field 注解把描述写进参数,代码如下。
import re
from typing import Annotated
from pydantic import Field
@mcp.tool()
def calc(expression: Annotated[str, Field(description="算术表达式,如 (1+2)*3")]) -> str:
"""计算一个算术表达式的值。"""
if not re.fullmatch(r"[0-9+\-*/(). ]+", expression):
return "仅支持数字与 + - * / ( ) 和空格"
try:
return str(eval(expression)) # 输入已按白名单过滤
except ZeroDivisionError:
return "除数不能为零"
解读:Annotated[str, Field(description=...)] 里的描述会原样进入工具 schema,模型看得见;返回 str 会被自动包成文本结果。注意工具内部不把业务错误抛给协议层——错误信息作为正常结果返回,模型读得懂,能自己修正参数重试。
3.2、resource 文件内容
资源把读取时机交给客户端应用。装饰器参数是 URI,静态地址与带参数的模板各写一个,代码如下。
from pathlib import Path
DOCS_DIR = Path("docs")
@mcp.resource("docs://catalog")
def catalog() -> str:
"""返回文档目录清单。"""
return "\n".join(p.name for p in DOCS_DIR.glob("*.md"))
@mcp.resource("docs://{filename}")
def read_file(filename: str) -> str:
"""读取指定 Markdown 文件的内容。"""
target = (DOCS_DIR / filename).resolve()
if DOCS_DIR.resolve() not in target.parents:
return "路径越界,已拒绝"
return target.read_text(encoding="utf-8")
解读:静态资源 docs://catalog 没有参数,客户端直接 resources/read;模板资源 docs://{filename} 的花括号参数映射到同名函数参数,客户端读 docs://intro.md 时 SDK 先解析出 filename 再调函数。第二个函数顺手演示了碰文件系统的 server 必做的越界校验——资源一旦挂进客户端,读文件的口子就是外部够得着的口子。
3.3、prompt 提示模板
prompt 由用户在客户端菜单里主动挑起,常见形态是斜杠命令。注册方式与前两者同构,代码如下。
# Annotated 与 Field 的导入同 3.1
@mcp.prompt(title="周报生成")
def weekly_report(
name: Annotated[str, Field(description="汇报人姓名")],
work: Annotated[str, Field(description="本周事项,分号分隔")],
) -> str:
"""按固定模板生成周报初稿。"""
items = "\n".join(f"- {x.strip()}" for x in work.split(";"))
return f"请以 {name} 的口吻把以下事项整理成周报:\n{items}"
解读:title= 是给人看的按钮文案;返回的字符串经 prompts/get 渲染后,作为一条 user 消息进入对话,相当于替用户预写了一大段提示词。它与 tool 最大的差别在错误语义:prompt 参数没有 JSON Schema,就是一张"名字加必填与否"的扁平表;缺必填参数时整个请求直接以 JSON-RPC 错误失败(-32603),不给函数执行机会——因为填表单的是用户,模型不在环里,不需要模型可读的错误通道。
4、类型即文档
回看前面的 add 与 calc:从头到尾没写一行 JSON Schema,也没碰过 JSON-RPC。SDK 从函数上读走三样东西——函数名成工具名,docstring 成描述,类型提示成参数 schema。calc 注册后,tools/list 返回的条目节选如下。
{
"name": "calc",
"description": "计算一个算术表达式的值。",
"inputSchema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "算术表达式,如 (1+2)*3"
}
},
"required": ["expression"]
}
}
解读:int 映射 integer,参数带默认值就从 required 里消失,Field 的 description 原样带入。这张 schema 同时驱动两端:Inspector 拿它画表单,模型拿它决定怎么传参。函数签名就是接口文档——签名一改,schema 自动跟着改,不存在文档过期的经典难题。SDK 把 wire 类型拆成纯 pydantic 包 mcp-types,也是为了让这条"类型到 schema"的推导链路有干净的地基。
5、低层 Server API
MCPServer 并不是 SDK 的全部。v2 是双轨 API:高层 MCPServer 负责"把 Python 函数翻译成协议条目";低层 Server 直接面向 JSON-RPC 方法本身——哪个 handler 响应 tools/list、tools/call 怎么分发、返回的报文长什么样,全部自己写,schema 也要手工构造,wire 类型从 mcp-types 包里拿。两条轨道的对比如下。
| 维度 | 高层 MCPServer | 低层 Server |
|---|---|---|
| 注册方式 | 装饰器注册函数 | 构造器传 handler |
| 参数校验 | 类型提示推导 schema | 手写 JSON Schema |
| 命令行调试 | mcp dev 与 mcp run 可用 | 需自写启动代码 |
| 典型场景 | 绝大多数 server | 逐字段控制协议报文 |
低层的主场是协议层细节。第 2 篇提过 GA 版给 list 方法新增了 ttlMs 与 cacheScope——想让 tools/list 的响应精确携带这两个字段,就得自己组装返回值;分页游标、中间件、运行期动态增删工具目录,也都是低层的活。官方文档把低层 Server 归在 Advanced 章节,并明确说 mcp dev 与 mcp run 只认 MCPServer,低层 server 要自己写启动代码(详见低层 Server 文档)。结论很干脆:默认从 MCPServer 起步,等它真的挡住你,再下探。
6、运行与调试
mcp.run() 是唯一的启动决策点,核心参数是传输方式。默认 stdio:宿主把你的文件当子进程拉起,协议字节流走 stdin 与 stdout。这带来一个新手必踩的坑——stdout 就是协议线:服务期间往 stdout 打印的内容都可能污染报文流,SDK 会把其中已 flush 的输出改道 stderr 兜底,但启动阶段缓冲的输出仍会落在线上,所以日志一律走 logging 模块。想变成端口服务,只改一行。
if __name__ == "__main__":
mcp.run(transport="streamable-http", port=3001)
这一行会让 SDK 用 Starlette 加 uvicorn 起一个 HTTP 服务,客户端连 http://127.0.0.1:3001/mcp。两个易错点:其一,host、port、streamable_http_path 这些传输参数全在 run() 上,写进 MCPServer(...) 构造器会直接 TypeError——构造器描述"server 是什么",run() 描述"server 怎么被服务",两者别混;其二,无状态部署加 stateless_http=True,每个请求独立处理、不追踪会话,正好接上第 2 篇讲的无状态内核。调试再预告一次:uv run mcp dev server.py 起 Inspector 可视化调三原语,细节第 5 篇展开(运行文档)。
7、实战:内部知识库 Server
最后串一个完整案例:给团队内部知识库做查询 server——工具负责检索,资源负责列目录。假设 docs/ 下放着一批 Markdown。检索走标准向量链路:文档与查询各自向量化,算余弦相似度取前 k 个。示例用词频向量把链路跑通,零外部依赖;生产环境把向量化一步换成 embedding 模型(本地 sentence-transformers 或内部 embedding 服务),检索骨架不用动。先看核心,代码如下。
import math
import re
from collections import Counter
from pathlib import Path
DOCS = {p.stem: p.read_text(encoding="utf-8")
for p in Path("docs").glob("*.md")}
def tokenize(text: str) -> list[str]:
return re.findall(r"[a-zA-Z0-9]+|[一-鿿]", text.lower())
VECTORS = {name: Counter(tokenize(body)) for name, body in DOCS.items()}
def cosine(a: Counter, b: Counter) -> float:
dot = sum(v * b.get(k, 0) for k, v in a.items())
norm = math.sqrt(sum(v * v for v in a.values())
* sum(v * v for v in b.values()))
return dot / norm if norm else 0.0
解读:启动时全量读入文档并建好词频向量;tokenize 对英文按单词、中文按单字切分——词频没有真语义,这里只求链路完整。接着把能力挂上原语,代码如下。
from typing import Annotated
from pydantic import Field
from mcp.server import MCPServer
mcp = MCPServer("内部知识库")
@mcp.tool()
def search(
query: Annotated[str, Field(description="检索问题或关键词")],
top_k: Annotated[int, Field(description="返回条数")] = 3,
) -> str:
"""按相似度检索内部文档,返回文件名与内容开头。"""
q = Counter(tokenize(query))
ranked = sorted(DOCS, key=lambda n: -cosine(q, VECTORS[n]))
return "\n".join(f"{n}.md:{DOCS[n][:50]}……" for n in ranked[:top_k])
@mcp.resource("kb://catalog")
def catalog() -> str:
"""返回知识库文档清单与字数。"""
return "\n".join(f"{n}.md({len(body)} 字)" for n, body in DOCS.items())
if __name__ == "__main__":
mcp.run()
解读:search 是留给模型的口子——模型判断用户在问内部知识时自己发起调用,top_k 带默认值所以是可选参数;kb://catalog 是留给客户端应用的口子——用户想看库里有什么时由应用读取,一次都不占用模型的工具调用。同一个知识库,两种暴露方式,正好对上第 1 篇那张控制权对照表。uv run mcp dev server.py 起服务实测:在 Tools 里问"部署怎么做",在 Resources 里读 catalog,各归其位。
8、总结
本文从协议转入代码,走完官方 Python SDK v2 的入门闭环:v2 要求 Python 3.11+,高层类改名 MCPServer、wire 类型拆成 mcp-types 包,"FastMCP"之名让位给第三方框架;不到十行代码起一个合规 server,装饰器加类型提示就是全部接口定义;三原语写法同构、错误语义各异;低层 Server 留给协议层精细控制;run() 定传输,stdio 模式下 stdout 即协议线。留三道练习:
- 把实战 server 的词频向量换成 sentence-transformers 的真 embedding,对比两者检索质量
- 给知识库 server 加一个 prompt:用户触发"总结某篇文档",模板带文件名参数
- 用
mcp run server.py --transport streamable-http把服务架上端口,再用 Inspector 连一次
对于准备交付第一个 server 的读者,建议路径是:MCPServer 起步,mcp dev 全程伴随,卡在协议细节再下探低层 API。本系列的调试与接入真实宿主,第 5 篇展开。

