给自己的项目接一根线:从 0 写出第一个 MCP 服务器
智能体看得见你项目的代码,却够不着你的数据。MCP 服务器就是补上这根线:查书、加书、改状态三个小工具,让智能体在你批准的前提下直接操作数据库。本文按官方快速上手,从 0 写出第一个 MCP 服务器。

先把这篇的边界说清楚。站里已经有讲调别人 API 的文章,比如《API 韧性:熔断与重试》和《Webhooks 集成》,还有讲搜索的几篇指南。这篇讲的不是"怎么调别人的接口",而是反过来:把你自己的数据和功能包成工具,递到智能体手里,让它直接替你操作。调 API 是你去找别人,MCP 服务器是你把自家后门打开一条缝,让智能体走进来干活。另外,站里同一轮还有一篇《别再把同一段话贴十遍了:给智能体写一份 SKILL.md 技能包》,两篇是搭档:技能包是给智能体的说明书,MCP 服务器是给智能体的操作杆。说明书告诉它什么时候、用什么顺序干活,操作杆让它真的能动手。
下面用到的"小书架"是一个虚构的练手项目:一个用 AI 帮着写出来的个人藏书管理小应用,有前端、有后端、有数据库。本文所有以它为例的代码和配置都是为了讲清楚做法编出来的简化版,不是能直接跑的生产代码。所有关于 MCP 协议的规则、版本号和接口名,都来自 MCP 官方文档,来源见文末。
智能体看得见,却够不着
先对一下症状。你的"小书架"跑起来了,书都存在自己的数据库里。有一天你想让智能体帮你整理藏书,你说"把今年买的、还没读完的书列出来",智能体说"好的",然后反问你:数据在哪?导出成文件发我?于是你去数据库里导一份 CSV,贴进对话,再说一遍"今年买的、没读完的"。下次你想加一本书,又得自己打开管理后台填表单。智能体看得见你的代码,却够不着你的数据,中间永远隔着一个你——负责复制粘贴的人。
常见的凑合办法有两个,都有毛病。第一是每次都把数据导出来贴进去。数据量一上来就贴不下,而且贴进去的是快照,智能体加完一本书,数据库里的真实数据并不会变,你还得自己再去改一遍。第二是给智能体开数据库直连、把账号密码写进提示词里。这等于把家门钥匙贴在门上:智能体是能干活了,但它也能顺手删库,而且密码还躺在聊天记录里。
缺的东西不是"更聪明的模型",而是一根线:一条让智能体在受控的前提下读写你的数据的标准通道。这根线就是 MCP 服务器。你写一个很小的服务器,把"我要让智能体干的三件事"暴露成工具:查书、加书、改状态。智能体需要的时候自己调用,你在旁边看着它调了什么、改了什么。数据不用导出,密码不用进聊天记录,干活的范围就是你暴露的那三个工具,多一个都没有。
MCP 一句话:AI 的 USB-C
官方文档用的比喻很贴切:MCP 是 AI 应用的 USB-C 口。以前每接一个外部系统都要单独写一套对接办法,就像每台设备都要配一根专用充电线;有了统一的口,写一次,到处都能插。MCP 是个开放标准,不是某一家公司的私有协议,Claude、ChatGPT、VS Code、Cursor 这些客户端都支持,你的服务器写一次,就能被很多客户端用。
一张图先把角色分清楚。整个结构里有三方:Host 是你用的 AI 应用,比如 Claude 桌面版、Claude Code;Client 是 Host 里面负责连 MCP 的那部分;Server 是你写的这个小服务器。Host 里的 Client 去连你的 Server,Server 再去碰你的数据和系统。智能体本身不直接碰你的数据库,它只跟 Client 说话,Client 再按协议跟 Server 说话。中间这条线走的是 JSON-RPC 消息,简单说就是"你调我的工具,我回你结果"的固定格式。
服务器能提供三种能力,官方文档叫三件套。Tools 是"能调用的函数",比如查书、加书,调用之前通常要经过用户同意;Resources 是"能读的文件型数据",比如一份书单、一份配置;Prompts 是"写好的模板",帮用户把一件事说清楚,比如"整理藏书"的标准说法。这篇只讲 Tools,因为对 vibe 项目来说,Tools 是最先用上、也最有用的那一件。等你有一个工具跑通了,再去加 Resources 和 Prompts 也不迟。
这里要先纠正一个常见的误会:MCP 服务器不是"又一个后端服务"。它不负责用户登录、不负责页面渲染、不负责跑定时任务,它只干一件事:把你指定的几个操作,用标准格式递给智能体。你的"小书架"后端该怎么写还怎么写,MCP 服务器只是它旁边一个很薄的翻译层。
上图就是这篇要搭出来的东西:左边是智能体在的 Host,中间是 Client,右边是你写的服务器,服务器后面才是你的数据库。智能体到数据库之间隔着两道门:Client 只按协议说话,服务器只暴露你点过头的三个工具。
先选语言,再选传输方式
动手之前先定两个选择,都是官方快速上手文档里写明的。
第一个选择:用什么语言写。官方快速上手给了 Python、TypeScript、Java、Kotlin、C#、Ruby、Rust、Go 八种语言的版本,逻辑都一样:搭一个服务器、暴露两个工具、接进客户端测一遍。对 vibe 项目来说,选你项目本身用的语言最省事:"小书架"后端是 Python,那就用 Python 写,Python 3.10 以上、MCP Python SDK 2.0.0 以上,用 uv 建项目。你的项目是 TypeScript,那就用 TypeScript 版,Node.js 20 以上。语言只是外壳,协议是一样的,选顺手的就行。
第二个选择:服务器和客户端之间用什么传输。两种:stdio 和 Streamable HTTP。stdio 是"本地启动、管道通信":客户端启动你的服务器进程,两边通过标准输入输出传消息。Streamable HTTP 是"跑在网上的服务":服务器部署在某个地址,客户端通过 HTTP 连过来。刚开始做,选 stdio 就够了。你的服务器就跑在你自己的电脑上,智能体在同一个环境里调它,不用部署、不用配域名、不用考虑公网安全。等哪天你要让不在同一台电脑上的智能体也能用,或者要给多个人用,再考虑 HTTP。
选 stdio 有一个必须刻在脑子里的规矩,官方文档在每个语言的版本里都重复了一遍:stdio 服务器绝对不要往标准输出写日志。因为消息本身就走标准输出,你打印一句日志,消息就被污染了,服务器当场断线。Python 里不要用 print,TypeScript 里不要用 console.log。日志要写到标准错误输出,比如 Python 的 logging 模块默认就是写 stderr,TypeScript 用 console.error。HTTP 服务器没有这个限制,因为消息走 HTTP 响应,不走标准输出。
从 0 写第一个服务器:三个工具就够了
官方快速上手做的是一个天气服务器,暴露 get_alerts 和 get_forecast 两个工具:一个查天气预警,一个查天气预报,数据来自美国国家气象局的公开接口。照着它改一改,就能变成"小书架"的版本:search_books 查书、add_book 加书、update_status 改阅读状态。三个工具,都是先读后写,读的先做,写的后做。
先搭架子。按官方文档的步骤,用 uv 建好项目、装好 mcp 包之后,服务器的代码骨架其实很短:建一个 MCPServer 实例,名字就叫 little-bookshelf,然后一个一个注册工具。Python SDK 有个很贴心的地方:工具的定义是直接从函数的类型标注和 docstring 生成的,你写个普通函数、把参数类型和一句话说明写清楚,工具的输入格式就自动有了。不用再手写一份 JSON Schema,也就少了一个对不上的地方。
工具怎么写,举一个例子。search_books 接受两个参数:query 是要搜的关键词,status 是阅读状态,比如"想读""在读""读完",不传就是全部。函数里面去查数据库,把结果拼成一段人能读的文字返回。重点在 docstring 那一句话:"按关键词和阅读状态搜索藏书"。智能体就是靠这句话决定什么时候调这个工具的。描述写得越具体,调用越准:写"搜索藏书"不如写"按关键词和阅读状态搜索藏书";写"管理书籍"就更糟,智能体根本不知道这个工具到底能干什么。
写工具描述有三个忌讳。第一是写得像标题:"图书管理工具"。第二是把所有能力都塞进一个工具:"管理藏书,包括搜索、添加、修改、删除"。一个工具只干一件事,三个工具就是三个工具,别为了省事合并成一个万能工具。第三是描述里藏着没说的副作用:一个叫 search_books 的工具偷偷改了数据库,智能体下次就不敢调它了。名字、描述、实际行为三者必须一致,这条规矩比任何技巧都重要。
add_book 和 update_status 是写操作,写的时候要多想一步:万一智能体传错了参数怎么办?比如书名是空的、状态写了个不存在的值。好的做法是在工具里面先校验:书名为空就直接返回一句"书名不能为空,请再确认",状态不在"想读/在读/读完"这三个值里就返回"状态只能是想读、在读、读完"。别等着数据库报错再把一堆英文错误信息抛给智能体。工具返回的错误信息是给智能体看的,要写成人话,让它能自己纠正了再试一次。
服务器跑起来之前,先在心里过一遍清单:工具是不是只有三个,有没有顺手多加了一个;每个工具的描述能不能让一个没看过代码的人猜出它是干什么的;写操作有没有校验、有没有返回人话错误;代码里有没有 print 或者 console.log 偷偷往标准输出写东西。清单全过,再启动。
接进客户端,亲手调一次
服务器写完了,还没完。接进客户端、亲手调一次,才算真的通了。官方文档以 Claude 桌面版为例:打开配置文件 claude_desktop_config.json,在 mcpServers 下面加一项,名字叫 little-bookshelf,内容是启动命令:用 uv、到哪个目录、跑哪个文件。写完保存,重启 Claude 桌面版。如果配置没问题,界面上会出现 MCP 的入口,里面能看到你注册的三个工具。
配置里最容易错的是路径。官方文档特意强调要用绝对路径:uv --directory 后面跟的是服务器文件夹的绝对路径,不是相对路径。相对路径在你自己的终端里能跑,换个启动方式就找不到了。写完配置先别急着重启客户端,先在终端里手动跑一遍启动命令,看服务器能不能正常启动、会不会立刻报错。手动能跑,再去配客户端。
验证的时候有个好用的工具:Inspector。官方文档提到了 Inspector CLI,可以列出服务器的工具、实际调一次看看返回什么。先在 Inspector 里把三个工具都调一遍:search_books 搜一个关键词,看返回的书单对不对;add_book 加一本假书,看数据库里是不是真的多了一条;update_status 把那本假书改成"读完",再搜一次确认状态变了。三个都通,再去客户端里用自然语言试:"帮我把《三体》加进藏书,状态是在读。"如果智能体调了 add_book、参数都对、数据库里多了一条记录,这根线就通了。
这里还有个版本细节值得知道,TypeScript 快速上手里写得很清楚:现在的服务器要用 serveStdio 来启动,它会跟客户端协商协议版本,2026-07-28 的新客户端和 2025 年的老客户端都能接。如果你还按老办法手写 server.connect(new StdioServerTransport()),服务器只能服务 2025 年的老客户端。用新版 SDK、按官方文档的最新写法走,就不用管这个。Inspector 也分协议时代:默认是 legacy 时代,只测 2025 年的握手,要加 --protocol-era modern 再跑一遍,确认新客户端也能列出你的工具。两个时代都列出三个工具,才算真的兼容。
三个一定会踩的坑
第一个坑,日志写错了地方。上面已经说过一遍,这里再强调一次,因为这是新手最常见的死法:stdio 服务器里任何往标准输出写的东西都会把消息弄坏。Python 的 print、TypeScript 的 console.log、还有某些库默认往标准输出打的启动横幅,都是嫌疑犯。症状很典型:服务器在终端里手动跑得好好的,一接客户端就断线、工具列表出不来。先查日志写到哪去了,九成就是这个。
第二个坑,工具描述写得太烂。智能体决定调哪个工具,几乎只看名字和描述。你把三个工具都起名叫 manage_books、manage_books_v2、manage_books_new,或者描述都写成"处理藏书相关操作",智能体只能靠猜。猜错了,它调错工具、改错数据,你还得收拾。修的办法很简单:名字用动词开头,search_books、add_book、update_status;描述写清楚"输入是什么、输出是什么、什么时候用"。写完之后找个没看过代码的人读一遍,他能猜出每个工具是干什么的,才算合格。
第三个坑,权限和安全想得太晚。工具一旦暴露出去,智能体就能调,调错了也能改你的数据。所以写操作要守三条线:第一,默认只读先行。先只暴露 search_books 这类读操作,跑顺了再加 add_book、update_status。读操作调错了最多返回一堆错数据,写操作调错了是真的改了你的库。第二,写操作要经过用户同意。MCP 的设计就是工具调用前要用户批准,别为了省事把审批关掉。第三,密钥和密码不要进仓库、不要进技能描述、不要进工具描述。服务器要连数据库,连接串放在环境变量或者本机配置文件里,代码里只读变量,不写明文。
安全这件事上,官方文档还有专门的安全章节,值得单独读一遍。核心思想就一句话:服务器暴露出去的每一个工具,都是你亲手交给智能体的权力。权力清单越短越好,权限越小越好,审计越清楚越好。每次加一个新工具之前,先问一句:这个工具最坏能干什么?如果答案让你冒汗,先收紧再说。
什么时候该上 HTTP,什么时候别折腾
stdio 跑通之后,很多人马上想"要不要部署到网上"。先别急。判断标准很简单:使用者是不是只有你、服务器和智能体是不是在同一台电脑上。如果两个答案都是"是",stdio 就够了。部署成 HTTP 服务要多操心一堆事:域名、HTTPS、鉴权、谁能调、调多少次、日志存哪。你的"小书架"只是你自己在用,这些成本纯属多余。
什么时候必须上 HTTP?三种情况。第一,智能体不在你电脑上,比如你用的是网页版客户端,要连你家里的服务器。第二,要给多个人用,比如团队共用一个藏书 MCP 服务器。第三,服务器本身就要长期在线、别人随时能连。到了这一步,传输方式要换成 Streamable HTTP,日志随便写标准输出也没事了,但安全清单要翻一倍:谁能连、用什么鉴权、每个工具的调用要不要审批、调用记录存多久。这些在官方文档的安全章节里都有,照着做,别自己发明。
还有一种情况要果断放弃:你要暴露的那个系统,本身就不该让智能体碰。比如生产数据库的写权限、能直接花钱的支付接口、能删用户数据的管理后台。这些不是"加个 MCP 服务器"能解决的问题,而是"根本不该给智能体开这个口子"的问题。正确的做法是中间再隔一层:只暴露一个"申请操作"的工具,真正执行的那一步还是由人来点。智能体可以帮你把申请单填好,但钱和数据,还是得人来点头。
先让一个工具跑通
如果你今天就想动手,清单只有五步,照着做,一个晚上就能跑通:
一、选语言。用项目本身的语言,Python 就用 Python,TypeScript 就用 TypeScript,别为了学新语言多花时间。二、只做一个读工具。先写 search_books,别的都不写。读工具调错了没后果,最适合练手。三、接进客户端。在 Inspector 里调一次,在 Claude 桌面版里用自然语言调一次,两次都通才算通。四、再加写工具。add_book 和 update_status 各加一个,校验和人话错误信息一起写上。五、把配置写进仓库。服务器代码、启动命令、配置示例都提交进仓库,下次换电脑、换人,都能照着重来一遍。
跑通一个工具之后,你会发现一件事:智能体和你自己的项目之间,隔着的那层窗户纸其实很薄。你缺的一直不是更强的模型,而是一根合规的线。线接上了,智能体就不再是只能看代码的旁观者,而是能帮你查数据、改状态、跑流程的搭档。而你要做的,只是把"它能干什么"这件事,亲手写进三个工具里,并且随时能收回来。
来源:Model Context Protocol 官方文档《What is the Model Context Protocol?》(https://modelcontextprotocol.io/docs/getting-started/intro ,2026-11-17 亲读,页面更新于 2026-11-09);《Build an MCP server》快速上手(https://modelcontextprotocol.io/quickstart/server ,2026-11-17 亲读,含 Python 与 TypeScript 版);技能包做法见本站《别再把同一段话贴十遍了:给智能体写一份 SKILL.md 技能包》。
评论 (0)
原始来源
相关文章
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。
JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。