上周末我跟着官方文档写第一个 MCP server，踩了 5 个坑。坑踩完之后回头把市面上那 8 个号称"MCP 入门必读"的资源全过了一遍，发现一个事——选错入口能让你绕一大圈。
这篇就把这 5 个坑和 8 个资源的真实点评写出来。先讲坑，再讲资源，最后给一条按顺序走的学习路线。
如果你不知道 MCP 是什么：Anthropic 在 2024 年 11 月开源的协议，约定"AI 模型怎么调外部工具"。USB-C 类比很贴切——Server 暴露能力，Client（Claude Desktop / Cursor / 自研 Agent）按同一份协议调，传输层走 stdio、SSE 或 Streamable HTTP。"协议"听起来很重，落到代码就是 JSON-RPC 加几个固定方法名。
坑 1：直接读官方 Quickstart 跑不通
官方文档（modelcontextprotocol.io） 那段 "For Server Developers" 写得简洁，但简洁的代价是没告诉你环境怎么搭。我用 brew 装的 Python 3.12 跑 uv run 第一次报错说 "No interpreter found"；折腾半小时才发现要用 uv venv 重建虚拟环境，再 uv pip install mcp，最后用 uv run --python 3.12 server.py 显式指定版本。这段官方文档完全没写——它默认你已经把 uv 的工作流摸熟了。
第二个小坑是 Claude Desktop 配置文件路径。我按习惯找了 ~/.config 半天，最后才在 ~/Library/Application Support/Claude/claude_desktop_config.json 找到（macOS）。Linux/Windows 路径又不一样。这事在官方 Quickstart 里只一句话带过，新手很容易卡在这。
走出这两个坑之后，我对官方文档的评价是：唯一的一手资料，但不是新手友好的入门资料。 Concepts 这一章把 Resources / Tools / Prompts 三种 primitive 拆得很清楚，是协议的骨架，绝对要读；Specification 那一章先跳过，写第二个 server 的时候再回来翻。Quickstart 必须自己跑通，跑不通就别往下走，先解决环境——这是判断你 Python 装对没装对的硬指标。
匠人学院那批跟我学 MCP 的同学里大概有 1/3 卡在这一步，所以我现在带新人会直接发一份"环境检查清单"，把 uv 版本、Python 版本、Claude Desktop 配置路径、which python 输出都列出来逐项核对，比埋头读文档省事得多。
坑 2：跟着 liaokongVFX 抄，撞到 SDK 不兼容
liaokongVFX/MCP-Chinese-Getting-Started-Guide 是 GitHub 上中文 MCP 教程里 star 最高的一个，定位"30 分钟从 0 到 Cursor 里跑通 MCP"。配图是真实截图不是手画示意图，理论上对着抄能跑通。
但这个仓库迭代比较快，部分代码片段对应的是早期版本的 SDK。我抄了一段早期 echo server 代码，跑起来报"Tool decorator signature changed"——后来对照新 SDK 才发现 @server.tool() 的参数名变了。开读前先看一眼最近一次 commit 时间，太久没更新就只看思路别照抄代码。
另一个小坑：liaokong 的术语翻译跟官方对不上。primitive 同一篇里"原语"和"基本单元"两种翻译都出现过，新人会以为是两个东西。其实是一个。
坑 3：被知乎《MCP 一篇就够了》系列绕进去
知乎上同名文章十几篇，点赞过千的有两三篇。我一开始挑了一篇阅读最高的，看完才发现整篇是 GPT 翻译官方文档凑字数——句子拗口、术语不统一、最关键的"为什么这么设计"完全没讲。
后来挑了一篇作者主页有真实 MCP server repo 的，质量明显是另一个档次：作者自己踩过坑，写出来的"为什么 MCP 不直接用 OpenAPI 而要自创协议"那段才是真东西。所以选知乎文章的判断标准只有一个——点开作者主页看他有没有真的写过 MCP server，没写过的纯文字爆款多半没读过 spec。
这一类知乎长文不会带你写一行代码，它的实际价值在补"MCP 这件事是怎么冒出来的"行业背景：LangChain Tool 抽象当年留下哪些不舒服的设计、Function Calling 和 MCP 各管哪一段、Cursor / Windsurf 这些 IDE 为什么主动接 MCP。读完之后跟人讨论至少不会外行——但写 server 这事还是得另外动手练。
URL：在知乎搜 "MCP 一篇就够了"，挑作者主页有真实 MCP server repo 的版本。
坑 4：FastMCP 文档读快了，把 Patterns 跳了
FastMCP 是我读过最舒服的英文资源。作者 Jeremiah Lowin 同时是 Prefect 的创始人，工程审美在线。文档分四段——Tutorials（十几行代码出 server）、Concepts（Tool / Resource / Prompt / Context 四种核心抽象）、Patterns（auth / middleware / async / 错误处理 / 依赖注入 / Composition）、Deployment（stdio / SSE / Streamable HTTP 三种 transport）。
我第一次读的时候只看了 Tutorials 和 Concepts，跑了两个 hello world 觉得自己学会了。后来要把 server 接到公司内网，一上来就遇到 auth 和 rate limit 的问题——这才回去补 Patterns 段。Patterns 这段是真正区分"会写 demo"和"能上生产"的分界线，写第二个 server 之前一定要读完。
从分层看，官方 @modelcontextprotocol/sdk 是低阶接口，需要自己拼 JSON-RPC handler 和 schema 字段；FastMCP 在上面包了一层 FastAPI 风格的语法糖，@mcp.tool() 加类型注解，schema 自动生成。99% 的业务场景直接用 FastMCP 就行，除非你要研究协议本身。
老实说一句：FastMCP 文档只覆盖 Python，TS 这边没有同等量级的封装。Patterns 段假设你写过 FastAPI 或类似框架，纯小白上来读 middleware 和依赖注入那两节会懵——建议先在 FastAPI 里写过两三个项目再回头看。
坑 5：误以为 anthropics/skills 跟 MCP 没关系
anthropics/skills 是 Anthropic 官方放出的 17 个完整 Skill 示例，包括 PDF 处理、PowerPoint 生成、Excel 操作、Webpage screenshot 等。我一开始以为 Skill 跟 MCP 是两件不同的事就跳过了。
后来发现：Skill 是 Claude 端的能力打包，MCP 是协议层，但 Skill 的实现里很多用到了 MCP server。这个 repo 是看"工业级 Skill 怎么组织"的最佳样本——每个 Skill 都有完整的 SKILL.md（说明）+ 实现代码 + 测试用例。
吐槽：repo 几乎没有 onboarding 文档，README 短到只能告诉你"这是 skills"，新手很容易不知道从哪个 Skill 开始读。建议从 pdf 这个最经典的入门，再看 webpage-to-markdown 学怎么调外部服务，看完这两个再去看更复杂的 xlsx。
免费，MIT 协议。
5 个坑之外，还想说一句关于"环境配置"
写这篇前我跟一位在大厂做 AI infra 的朋友聊过 MCP，他当时第一句话是："写 server 是简单的，难的是端到端跑通。"我那时候没太理解，跑完 5 个坑之后才反应过来——MCP 这套东西涉及的链条比看起来长：你机器上的 Python 环境、虚拟环境管理工具（uv / pip / poetry）、MCP server 进程本身、Claude Desktop 或 Cursor 的配置文件路径、配置文件里的 command 绝对路径、env 变量的传递方式、transport 类型（stdio / SSE / Streamable HTTP）、本地防火墙——任何一个环节出问题都会让你"server 看起来跑起来了但 Claude 就是调不到"。
我后来在匠人学院的一次内部分享里讲过这件事，结论是：MCP 这门技术门槛不高，但坑分布得很散。 你不会在某一处被 block 一整天，更常见的是每个小地方花 15 分钟，加起来一下就是一下午。所以新手最好有人能直接看你屏幕指出"你这里少了个 absolute path"那种支援，自己埋头查文档效率最低。
那剩下的三个资源呢
Anthropic Academy / Skilljar（anthropic.skilljar.com）：Anthropic 自己的官方培训门户，13 门左右免费课，覆盖 Prompt Engineering、Tool Use、Claude Code、MCP、Agent Building。MCP 那门课内容跟官方文档高度重合，但有视频 + quiz，对不喜欢读纯文字的人友好。课程节奏偏慢，视频里讲的东西文档 10 分钟能读完。优点是能拿到 Anthropic 官方的 completion 凭证，简历上能写一行"Anthropic Academy: MCP Fundamentals"。
菜鸟教程 MCP 协议页（runoob.com 站内搜 "MCP"）：菜鸟教程的优势永远是"30 分钟把概念扫一遍"，是什么 / 为什么 / 怎么用 / 一个最小例子。给完全没接触过 AI 协议的人 30 分钟入门用。跑过 hello world 之后这页面就再也用不到了，不要指望它教你工程实践。
匠人学院 AI Engineer Bootcamp 里的 MCP 模块（jiangren.com.au/learn/ai-en… MCP 放到 AI Engineer Bootcamp 当中一周内容来教，没单卖。跟前面公开资源相比，唯一差异化的点是中文授课加上"做—交—改"的导师 review 闭环：学员在 MCP 这一周末尾要交一份自己写的 server——常见的选题是 Notion 同步、对接公司 API、或包一层数据库查询工具——由华人导师阅读代码、给中文反馈。这一段是公开资源没法替代的，文档教不了"针对你这份代码该改哪里"。不过 MCP 嵌在四周 Bootcamp 里作为其中一个模块，单独冲着 MCP 来会觉得节奏绕；只想学 MCP 不想跟 Agent / RAG 一起学的人，整门课的性价比就比较低。
我自己走过来的学习路线
照着下面顺序走，大概一周时间能从"听过 MCP"走到"写过自己的 MCP server"。
- 第 1 步（30 分钟）：菜鸟教程 + 知乎《MCP 一篇就够了》。先把"MCP 是什么、为什么会出现、和 Function Calling 啥关系"在脑子里建好。这一步纯阅读不动手。
- 第 2 步（1 小时）：Anthropic 官方文档 Introduction + Quickstart。Quickstart 里那个 weather server 必须自己跑通。跑不通先解决环境，别往下走。
- 第 3 步（2 小时）：用 FastMCP 跑通一个 hello world，然后改成"调一个真实公开 API"（查天气、查股票、查 GitHub repo）。目的是让你脱离 reference 实现，自己拼一个 tool 出来。
- 第 4 步（半天）：去 anthropics/skills 挑一个跟你业务相关的 Skill，把代码读完、跑起来、改一处行为。这一步是看"工业级代码怎么组织"。
- 第 5 步：自己想一个真实业务场景的 MCP server——对接公司内部 API、对接 Notion、对接数据库都行。从需求到代码到部署到接进 Claude Desktop / Cursor，全流程自己走一遍。这一步走完，可以在简历上写"会写 MCP server"。
- 第 6 步（可选）：如果第 5 步发现没人 review 你的代码、不知道写得行不行、想要求职导向的反馈，可以考虑匠人学院 AI Engineer Bootcamp 的 MCP 模块——会有中文导师改代码并给评语。不是必选项，能自学走到这步的人可以自己继续。
最后回答几个常被问的问题
MCP 和 Function Calling 啥区别？ 一个在模型层一个在协议层。Function Calling 是模型本身把"我要调某函数"序列化成 JSON 输出的能力；MCP 是工程协议，规定 server 端如何暴露 tool、client 端如何发现并调用、走哪种 transport。换言之：意图怎么表达归 Function Calling，意图怎么跨进程跨语言送到工具再把结果送回来归 MCP。两者不冲突。
学 MCP 之前要先学 LangChain 吗？ 不用。两条相对独立的技术线——LangChain 是 Agent 编排框架，MCP 是 tool 协议层。
Python 还是 TypeScript 写 server？ 看生态成熟度。Python 有 FastMCP 高层封装，写起来快、文档全；TS 这边官方 SDK 是底层接口，要自己写更多胶水代码，但跟前端工具链（VS Code 插件、Cursor 扩展）配合更顺。两边都能写出 production server。
MCP 能用在生产环境吗？ 能，但 transport 必须分场景挑。stdio 只走本地 IDE 集成；多用户远程访问要换 SSE 或 Streamable HTTP，并把鉴权 / 限流 / 可观测性自己接进来。FastMCP 文档 Patterns 段有相对完整的工程范例。
学完 MCP 能找到工作吗？ MCP 一项不够。它是 AI Engineer 岗位的加分技能之一，需要跟 RAG、Agent、Eval、Prompt Engineering 组合出现才有说服力。从 2025 下半年开始，澳洲、美国的 AI Engineer 招聘 JD 已经把 "tool use / agent frameworks / MCP" 写进显式要求里。匠人学院的 AI Engineer Bootcamp 就是把这一整组能力打包做的学习路径。
写完这篇是想说：MCP 这事不难，难的是踩坑的时候没人告诉你"哪一步是真的卡点、哪一步是错觉"。8 个资源没有最好——按上面的路线走，挑跟你目标契合的资源深读，剩下的当 reference 摆着。
我现在带匠人学院 AI Engineer 项目里的几位同学过 MCP 模块，最常给的建议就是两条：第一，先把"我能在 Claude Desktop 里调到一个我自己写的 tool"这件事跑通，然后再纠结架构和 transport——多数人在概念阶段花了太多时间，反而错过了动手期；第二，写第一个真实业务 server 的时候，越小越好，能用一个 tool 解决的问题不要塞两个，先把流程跑顺再加东西。这两条听起来很朴素，但能避开一大半新手会踩的设计坑。
留个评论钩子：你跑通自己第一个 MCP server 的时候是哪天？踩到的最大一个坑是什么？欢迎在评论区写下来，我会一条条回。 更多详情可以在JR Academy匠人学院网站查看：jiangren.com.au/program-cou…
