写第一个 MCP server：新规范下要注意什么
数据截至 2026-07，价格与限额以各官网为准。
现在从零写第一个 MCP server，最该注意的不是”怎么把工具跑起来”，而是别照着旧教程建立错误的心智模型：2026-07-28 发布的新规范把协议内核改成了无状态，Tasks 从核心搬进了 extension，授权也向真实世界的 OAuth 部署靠拢。官方把这次修订定性为协议发布以来最大的一次。对新项目来说这其实是好消息——你不用背历史包袱，但前提是你一开始就照着当前版本写，而不是照着网上存量最多的那批旧文章写。
先承认一个很常见的误解：不少人以为”写 MCP server”是件框架活儿，装个 SDK、照示例改两行、把函数暴露出去就完事了，剩下的都是业务代码。跑通一个玩具确实是这样。但真正让第一个 server 后面活得下去的，是几个协议层面的选择：状态放在哪、长任务怎么处理、鉴权什么时候接、版本怎么跟。这几件事一开始拍错了，后面重写的成本远高于一开始多读半小时文档。
先搞清楚你要对齐的是哪个版本
这一步比写代码重要，因为 MCP 相关的中文资料现在存量很大、更新很慢，你搜到的十篇里可能有九篇讲的是旧版本。
时间上做个锚点：MCP 于 2024-11 发布，到 2026-07 大约一年零八个月；2025-12 Anthropic 把它捐给了 Linux 基金会下的 Agentic AI Foundation，成为厂商中立、社区治理的标准，到现在大约七个月。也就是说这是一个还很年轻、迭代速度不慢的协议，“去年的教程”在这里往往意味着”上一代做法”。
判断资料是否过期，有个简单办法：看它说的当前稳定版是哪一版。已经有站点仍然把更早的版本列为当前稳定版、并预告下一版”暂定 2026 年 6 月”，这类信息已经过期，别拿来当依据。一律以 blog.modelcontextprotocol.io 的官方发布公告和规范文档当前版本为准，仓库在 github.com/modelcontextprotocol。
新规范一共动了六块内容：无状态协议内核、Extensions 框架、Tasks、MCP Apps、授权加固、正式的弃用策略。下面按对”第一个 server”影响从大到小说。
不要自己发明会话机制
这是新规范里最实质的一处变化：MCP 现在在协议层是无状态的，由六个 SEP（Specification Enhancement Proposal，规范增强提案）共同实现，落地了此前 “The Future of MCP Transports” 里的计划。协议层不再要求会话追踪。
对老项目来说，这意味着以前为远程 server 搭的那套东西可以拆：粘性会话、共享 session 存储、网关侧的深度包检测，都不再是必需品，server 可以直接跑在普通轮询负载均衡后面，按 Mcp-Method 头路由。
对你的第一个 server 来说，意义在别的地方——你可以省掉一整块本来会写错的代码。新手常见的做法是：担心多轮调用之间要”记住”什么，于是自己在 server 里挂一个内存字典，用某个 ID 当键存上下文。本地单进程调试时看起来完全正常，一上多副本部署就开始随机失灵，因为下一个请求打到了另一个副本上。
现在的推荐姿势很简单：把每次工具调用当成一次独立的、可重放的请求来写。要状态就落到外部存储（数据库、缓存服务），并且状态的键由调用方显式传进来，而不是靠协议帮你隐式维持。
这里要提防一个理解偏差：无状态说的是协议层不再要求会话追踪，不是”MCP 不能有状态”。你的业务当然可以有状态，只是这个状态属于应用层，由你自己管理和声明，不再假装它是协议的一部分。展开可以看MCP 变成无状态了：粘性会话和共享 session 存储可以撤了。
长任务：Tasks 已经不在核心里了
用于长时间运行操作的 Tasks 特性，在新规范里从核心协议移到了 extension。同时 Extensions 框架允许用户自建 extension，与官方认可的 extension 并存。
第一个 server 建议的做法是：先别碰。把范围压到”几秒内能返回结果”的同步工具上，先把工具描述写清楚、参数校验做扎实、错误信息说人话，这些才是决定 agent 能不能用好你的 server 的因素。等到确实遇到”这个操作要跑好几分钟”的场景，再去读 Tasks extension 的当前文档接进来。
如果你现在就非要处理长任务，也有个不依赖 extension 的朴素办法：把它拆成”提交”和”查询”两个同步工具——提交工具立刻返回一个任务 ID，查询工具用 ID 拿进度和结果。这个模式的缺点是把轮询的责任推给了调用方，agent 侧要多写点逻辑，但胜在协议层面没有任何特殊要求，将来迁到官方 extension 也不至于推倒重来。相关背景见 Tasks 移出核心与 Extensions 框架。
授权：什么时候接，接的时候按什么标准
新规范用六个 SEP 让授权规范更贴近真实的 OAuth 2.0 / OpenID Connect 部署，其中包括要求客户端按 RFC 9207 校验 iss 参数（SEP-2468）。
对第一个 server，判断标准很直白：
- 只在本地跑、只给自己用：可以先不做授权，把精力放在工具本身。
- 要暴露给团队或公网：授权不是可选项，而且不建议自己发明一套 token 校验，直接对着当前规范里的授权章节做。
新手最容易踩的坑是把授权当成”加个 API Key 头”就完事。新规范往真实 OAuth 部署靠拢，恰恰说明这块的复杂度是被承认的——iss 校验这类要求存在的原因，是防止令牌被换到另一个签发方的场景下误用。这不是你能靠直觉补齐的细节，照文档做比自己推演划算得多。展开见 MCP 授权加固。
工具本身怎么写：把描述当接口文档写
协议之外，真正决定你的 server 好不好用的，是工具描述的质量。agent 是靠读描述来决定调不调、传什么参数的，描述含糊，表现就是”模型老是不调我的工具”或者”参数总是传错”。
几条可以直接照做的：
- 一个工具只做一件事。宁可拆成三个职责清晰的工具，也不要做一个带
mode参数的万能工具。 - 工具名要能望文生义，别用内部缩写。
- 参数写清类型、是否必填、取值范围，枚举值就把可选项列出来。
- 描述里写清楚什么时候该用它、什么时候不该用。后半句常被省略，但它对减少误调用的作用很大。
- 失败要返回可读的错误说明，而不是抛一个裸异常。agent 拿到”缺少参数 X，X 应为 ISO 日期字符串”这种信息，是有机会自我纠正的；拿到一个 500 就只能放弃。
至于具体的 SDK 写法——用哪个装饰器、字段叫什么名字、怎么启动传输层——这部分请以官方 SDK 当前版本的文档为准。规范刚做过大改，任何凭记忆写出来的函数签名都有过期风险，包括本文不去给的那种。你可以先把工具想成这么一份契约：
# 概念示意，不是任何 SDK 的真实 API
工具名 ：一眼能看懂它做什么
输入参数 ：类型 / 必填与否 / 取值范围或枚举
成功返回 ：结构化结果，字段稳定
失败返回 ：说清楚哪里错了、调用方该怎么改
使用说明 ：什么场景该用，什么场景不该用
把这五项在纸上写明白，再去查 SDK 怎么表达，比反过来做要顺得多。
新旧不兼容与 12 个月窗口
这次改动的破坏性是官方明说的。维护者 David Soria Parra 称这是自加入授权以来最实质的变更，原话是 “A lot of things that made MCP are gone.”（很多构成 MCP 的东西已经没有了。）具体到工程上：2026-07-28 版本的 server 可能无法与旧 client 协同，反之亦然。弃用机制给旧版本留了 12 个月窗口。
新项目怎么对待这件事：
- 明确写下你的目标版本，写进 README，不要含糊说”支持 MCP”。
- 先确认你要接的 client 支持到哪一版。如果你的目标使用场景里 client 还停在旧版本，那就先按旧版本写，同时把迁移排进计划——12 个月窗口是给存量准备的，不是让新项目无限期观望的。
- 别试图同时兼容新旧两套。第一个 server 就搞双栈，复杂度会吃掉你所有时间。
写完之后：让别人找得到
server 能跑只是一半，另一半是可发现性。官方 MCP Registry 在 registry.modelcontextprotocol.io，提供 server 发现、文档与 API 参考，由 modelcontextprotocol GitHub 组织维护，是社区驱动的。
路线图里还有一项相关工作叫 MCP Server Cards——通过 .well-known URL 暴露 server 元数据的标准，让注册表和爬虫不用真的连接就能发现能力。如果你打算把 server 公开出去，这块值得关注，具体形态以官方文档当前版本为准。相关介绍见官方注册表与 MCP Server Cards。
顺带说一下这次修订里的 MCP Apps：它是六块内容之一，但官方发布博客没有展开细节，本文不替它编内容，请以官方规范文档当前版本为准。
诚实说说局限
有几件事需要先说明白，免得预期错位。
中文资料的覆盖度目前很低。 新规范刚发布，中文世界里能对上号的内容还很少，遇到分歧时请回到官方 blog 和规范文档，而不是相信搜索结果里靠前的旧文。
生态数字要按口径看。 按官方与行业公开资料的口径，目前有超过一万个公开 MCP server 在生产中运行，SDK 月下载量超过 9,700 万。这类数字来自公开资料汇总，不是精确统计，看趋势就好，别拿它当技术选型的唯一依据。至于生态的广度，OpenAI、Google、Microsoft、AWS 这四家主流厂商都已经把 MCP 接进了自家 agent 栈，从这个角度说，它作为跨厂商接入标准的地位是比较稳的。
规范还会继续动。 一年零八个月里做到这个程度已经不慢了，正式弃用策略的确立说明后续变更会更有章法，但不代表不再变。把”跟规范版本”当成项目的常规维护项，而不是一次性任务。
小结
写第一个 MCP server，先花时间确认版本，再动手；协议层已经无状态，别自己造会话，需要状态就显式外置；Tasks 已移出核心，第一个 server 先做同步工具，长任务用提交加查询的朴素模式过渡；对外暴露就老老实实按当前授权规范做，包括 RFC 9207 的 iss 校验这类细节；工具描述当接口文档写，它比框架选型更影响实际效果。新旧版本可能互不兼容，弃用窗口是 12 个月，把目标版本写清楚、别搞双栈兼容。所有具体 API、字段和流程，以官方 blog 与规范文档当前版本为准。