自建 MCP Server 怎么写：3 步用 Python 暴露你的工具：从配置到验证的完整步骤

想让 AI 直接查你公司的订单库、调内部接口，它却只回一句"我没有这个能力"？根因很简单：你没给 AI 接上工具。最快的解法是用 MCP 协议把你的本地函数包成一个 MCP Server，AI 就能像调用自带能力一样随时调用。本文用 Python 走通"定义工具、启动服务、接入验证"三步，从配置到验证一次讲清，连版本要求与常见失败路径都一并说明。看完你就能把任意一个本地函数，变成 AI 随叫随用的能力。

先看结论

三步对应"能跑通"的最低闭环，先别追求花哨功能，跑通再扩展。

💡 小提示：自建 MCP Server 的本质，是把"你的代码能力"翻译成 AI 能理解的 JSON 工具描述。先过一遍 MCP 文档教程 理解协议全貌。

一、第一步：用 SDK 定义工具函数

先装好官方 Python SDK，然后用装饰器把一个普通函数声明成 MCP 工具。工具的核心是"名字、描述、参数 schema、返回值"四件套，AI 靠这些决定要不要调用它。注意版本：FastMCP 要求 Python 3.10 及以上，装之前先 python --version 确认本机版本是否满足。

pip install mcp

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("w3cschool-demo")

@mcp.tool()
def query_order(order_id: str) -> str:
    """根据订单号查询订单状态。

    Args:
        order_id: 订单的唯一编号
    """
    # 实际项目里这里连数据库；示例直接返回
    return f"订单 {order_id} 当前状态：已发货"

if __name__ == "__main__":
    mcp.run()

上面这段代码就是最小可用的工具函数。描述写在 docstring 里，AI 会读它来判断何时调用。参数类型标清楚，协议才能正确生成 schema。完整字段说明见 MCP Server 详解。

⚠️ 注意：docstring 别写空。AI 完全靠描述选择工具，描述含糊它就会乱调用或干脆不用。

二、第二步：启动服务并选好传输方式

工具定义好之后，要让 Server 真正跑起来。MCP 常见两种传输：stdio（本机进程间）和 http（远程）。新手先跑 stdio，最简单也最关键。适用边界：stdio 只适合本机客户端直连，要给别人远程用才上 http，两种传输别在同一个服务里混用。

if __name__ == "__main__":
    # 默认 stdio 传输，适合本地客户端直连
    mcp.run(transport="stdio")

运行方式（未在本机执行，依据官方 SDK 文档）：

python server.py

预期结果（未在本机执行）：进程启动后保持监听，不报错退出，等待客户端连接。如果你的客户端走 http，就把 transport 改成 "http" 并指定端口——但别在一个服务里混用两种传输，否则客户端对接会失败。Python 基础不熟的话，Python3 教程 能帮你补齐语法。

三、第三步：接入客户端并验证调用

服务跑起来后，要在 AI 客户端里登记这个 Server，然后真正发起一次调用验证它"通了"。验证不是看它启动没报错，而是看 AI 能不能成功拿到返回值。

以常见的客户端配置为例，把 Server 登记进去：

{
  "mcpServers": {
    "w3cschool-demo": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

验证步骤（未在本机执行）：在客户端里问"查一下订单 A100 的状态"，观察 AI 是否调用了 query_order 并返回"已发货"。如果它回答"我没有这个工具"，说明登记没生效或传输不匹配；如果返回报错，多半是参数 schema 与函数签名对不上。这类 AI 编程接入的边界与失败排查，正是工程里最费时间的部分，AI 编程技能教程 里还有更多实战思路。

不是每个能力都要自己造 Server。如果你的工具只是偶尔调用一次、或已有现成 HTTP 接口，直接用函数调用或现有 SDK 更快。但当 AI 需要反复、稳定地操作你的私有资源（订单库、内部系统、本地文件），并且希望换一个客户端也能复用同一套能力时，自建 MCP Server 的投入才真正划算。判断标准很简单：这个能力会被多个 AI 客户端反复用到，且涉及你独有的数据源——那就值得封装成 Server。

四、上线前自检清单

Server 跑通后先别急着接业务，用这张清单过一遍，避免"能启动但工具调不通"。

• 每个工具的 docstring 是否写清了"干什么、要什么参数"？描述含糊，AI 就会乱调用或干脆不用。
• 参数 schema 是否与函数签名对得上？对不上，客户端能列出工具却实际调不动。
• stdio 与 http 是否只选一种？在一个服务里混用两种传输，客户端对接会直接失败。
• 是否真的发起了一次调用验证？验证不是看它启动没报错，而是看 AI 能否成功拿到返回值。
• 多个工具是否描述区分清楚？工具多了不区分，AI 容易选错那一个。
• 错误路径是否也测过？故意传一个错误参数，确认返回的是可读报错而非整段崩溃。
• 是否给 Server 起了有意义的名字？多个 Server 并列时，名字含糊会让你分不清哪个是哪个。
• 是否记录了启动命令？同事复用时直接复制即可，不用再翻代码找入口。

清单全过，自建 MCP Server 才算真正可用；任一项存疑，先补再扩大工具数量。

总结

自建 MCP Server 的三步是"定义工具、启动服务、接入验证"。最容易翻车的不是写代码，而是忘了验证——服务能启动不等于工具能被正确调用。把每个工具的描述和参数写准，跑通最小闭环后再往上加功能，远比一口气写一堆用不上的工具来得稳。下一步建议从 Python 教程里挑一个真实函数练起，比如查库存或发通知，先跑通再扩展。

常见问题

Q：stdio 和 http 该选哪个？

A：本机客户端直连首选 stdio，零配置最稳；要给别人远程用才上 http。别在一个服务里混用，客户端对接会直接失败。

Q：工具定义了但 AI 不调用怎么办？

A：九成是 docstring 描述太含糊，或参数 schema 与函数签名对不上。把"这个工具干什么、要什么参数"写清楚，AI 才会用。

Q：一个 Server 能挂多个工具吗？

A：能，而且推荐。用同一个 FastMCP 实例多写几个 @mcp.tool() 即可。工具多了记得在描述里区分清楚，避免 AI 选错。

Q：MCP 和普通的 HTTP API 有什么区别？

A：普通 HTTP API 要你自己在代码里拼请求、解析响应；MCP 把"工具、资源、提示"统一成一份协议描述，AI 客户端能自动发现并调用。你写一次工具定义，任意支持 MCP 的客户端都能直接用，不用为每个前端单独适配。

延伸学习

想把这个能力系统补上，可以按这个顺序：

1. 想系统学 Python，Python3Course 课程 是边学边练的形式；
2. 也看看这篇笔记 通俗易懂一文讲透什么是 MCP，先建立协议直觉；
3. 想深入客户端对接，MCP 客户端教程 能帮你少踩坑。