1. 从“它没有这个能力”说起MCP 到底是个啥先说结论MCP 全称 Model Context Protocol模型上下文协议是一套让智能体用统一姿势调用外部工具的开放约定。你可以把它理解成“AI 世界的 USB-C 接口”——以前每个软件接工具都各玩各的你给 A 写的插件搬到 B 就废了有了 MCP工具写一遍所有支持这套协议的客户端拿来就能用。我为什么会去折腾它起因特别朴素。平时写代码、查资料都靠一个桌面端 AI 助手搭把手用着用着就想让它帮我盯一下服务器。我随口问“看看 C 盘还剩多少空间”它客客气气回我一句“我没有这个能力”。行吧复制粘贴大法继续。来回几次我烦了这活儿不该这么蠢于是决定自己动手。扒资料的时候 MCP 这个词反复往外蹦。搞清楚之后发现它的角色拆分很清晰跑智能体的软件算客户端提供工具的一方写 MCP 服务器两边按协议消息来往。对个人开发者来说这个思路太友好了——不用给每个软件单独伺候一遍。这篇就聚焦一件事用 Python SDK 从零写一个 stdio 型 MCP 小工具接给智能体并且用一次真实的工具调用验证它跑通。全程可复制环境是 Windows 11 Python 3.12其他系统把路径换一下就行。适合谁会写 Python 函数、想让 AI 帮自己干重复活的人。半天时间足够。2. 前置准备装 SDK、拿统一 Key、理清最小结构动手之前把三件事办了后面会顺很多。第一件装官方 SDK。命令行一行搞定pip install mcp[cli]装完可以顺手验证一下版本避免装到太老的包pip show mcp第二件准备一个统一 Key 通道。写 MCP 工具经常要调模型或外部接口如果每个工具都单独配一套 Key管理起来很乱。我这边用的是 TaoToken 的统一 Key 通道一个 Key 走通模型对话和工具调用省得在多个配置文件里来回改。先去控制台把 Key 建出来控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后先别急着写进代码等会儿在配置片段里统一填。接口地址用https://taotoken.net/api注意这个不带 UTM 参数是给程序调用的。第三件理清 MCP 服务器的最小结构。一个 stdio 型服务器其实就三块起一个 FastMCP 实例、用装饰器登记工具函数、最后mcp.run()走 stdio 通道。没有端口没有路由比想象中简单太多。这里有个细节值得单独拎出来说函数下面的说明文字会原样喂给模型成为它理解这个工具是干嘛的依据。说明写得含糊模型要么不理你要么瞎传参数。我后来才咂摸出这个味道——工具说明文字的质量直接决定模型用不用你的工具、怎么传参。所以别偷懒docstring 写清楚。3. 可复制配置三十行 server 代码 客户端 JSON先上服务器代码。新建一个文件叫my_mcp_server.py内容如下import shutil import json import urllib.request from mcp.server.fastmcp import FastMCP mcp FastMCP(my-tools) mcp.tool() def disk_free(drive: str C:) - str: 查询指定磁盘的剩余空间。drive 参数传盘符例如 C: 或 D:。 usage shutil.disk_usage(drive \\) free_gb usage.free / (1024 ** 3) total_gb usage.total / (1024 ** 3) percent usage.used / usage.total * 100 return f{drive} 剩余 {free_gb:.1f}G总容量 {total_gb:.1f}G占用率 {percent:.0f}% mcp.tool() def ip_location() - str: 查询本机公网 IP 的归属地信息。 with urllib.request.urlopen(https://ipapi.co/json/, timeout5) as resp: data json.loads(resp.read().decode()) return fIP {data.get(ip)} 归属 {data.get(city)}, {data.get(country_name)} if __name__ __main__: mcp.run()两个工具一个查磁盘一个查 IP 归属地。mcp.tool()装饰器负责登记docstring 负责告诉模型这个工具干嘛用。最后mcp.run()默认走 stdio 通道。接下来是客户端登记。配置就是一小段 JSON关键字段两个command填 Python 解释器的完整路径args放脚本的具体位置写到文件名为止。假设你的客户端支持 MCP 配置片段长这样{ mcpServers: { my-tools: { command: C:/Users/yourname/AppData/Local/Programs/Python/Python312/python.exe, args: [ C:/Users/yourname/projects/my_mcp_server.py ], env: { PYTHONUTF8: 1, TAOTOKEN_API_KEY: 你的统一Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }三个地方要盯紧command必须是解释器完整路径不能只写pythonJSON 里的反斜杠要么转义要么全写成正斜杠我干脆全用正斜杠env里把PYTHONUTF8设成 1Windows 控制台的中文乱码能少一大半。如果你用的是 Claude Code 这类工具配置思路一样把 Base URL、Key、Model ID 三件套填全就行。Model ID 按你实际用的模型填别照抄别人的。保存配置后重启客户端设置页里应该能冒出你登记的那两个工具。4. 验证请求一次工具调用确认跑通配置保存、客户端重启之后别急着高兴先做一次真实验证。打开对话窗口直接问“C 盘还剩多少空间”如果一切正常模型不会跟你道歉而是发起一次工具调用拿到数之后告诉你结果。我这边实测返回的是“C 盘剩余 86G占用率过七成”还顺嘴提醒了一句。那一下体验挺奇妙——屏幕对面的模型自己决定调哪个工具、传什么参数我写的代码在后台被它指挥着跑。想更严谨一点可以再问一句“帮我查下公网 IP 归属地”看它会不会调第二个工具。两个工具都能被正确触发说明 stdio 通道、工具登记、参数传递这条链路全通了。如果你还想单独验证模型通道本身可以走模型对话入口发一条测试请求模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content这一步的意义在于把“工具调用”和“模型通道”分开验证。工具没触发可能是配置问题模型没响应可能是 Key 或 Base URL 问题。分开查定位快很多。验证通过之后你可以试着把工具说明改得模糊一点比如把 docstring 删掉再问一次同样的问题大概率模型就不理你了。这个反向实验能让你直观感受到说明文字的分量。5. 常见报错排查401、invalid JSON、OAuth 这些坑跑通过程当然不是一路绿灯坑都记下来了对照着查能省不少时间。报错一401 Unauthorized。这个基本是 Key 的问题。检查TAOTOKEN_API_KEY有没有填对有没有多余空格Base URL 是不是写成了带 UTM 的地址。程序调用要用https://taotoken.net/api别把浏览器地址粘进去。如果 Key 刚建好确认一下有没有复制完整。报错二invalid JSON 或连接反复断。这个坑我踩得最狠。stdio 通道是拿来做协议通信的我在代码里顺手print了几行调试日志通道被污染客户端直接报 invalid JSON。解决办法很简单所有日志改走stderr别用print。比如import sys; print(debug, filesys.stderr)。报错三local proxy failed 或连接超时。先确认你的网络环境正常再检查客户端配置里的command路径对不对。路径写错、解释器找不到表现就是连不上。另外确认脚本本身能独立跑起来——命令行直接python my_mcp_server.py如果不报错、安静地等着说明服务器没问题。报错四OAuth 相关提示。有些客户端在接入远程服务时会走 OAuth 流程。如果你只是本地 stdio 工具一般用不到如果确实遇到检查客户端的认证配置确认 Key 是通过env传进去的而不是写死在代码里。报错五中文乱码报错一半是问号。Windows 控制台的老问题。给环境变量加PYTHONUTF81世界清净。这个在配置的env字段里加上就行。排查顺序建议这样先确认脚本能独立运行再确认客户端配置路径正确然后看 Key 和 Base URL最后查日志输出有没有污染 stdio 通道。按这个顺序走大部分问题十分钟内能定位。6. 跑通之后把重复劳动甩出去半天折腾下来说几句实在的。门槛比想象中低。会写 Python 函数就能写 MCP 服务器协议细节 SDK 全包圆了真正要上心的是工具说明文字写清楚。这可能是智能体生态里少有的公共标准——模型能力各家卷各家的但工具接入这一层大家愿意坐下来用一个协议对开发者是实打实的方便。我下一步打算也定了把服务器的告警查询和日志检索包成工具接进去。以后半夜服务器闹脾气我躺着问一句让 AI 自己翻日志不用再爬起来开电脑。你手头要是也有想甩出去的重复劳动照这个路子走一遍半天足够折腾出自己的第一个 MCP 服务器。需要长期跑编码或 Agent 任务的可以看看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留个小技巧工具别一次写太多先写一个能跑通的验证链路没问题再往上加。我第一个工具就查磁盘跑通之后加第二个、第三个心里踏实。