如果你最近在看 Agent、工具调用或 AI 应用集成，大概率已经见过 MCP 这个词。但很多人看完概念介绍之后，还是会卡在同一个问题上：MCP Server 到底怎么写，最小可用版本需要哪些东西？
这篇文章不讲太大而全的架构，而是只解决一个问题：怎么从 0 写一个最小可用的 MCP Server，并理解它为什么能工作。
你读完之后，至少可以得到三样东西：
- 知道 MCP Server 在整个链路里扮演什么角色
- 知道一个最小可用版本应该提供哪些能力
- 知道从“能跑”到“能用”之间还差哪些工程化动作
如果你是开发者，最适合把这篇文章当作 MCP 入门后的第一篇实操文。
一、先讲清楚：MCP Server 到底在做什么
先别急着写代码，先把角色关系搞清楚。
你可以把 MCP 理解成一套让模型或 Agent 以更标准方式调用外部能力的协议。这里最关键的不是“协议”两个字本身，而是它把原来零散的工具接入方式，变成了一个更统一的交互结构。
在这个结构里，MCP Server 负责的事情很明确：
- 暴露自己有哪些能力可以用
- 告诉客户端每个能力怎么调用
- 接收调用请求
- 返回结果
换句话说，MCP Server 本质上就是一个把工具能力标准化暴露出来的服务端。
它不一定复杂，也不一定一开始就要连数据库、鉴权、队列或完整业务系统。对入门来说，你完全可以先做一个只提供 1 到 2 个工具的最小版本。
二、为什么要先做“最小可用”版本
很多人一开始就想做一个很完整的 MCP Server：
- 接很多工具
- 管理很多资源
- 做权限控制
- 做日志系统
- 做多环境配置
这在工程上当然有意义，但对第一次上手来说，往往会让问题变得不清楚。
你很难分辨：
- 是协议没理解清楚
- 是工具注册错了
- 是参数结构不对
- 还是客户端接入方式有问题
所以更好的顺序是：
先做一个最小可用版本，只验证“定义工具 → 被客户端发现 → 成功调用 → 返回结果”这条链路能不能跑通。
只要这条链路通了，后面的扩展才有基础。
三、一个最小可用 MCP Server 应该包含什么
如果目标只是“跑通”，最小版本通常只需要下面几样东西。
1. 一个服务端进程
它负责启动 MCP Server，并对外暴露自己的能力。
2. 至少一个工具
比如：
- 获取当前时间
- 计算两个数字之和
- 读取某个固定目录下的文件
- 返回一段固定文本
这类工具的优点是：
- 输入简单
- 输出明确
- 容易验证是否调用成功
3. 工具的名称、描述和参数定义
这一点非常关键。
客户端之所以能发现并调用你的工具，不是因为“你写了某个函数”，而是因为你把这个函数包装成了一个带有元信息的可调用能力。
至少要让客户端知道：
- 这个工具叫什么
- 它是干什么的
- 需要什么参数
- 参数类型是什么
- 调用后会返回什么
4. 一个稳定的返回结果
最小版本不要一上来就返回过于复杂的结构。
先保证调用结果清楚、可读、好验证。这样排查问题会快很多。
四、最小示例应该选什么工具
第一次写 MCP Server，不建议直接上复杂业务接口。
更推荐你从下面三类里选一个。
方案 A：时间工具
比如 get_current_time。
优点：
- 不依赖外部系统
- 容易看出结果是否正确
- 适合验证调用链路
方案 B：计算工具
比如 add_numbers。
优点：
- 参数结构简单
- 很容易测试不同输入
- 方便理解工具调用过程
方案 C：受限文件读取工具
比如只允许读取某个测试目录下的文件。
优点：
- 更接近真实工具场景
- 能开始理解权限边界问题
如果你只是第一次跑通，最推荐从时间工具或计算工具开始。
五、实现时可以按这 6 步走
下面不强绑定某个 SDK 的具体写法，而是先讲最通用的实现顺序。不同语言和 SDK 细节会有差异，具体接口以官方最新文档为准。
第一步：初始化 MCP Server
你需要先创建一个服务端实例。
这一层通常会涉及：
- 服务端名称
- 版本信息
- 基本初始化配置
这一步的目标不是做很多事，而是让服务端先具备“声明自己是谁”的能力。
第二步：注册工具
这是最核心的一步。
你需要定义一个工具，并明确它的：
- 名称
- 描述
- 输入参数
- 执行逻辑
例如，一个最简单的加法工具，逻辑上大概是：
- 接收
a和b - 计算
a + b - 返回结果
这里最容易出错的不是计算本身，而是：
- 参数名和实际传入字段不一致
- 参数类型定义不清
- 描述写得太模糊，导致模型不知道什么时候该用它
第三步：实现工具逻辑
最小版本的工具逻辑应该尽量简单。
比如：
- 不要依赖太多外部服务
- 不要引入复杂状态
- 不要把错误处理写得过度复杂
目标只有一个：让工具能稳定返回预期结果。
第四步：启动传输层
MCP Server 需要和客户端建立可通信的通道。
不同接入方式可能会用不同传输方案。你现在不需要一开始把所有模式都学完，只要先明确一点：
没有传输层，工具就只是本地代码；有了传输层，客户端才有机会发现和调用它。
如果你是第一次上手，建议优先选文档里最基础、最容易调试的一种方式。
第五步：在客户端里接入并测试
写完服务端之后，不算完成。你还要验证客户端能不能：
- 识别到你的 MCP Server
- 发现你注册的工具
- 正确发起调用
- 正确拿到结果
这一步是很多人最容易忽略的。
你以为“服务端已经启动”就代表成功了，但实际上客户端没识别到工具、配置写错、路径不对、协议不匹配，都可能导致最终不可用。
第六步：记录问题并做最小修正
第一次跑通时，很可能会遇到这些问题：
- 工具列表没显示
- 参数校验失败
- 返回结构不符合预期
- 客户端没有正确连接到服务端
- 描述不清导致工具不被优先使用
不要一口气重构。
先只修能阻塞“跑通”的问题，把最小链路打通再说。
六、如果你更想看代码，最小示例应具备哪些结构
虽然不同 SDK 写法不同，但一个最小可用 MCP Server 的代码结构，通常会有下面这些部分：
1. 导入 MCP 相关依赖
2. 创建 server 实例
3. 定义一个工具
4. 描述工具的输入参数
5. 实现工具处理逻辑
6. 启动 server
7. 在客户端完成配置并测试如果你已经有一定开发经验，这个结构其实不难。真正难的是后面这些问题：
- 工具描述怎么写得让模型更容易用对
- 参数设计怎么避免误调用
- 哪些能力应该暴露，哪些不该暴露
- 权限边界怎么控制
但这些都属于“从能跑到能用”的下一阶段问题。
七、第一次上手最常见的 5 个坑
1. 一开始就接复杂工具
比如一上来就接数据库查询、浏览器自动化、文件系统全量读写。
问题不是这些不能做，而是你会很难知道错误到底出在哪一层。
2. 工具描述写得太抽象
如果工具描述只是“处理数据”“执行任务”“读取信息”，模型很难准确判断何时调用。
更好的写法应该明确用途和边界。
例如：
- 用于获取当前系统时间
- 用于计算两个数字之和
- 用于读取指定测试目录中的文本文件
3. 参数设计不清楚
参数名、类型、是否必填，这些如果定义得含糊，调用成功率会明显下降。
4. 忽略权限边界
哪怕是最小版本，也不要默认暴露危险能力。
例如文件读取工具，不要一开始就允许读取整台机器上的任意文件。更好的做法是只开放一个测试目录。
5. 只看服务端日志，不看客户端表现
MCP 是一条完整链路。服务端启动成功，不等于客户端就一定能正常调用。
八、从“最小可用”到“真正可用”，下一步该补什么
当你已经跑通最小版本后，下一步不要急着加十几个工具。更合理的顺序通常是下面这样。
1. 补错误处理
至少要让错误信息足够清楚，方便判断是参数问题、连接问题还是工具内部执行失败。
2. 补输入校验
特别是数值、路径、枚举类参数。输入校验越清楚，工具越稳定。
3. 补权限控制
如果工具涉及文件、命令执行、外部 API、浏览器或系统能力，就必须认真考虑权限边界。
4. 补日志与调试信息
最小版本可以简单，但可观察性不能长期缺失。否则一旦工具多了，很难排查。
5. 补工具设计规范
工具数量增加后，要统一这些内容：
- 命名风格
- 描述写法
- 参数定义方式
- 返回结构格式
否则后面会越来越乱。
九、什么时候说明你真的学会了
很多人会把“照着示例跑起来”当成学会了，但更可靠的判断标准是：
- 你能自己解释 MCP Server 的角色
- 你能自己设计一个简单工具
- 你能排查为什么客户端没调起来
- 你能知道一个工具为什么不该暴露太大权限
- 你能从单工具扩展到多工具，而不把结构写乱
做到这些，才算真的入门。
十、结语：先跑通，再工程化
第一次写 MCP Server，最重要的不是写得多完整，而是把最小链路跑通。
你真正要验证的，是这条路径：
定义能力 → 暴露能力 → 客户端发现 → 成功调用 → 返回结果。
只要这条链路跑通，你就已经跨过了最关键的一步。
后面的权限控制、错误处理、日志、工具设计规范，都是在这个基础上逐步补齐的工程化工作。
如果把这件事压缩成一句话，那就是：
第一次写 MCP Server，不要追求大而全，先做一个最小但真的能用的版本。
摘要建议
这篇文章围绕“怎么写一个最小可用的 MCP Server”展开，重点讲清 MCP Server 在整个调用链路中的角色、最小版本需要包含哪些能力，以及开发者第一次上手时应如何按步骤完成初始化、注册工具、实现逻辑、接入客户端和完成调试。文章同时总结了常见误区，并给出从“能跑”到“真正可用”的工程化补充方向。
关键词建议
- MCP Server
- MCP 教程
- Model Context Protocol
- Agent 工具调用
- AI 开发教程
- MCP 入门
