1. 从零构建 MCP 服务为什么你需要一个自己的 MCP ServerMCPModel Context Protocol是 Anthropic 推出的开放协议用来把外部工具、数据源、业务函数以标准化方式暴露给大模型。你可以把它理解成“AI 世界的 USB-C 接口”客户端Claude Desktop、Cline、Cursor、ChatMCP 等只认协议不认你内部怎么实现只要你的 MCP Server 按规范注册了 Tools、Resources、Prompts模型就能自动发现并调用。但现实里公开的 MCP 服务往往满足不了业务需求。比如你想让模型查公司内部的订单库、读本地某个日志目录、调用自研的风控接口这些都不可能靠现成的开源 Server 完成。这时候能不能自己写一个可复用的 MCP 服务就成了分水岭。这篇文章聚焦“从零搭建一个可复用 MCP 服务”的完整链路先定义工具清单与调用协议再通过 TaoToken 统一 Key/API 通道接入模型能力最后在本地用一次真实工具调用验证服务可用。适合已经了解 MCP 基本概念、想动手写第一个 Server 的开发者也适合手里有一堆内部 API 想统一封装成 AI 工具链的工程师。我试过把公司三个内部接口封装成一个 MCP Server从写代码到 Claude Desktop 里跑通调用前后不到一小时。下面把每一步拆开讲清楚你照着做就能复现。2. TaoToken 前置准备统一 Key 与 API 通道配置在写 MCP Server 之前先把模型能力这一层打通。MCP Server 本身不产生智能它只是“工具提供方”真正决定调用哪个工具、传什么参数的是背后的大模型。所以你需要一个稳定的模型 API 通道。TaoToken 的作用就是提供统一的 Key 和 API 入口让你在 MCP Server 里调用模型时不用关心多家厂商的鉴权差异。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。2.1 获取 API Key登录后进入控制台在 API Keys 页面创建一个新 Key。建议按项目命名比如mcp-server-demo方便后续排查。创建后立即复制保存页面刷新后就不再完整显示。拿到 Key 之后先别急着写 MCP 代码用 curl 验证一下通道是否可用curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-3-5-sonnet-20241022, messages: [{role: user, content: 只回复两个字通了}], max_tokens: 20 }如果返回里能看到choices字段和正常内容说明 Key 和通道都没问题。这一步很关键很多人后面 MCP 调用失败其实是 Key 或 Base URL 写错了先在这里排除掉。2.2 记录三个核心参数后面 MCP Server 和客户端配置都会用到这三个值建议先写在一个临时文件里参数值用途Base URLhttps://taotoken.net/api所有模型请求的根地址API Keysk-xxxxxxxx鉴权凭证Model IDclaude-3-5-sonnet-20241022指定调用的模型注意Base URL 不要带 UTM 参数API 调用只认https://taotoken.net/api这个干净地址。UTM 只用于官网跳转统计。如果你打算长期跑编码类 Agent可以顺带了解 Coding Plan它更适合高频、长上下文的场景如果只是验证模型对话效果用模型对话页面手动测几条 prompt 就够了。但本文的重点是 MCP Server 本身模型通道打通后我们回到服务端开发。3. 可复制配置MCP Server 工具注册与 settings 片段这一节是全文核心。我们用一个 Python 的 MCP Server 做示例注册两个工具一个加法工具用于验证调用链路一个“查询订单状态”工具模拟真实业务。同时给出客户端配置片段路径和原文保持一致。3.1 项目初始化确保本机有 Python 3.10 和 uv 包管理工具。没有 uv 的话用 pip 安装即可pip install uv uv init mcp-server-demo cd mcp-server-demo uv add mcp[cli]执行完目录里会出现main.py这就是我们的开发目标文件。3.2 编写 Server 代码把main.py编辑成下面这样from mcp.server.fastmcp import FastMCP mcp FastMCP(mcp-server-demo, MCP Server Example) mcp.tool() def add(a: int, b: int) - int: Adds two numbers. return a b mcp.tool() def query_order(order_id: str) - str: Query order status by order id. fake_db { A1001: 已发货, A1002: 待付款, A1003: 已完成, } return fake_db.get(order_id, 订单不存在) mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Returns a greeting message. return fHello, {name}! if __name__ __main__: mcp.run(transportstdio)逐段解释关键点。FastMCP是官方 Python SDK 提供的高层封装你不需要手写 JSON-RPC 的传输细节。mcp.tool()装饰器把普通函数注册成模型可调用的工具函数的类型注解和 docstring 会被自动提取成工具的输入 schema 和描述模型就是靠这些信息决定要不要调用、传什么参数。mcp.resource(greeting://{name})注册的是资源和工具的区别在于资源偏向“读数据”工具偏向“执行动作”。资源用 URI 模式标识{name}是占位符客户端请求greeting://张三时就会触发这个函数。mcp.run(transportstdio)表示用标准输入输出通信这是本地 MCP Server 最常用的方式Claude Desktop、Cline 都支持。3.3 客户端 settings 配置片段以 Claude Desktop 为例打开开发者配置文件macOS 一般在~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 在%APPDATA%\Claude\claude_desktop_config.json写入{ mcpServers: { mcp-server-demo: { command: /你的项目地址/mcp-server-demo/.venv/bin/python, args: [ /你的项目地址/mcp-server-demo/main.py ], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL: claude-3-5-sonnet-20241022 } } } }这里把 Base URL、Key、Model ID 三件套都写进了env方便 Server 内部读取。如果你用的是 Cline 或 CC Switch配置结构类似核心都是commandargsenv三部分。Codex 用户如果走auth.json把同样的三个值填进对应字段即可。注意command必须指向虚拟环境里的 python不要用系统 python否则mcp依赖找不到。这是新手最容易踩的坑。4. 验证请求启动、列工具、发起调用三步走配置写完后不要直接扔给客户端先在本地把服务跑起来验证。三步动作启动、列工具、发起调用。4.1 启动开发模式官方 SDK 提供了mcp dev命令可以启动一个带调试界面的开发服务器uv run mcp dev main.py终端会输出类似Starting MCP inspector... Proxy server listening on port 3000打开提示的本地地址你会看到一个 Inspector 界面左侧列出当前 Server 注册的所有能力。4.2 列出工具在 Inspector 里点击 “Tools” 标签应该能看到add和query_order两个工具每个工具下面显示参数 schema。如果这里看不到工具说明装饰器没生效或者代码有语法错误回到终端看报错。也可以用命令行方式列出工具适合脚本化验证echo {jsonrpc:2.0,id:1,method:tools/list,params:{}} | uv run main.py正常返回里会有result.tools数组包含两个工具的定义。4.3 发起一次真实调用在 Inspector 里选中query_order参数填{order_id: A1001}点击调用。返回结果应该是{ content: [ { type: text, text: 已发货 } ] }看到这个返回说明 MCP Server 的工具注册、参数解析、函数执行、结果封装整条链路都通了。接着在 Claude Desktop 里重启客户端输入“帮我查一下订单 A1002 的状态”模型会自动调用query_order工具并返回“待付款”。这一步的成功标志是模型没有胡编答案而是真的触发了你写的函数。如果模型回复“我无法查询订单”说明工具没被识别检查客户端配置里的路径和 env。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth实际搭建过程中报错集中在几个地方。下面按真实错误信息对照排查。401 Unauthorized出现在 curl 验证或 Server 内部调用模型时。原因通常是 Key 写错、Key 过期、或者 Authorization 头格式不对。正确格式是Bearer sk-xxx注意 Bearer 和 Key 之间有一个空格。如果 Key 是从网页复制的检查有没有多余换行。local proxy failed / connection refusedMCP 客户端启动 Server 时连不上。九成是command路径写错或者虚拟环境没建好。用绝对路径别用~或相对路径。Windows 下路径分隔符要用双反斜杠或正斜杠。reading choices 报错 / choices 字段为空模型 API 返回了非预期结构。常见于 Base URL 写成了带 UTM 的官网地址或者 Model ID 拼错。确认 Base URL 是https://taotoken.net/apiModel ID 和你在模型对话页面看到的一致。OAuth 相关报错部分客户端在首次连接时会尝试 OAuth 流程如果 Server 没实现对应端点就会失败。本地 stdio 模式一般不需要 OAuth检查客户端是不是误配成了远程模式。CC Switch 用户注意把传输方式选成 stdio。工具列出来了但调用无响应函数内部抛异常被吞掉。在main.py里加print或logging用uv run mcp dev main.py看终端输出。FastMCP 会把异常转成错误响应但不会打印堆栈需要自己加日志。中文参数乱码stdio 传输默认 UTF-8如果客户端环境编码不是 UTF-8 会出问题。在env里加PYTHONIOENCODING: utf-8通常能解决。排查顺序建议先 curl 验证 Key 和通道再mcp dev验证 Server 本身最后配客户端。一层一层排除比一上来就调客户端高效得多。6. 把 MCP 服务接入你的 AI 工具链下一步怎么做服务跑通只是起点。真正可复用的 MCP Server需要考虑工具清单的版本管理、参数校验、错误码规范、以及多客户端兼容。你可以把query_order换成真实的内部 API 调用把add换成更复杂的业务函数注册逻辑完全一样。如果你想让模型能力这一层更省心TaoToken 的统一 Key 通道可以复用到多个 MCP Server 里不用每个项目单独配鉴权。需要创建新 Key 或查看用量去 API Keys 页面接入细节和参数说明看接入文档想先手动验证模型效果用模型对话页面长期跑编码类 AgentCoding Plan 更合适。MCP 的价值在于标准化。你写一次 ServerClaude、Cline、Cursor、ChatMCP 都能用。把内部能力封装成工具模型就能在你的业务上下文里干活而不是只会聊天。下一步试着把你手头最常用的一个内部接口封装成 MCP 工具跑通调用你就真正掌握了这套链路。