1. MCP 协议到底解决什么问题从大模型“只会聊天”到真正调用外部系统很多人第一次接触 Model Context ProtocolMCP时会把它理解成又一个“插件规范”。但真正动手接过工具调用的人会发现MCP 要解决的是一个更底层的问题大模型本身只会生成文本它没有手也没有脚无法直接读你的本地文件、查你的数据库、调你的内部 API。过去我们靠 Function Calling 硬编码每接一个系统就写一套适配层模型换一个、工具换一个代码就得重写一遍。MCP 就是把这个适配层标准化让大模型与外部系统之间的交互有了一套统一的“插座和插头”。MCP 全称 Model Context Protocol即模型上下文协议是一个开源标准用来连接 AI 应用程序与外部系统。这里的 AI 应用程序可以是 Claude Code、IDE 里的编码助手也可以是你自己写的 Agent 宿主。外部系统则包括本地文件、数据库、搜索引擎、计算器、工作流引擎等。MCP 的核心价值在于它把“模型能调用什么”和“模型怎么调用”解耦了。工具提供方只需要按 MCP 规范暴露能力宿主方只需要按 MCP 规范连接双方不用互相知道对方的实现细节。它适合谁如果你正在做 AI 应用开发尤其是需要让模型访问真实数据、执行真实操作的场景MCP 几乎是绕不开的一层。它适合三类人第一类是 Agent 开发者需要给模型挂载文件系统、数据库、API 等工具第二类是平台工程师需要把内部系统安全地暴露给 AI 助手第三类是工具作者希望自己写的工具能被多个 AI 宿主复用。MCP 的客户端-服务器架构让这三类角色可以各自独立演进。从架构上看MCP 分为数据层和传输层。数据层基于 JSON-RPC 2.0定义了生命周期管理、核心原语工具、资源、提示和通知机制。传输层定义通信通道常见的有 Stdio 传输和 Streamable HTTP 传输。Stdio 适合同一台机器上的本地进程间通信Streamable HTTP 适合远程服务器并支持标准 HTTP 身份验证。MCP 是一个有状态协议连接建立时需要先做 initialize 请求协商协议版本和双方支持的能力确保后续交互不会因为版本不兼容而失败。核心原语是理解 MCP 的关键。工具Tools是服务器提供的可执行函数模型可以调用它来执行操作比如文件读写、API 调用、数据库查询对应tools/list发现和tools/call执行。资源Resources是服务器提供的上下文数据来源比如文件内容、数据库记录、API 响应对应resources/list和resources/get。提示Prompts是可重用的模板用于构建与语言模型的交互比如系统提示、少样本示例。除此之外客户端也会向服务器提供采样Sampling、引发Elicitation、日志Logging等能力让服务器可以请求模型补全、请求用户确认、发送调试日志。一个典型的 MCP 交互流程是这样的客户端先发送 initialize 请求协商协议版本和能力连接建立后客户端发送tools/list获取服务器提供的所有工具元数据包括名称、描述、输入 schema当模型决定使用某个工具时客户端发送tools/call指定工具名称和参数服务器执行后返回 content 数组如果服务器的工具列表发生变化它会发送notifications/tools/list_changed通知客户端收到后重新调用tools/list刷新工具注册表。这套流程让模型与外部系统的交互变得可发现、可调用、可更新。理解了这些你就能明白为什么 MCP 被称为“大模型与外部系统交互的核心协议”。它不是简单的 API 封装而是一套完整的上下文交换机制。接下来我会带你从零搭建一个 MCP 服务端并用客户端调用验证整条通道让你亲手跑通一次完整的 MCP 交互。2. 前置准备TaoToken 接入与 MCP 运行环境搭建在动手写 MCP 服务端之前需要先把模型调用通道准备好。MCP 本身只负责工具调用协议真正决定“模型要不要调用工具、调用哪个工具”的还是大模型。所以你需要一个稳定的模型 API 入口。我实测下来用 TaoToken 作为模型接入层比较顺手它兼容 OpenAI 风格的接口配置简单适合和 MCP 客户端配合使用。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建好 Key 之后可以在 API Keys 页面管理你的密钥 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你只是想先验证模型对话是否正常可以用模型对话页面快速测试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。环境方面我建议用 Python 3.10 以上版本因为 MCP 的 Python SDK 和 FastMCP 对类型注解支持较好。你需要安装 FastMCP它是目前构建 MCP 应用比较标准的框架代码风格简洁适合快速搭建服务端和客户端。安装命令如下pip install fastmcp如果你打算用 Streamable HTTP 传输还需要确保本地端口没有被占用。我一般用 8000 端口做本地验证。另外建议单独建一个虚拟环境避免依赖冲突python -m venv mcp-env source mcp-env/bin/activate # Windows 用 mcp-env\Scripts\activate pip install fastmcp接下来要确认你的模型调用配置。MCP 客户端在调用工具时需要把工具列表和用户请求一起发给模型模型返回工具调用指令后客户端再执行tools/call。所以你需要一个能正常响应工具调用请求的模型接口。TaoToken 的 API 兼容 OpenAI 格式你可以用以下环境变量配置export TAOTOKEN_API_KEY你的_API_Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它内部已经集成了 MCP 客户端你只需要在配置文件里加上 MCP 服务器地址即可。但为了让你理解整条链路我建议先用 FastMCP 手写一个最小客户端把 initialize、tools/list、tools/call 三个步骤都跑一遍。这样后面遇到报错时你能快速定位是服务端问题还是客户端问题。还有一个容易忽略的点MCP 服务器和客户端之间的传输方式要匹配。如果你用 Stdio 传输服务端和客户端必须在同一台机器上通过标准输入输出通信如果你用 Streamable HTTP服务端要监听一个 HTTP 端口客户端通过 URL 连接。我下面会以 Streamable HTTP 为例因为它更接近生产环境的使用方式也方便你后续把 MCP 服务器部署到远程。最后建议你准备一个简单的工具函数作为验证目标比如一个加法工具或一个读取本地文件元信息的工具。不要一上来就接数据库或复杂 API先用最小可运行示例把通道跑通再逐步替换成真实业务逻辑。这样排障成本最低。3. 可复制配置FastMCP 服务端与客户端完整代码这一节是整篇文章的核心我会给你一份可以直接复制运行的 FastMCP 服务端代码以及对应的客户端调用代码。你只需要把 API Key 换成自己的就能在本地跑通一次完整的 MCP 交互。先看服务端。创建一个文件mcp_server.py内容如下from fastmcp import FastMCP mcp FastMCP(Demo MCP Server) mcp.tool def add(a: int, b: int) - int: Add two numbers return a b mcp.tool def search_products(query: str, category: str | None None) - list[dict]: Search the product catalog with optional category filtering. print(fSearching for {query} in category {category}) return [ {id: 1, name: Sample Product A, category: category or general}, {id: 2, name: Sample Product B, category: category or general}, ] mcp.resource(data://config) def get_config() - dict: Provides application configuration as JSON. return { theme: dark, version: 1.2.0, features: [tools, resources], } mcp.resource(weather://{city}/current) def get_weather(city: str) - dict: Provides weather information for a specific city. return { city: city.capitalize(), temperature: 22, condition: Sunny, unit: celsius, } mcp.prompt( nameanalyze_data_request, descriptionCreates a request to analyze data with specific parameters, ) def data_analysis_prompt(data_uri: str, analysis_type: str summary) - str: return fPlease perform a {analysis_type} analysis on the data found at {data_uri}. if __name__ __main__: mcp.run(transportstreamable-http, host127.0.0.1, port8000)这段代码定义了两个工具、两个资源和一个提示模板。add是最简单的验证工具search_products演示了带可选参数的复杂工具。资源部分演示了静态资源和带路径参数的资源模板。提示模板演示了如何预置指令。运行服务端python mcp_server.py你会看到服务端在http://127.0.0.1:8000/mcp上监听。接下来写客户端。创建mcp_client.pyimport asyncio from fastmcp import Client client Client(http://127.0.0.1:8000/mcp) async def main(): async with client: tools await client.list_tools() print(Available tools:) for tool in tools: print(f - {tool.name}: {tool.description}) result await client.call_tool(add, {a: 3, b: 5}) print(add result:, result) result await client.call_tool( search_products, {query: laptop, category: electronics}, ) print(search_products result:, result) config await client.read_resource(data://config) print(config resource:, config) weather await client.read_resource(weather://beijing/current) print(weather resource:, weather) asyncio.run(main())运行客户端python mcp_client.py如果一切正常你会看到工具列表、加法结果、搜索结果、配置资源和天气资源依次打印出来。这就是一次完整的 MCP 交互客户端连接服务器发现工具调用工具读取资源。如果你想把 MCP 服务器接入 Claude Code需要在 Claude Code 的配置文件中添加 MCP 服务器地址。Claude Code 的 MCP 配置通常放在~/.claude/claude_desktop_config.json或项目级配置中格式如下{ mcpServers: { demo-server: { url: http://127.0.0.1:8000/mcp } } }如果你用的是 Cline 或 CC Switch 这类工具配置方式类似核心三件套是 Base URL、API Key 和 Model ID。Base URL 填https://taotoken.net/apiAPI Key 填你在控制台创建的密钥Model ID 填你实际使用的模型名称。这三项配好之后MCP 客户端才能把工具调用请求发给模型模型返回工具调用指令后客户端再执行tools/call。对于 Codex 用户如果你用的是auth.json配置方式需要确保auth.json中的 API 地址和 Key 与 TaoToken 一致。Codex 的 MCP 支持通常通过配置文件声明 MCP 服务器具体字段名可能因版本而异但核心逻辑不变声明服务器地址客户端启动时连接连接成功后拉取工具列表。这里要提醒一点MCP 服务器不要直接连生产数据库。我见过有人把生产库的读写权限直接暴露给 MCP 工具结果模型误调用导致数据被改。正确做法是给 MCP 服务器单独建一个只读账号或者用视图限制可访问的数据范围。工具描述里也要写清楚“只读”“需要确认”等提示让模型和用户都有预期。4. 验证请求与成功结果从 initialize 到 tools/call 的完整链路配置写完之后最关键的一步是验证整条链路是否真的通了。很多人卡在“代码写完了但不知道哪一步出错”所以我会把验证过程拆成几个可观察的步骤每一步都有明确的成功标志。第一步验证服务端是否正常启动。运行python mcp_server.py后你应该看到类似INFO: Uvicorn running on http://127.0.0.1:8000的输出。如果没有这行说明端口被占用或 FastMCP 安装有问题。可以用curl快速探测curl -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}}如果返回包含result和capabilities的 JSON说明服务端正常。如果返回连接拒绝检查服务端是否在运行、端口是否一致。第二步验证客户端能否连接并发现工具。运行python mcp_client.py观察输出。成功时你会看到Available tools: - add: Add two numbers - search_products: Search the product catalog with optional category filtering. add result: ... search_products result: ... config resource: ... weather resource: ...如果list_tools返回空列表说明服务端没有正确注册工具。检查mcp.tool装饰器是否加在函数上函数是否有类型注解。FastMCP 依赖类型注解生成 inputSchema没有注解的工具可能不会被正确暴露。第三步验证工具调用结果。add工具应该返回8search_products应该返回两个产品字典。如果返回的是错误信息比如Tool not found说明工具名称不匹配。注意tools/call里的名称是工具注册名不是函数名。如果你在mcp.tool(namefind_products)里指定了自定义名称调用时要用find_products。第四步验证资源读取。read_resource(data://config)应该返回配置字典read_resource(weather://beijing/current)应该返回北京天气。如果返回Resource not found检查资源 URI 是否和注册时一致。资源模板的路径参数要用{city}这种格式调用时替换成实际值。第五步验证模型侧的工具调用。这一步需要你的模型 API 正常工作。你可以用 TaoToken 的模型对话页面先测试模型是否能理解工具描述。把工具列表和用户请求一起发给模型看模型是否返回工具调用指令。如果模型不调用工具可能是工具描述不够清晰或者模型不支持工具调用。可以换一个支持 Function Calling 的模型再试。我踩过的一个坑是客户端和服务端的协议版本不一致。MCP 在 initialize 阶段会协商协议版本如果客户端声明的版本服务端不支持连接会失败。FastMCP 默认使用较新的协议版本但如果你用的是旧版客户端可能需要手动指定。解决办法是升级 FastMCP 到最新版或者在看日志时留意protocolVersion字段。另一个常见问题是 Streamable HTTP 的路径。FastMCP 默认的 MCP 端点是/mcp如果你写成了/sse或/messages会返回 404。确认客户端 URL 和服务端实际监听路径一致。如果你用 Stdio 传输客户端配置里要写命令和参数而不是 URL。成功跑通之后你可以把search_products替换成真实的业务工具比如查询订单、读取文档、调用内部 API。MCP 的好处是你只需要改服务端的工具实现客户端和模型侧不用动。工具描述写清楚模型就能自动发现并调用。这就是标准化协议带来的复用价值。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节我整理了几个真实遇到过的报错以及对应的排查思路。这些报错在 MCP 接入过程中出现频率很高提前了解能省不少时间。401 Unauthorized。这个报错通常出现在模型 API 调用阶段而不是 MCP 协议本身。如果你在客户端配置里填了 TaoToken 的 API Key但请求返回 401先检查 Key 是否复制完整有没有多余空格。然后确认 Base URL 是否正确TaoToken 的 API 地址是https://taotoken.net/api不要漏掉/api路径。如果你用的是环境变量确认环境变量在当前终端会话中生效。可以用echo $TAOTOKEN_API_KEY检查。另外有些客户端会把 Key 放在Authorization: Bearer头里有些放在自定义头里确认你的客户端配置和 TaoToken 的要求一致。local proxy failed。这个报错通常和网络配置有关。如果你在本地运行 MCP 服务端客户端连接127.0.0.1:8000时出现这个错误先检查服务端是否真的在监听。可以用netstat -an | grep 8000或lsof -i :8000查看端口状态。如果服务端在 Docker 里运行端口映射可能没配好需要把容器端口映射到宿主机。另外某些企业网络环境会限制本地回环地址的访问如果你在公司网络里可以尝试换一个端口或者用 Stdio 传输替代 HTTP 传输。reading choices。这个报错通常出现在模型返回结果解析阶段。MCP 客户端把工具列表和用户请求发给模型后期望模型返回结构化的工具调用指令。如果模型返回的是普通文本客户端解析choices字段时就会报错。解决办法是确认你使用的模型支持 Function Calling 或 Tool Use。不是所有模型都支持工具调用有些模型只能生成文本。你可以在 TaoToken 的模型对话页面测试模型是否支持工具调用或者换一个明确支持工具调用的模型。另外检查客户端发送的请求体里是否正确包含了tools字段格式是否符合 OpenAI 规范。OAuth 相关错误。如果你用 Streamable HTTP 传输并且服务端配置了 OAuth 认证客户端需要先获取 access token。常见错误包括invalid_client、invalid_grant、redirect_uri_mismatch。排查时先确认 OAuth 客户端 ID 和密钥是否正确回调地址是否在服务端注册。如果你只是本地验证可以暂时关闭 OAuth用无认证模式跑通链路再逐步加上认证。FastMCP 支持在mcp.run()里配置认证中间件但本地开发时建议先不启用减少变量。除了这些具体报错还有一些通用排查技巧。第一看日志。FastMCP 服务端和客户端都会打印详细日志把日志级别调到 DEBUG 能看到完整的 JSON-RPC 请求和响应。第二用最小示例。如果你自定义的工具报错先换回add工具确认基础链路没问题再逐步替换。第三检查版本。FastMCP 和 MCP 协议都在快速迭代旧版本可能存在兼容性问题。用pip install -U fastmcp升级到最新版然后重新跑一遍。还有一个容易忽略的点MCP 服务器的工具描述会影响模型是否调用工具。如果描述太模糊模型可能不知道什么时候该用这个工具。建议在描述里写清楚工具的作用、输入参数的含义、返回值的格式。比如search_products的描述写成“Search the product catalog with optional category filtering”模型就能理解这是搜索工具支持按分类过滤。描述写得好模型调用准确率会明显提升。6. 从验证到落地MCP 通道的长期使用建议跑通最小示例之后你可能会想把它用到实际项目里。这里我给几个落地建议都是实际项目中总结出来的。第一工具粒度要适中。不要把一个大功能塞进一个工具也不要把每个小操作都拆成独立工具。工具太多模型选择困难工具太少模型无法完成复杂任务。我一般按“一个工具完成一个明确动作”来划分比如“查询订单”“创建退款”“发送通知”各是一个工具。工具描述里写清楚前置条件和副作用让模型知道调用后会发生什么。第二资源设计要区分静态和动态。静态资源适合配置、文档、schema 这类不常变的数据动态资源适合实时数据比如天气、库存、订单状态。资源 URI 要有清晰的命名空间比如data://config、weather://{city}/current避免和工具名称混淆。资源模板的路径参数要有限定不要暴露整个文件系统。第三提示模板要可复用。提示模板的价值在于把复杂的指令固化下来让模型每次都能按同样的方式处理任务。比如“分析数据请求”模板把数据 URI 和分析类型作为参数模型收到后就知道要做什么。提示模板不要写死具体数据而是用参数占位这样同一个模板可以复用于不同场景。第四传输方式按场景选。本地开发用 Stdio 最简单不需要网络配置远程部署用 Streamable HTTP方便多客户端连接。如果服务端要暴露给多个用户建议加上认证和限流。MCP 协议本身支持 OAuth但实现起来有一定复杂度可以先用 API Key 做简单认证后续再升级。第五监控和日志不能少。MCP 服务器在生产环境运行时要记录每次工具调用的入参、出参、耗时、错误信息。这些日志不仅能帮你排查问题还能分析模型的使用模式优化工具设计。FastMCP 支持自定义日志中间件你可以在工具函数里加日志也可以用客户端的 Logging 能力收集服务端日志。第六版本管理要跟上。MCP 协议还在演进FastMCP 也在持续更新。建议锁定依赖版本避免自动升级导致不兼容。在requirements.txt里写死版本号比如fastmcp2.3.1升级前先在测试环境验证。同时关注 MCP 官方文档和 FastMCP 的更新日志了解新特性和废弃项。如果你打算长期做 Agent 开发建议把 MCP 服务器当成一个独立服务来维护而不是嵌在应用代码里。这样工具可以复用多个 AI 宿主可以连接同一个 MCP 服务器。你可以用 Docker 打包 MCP 服务器用环境变量注入配置用健康检查接口监控状态。这样部署和扩缩容都会方便很多。最后如果你在接入过程中遇到模型调用问题可以回到 TaoToken 的模型对话页面单独测试模型能力确认模型本身是否支持工具调用。MCP 通道的稳定性取决于模型、客户端、服务端三方的配合任何一环出问题都会导致调用失败。分步验证逐层排查是最有效的方法。