1. MCP 协议到底解决什么问题：从大模型“只会聊天”到真正调用外部系统

很多人第一次接触 Model Context Protocol（MCP）时，会把它理解成又一个“插件规范”。但真正动手接过工具调用的人会发现，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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key，控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建好 Key 之后，可以在 API Keys 页面管理你的密钥： https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果你只是想先验证模型对话是否正常，可以用模型对话页面快速测试： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

环境方面，我建议用 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_URL="https://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(f"Searching 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( name="analyze_data_request", description="Creates a request to analyze data with specific parameters", ) def data_analysis_prompt(data_uri: str, analysis_type: str = "summary") -> str: return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}." if __name__ == "__main__": mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

这段代码定义了两个工具、两个资源和一个提示模板。add是最简单的验证工具，search_products演示了带可选参数的复杂工具。资源部分演示了静态资源和带路径参数的资源模板。提示模板演示了如何预置指令。

运行服务端：

python mcp_server.py

你会看到服务端在http://127.0.0.1:8000/mcp上监听。接下来写客户端。创建mcp_client.py：

import 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/api，API 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工具应该返回8，search_products应该返回两个产品字典。如果返回的是错误信息，比如Tool not found，说明工具名称不匹配。注意tools/call里的名称是工具注册名，不是函数名。如果你在@mcp.tool(name="find_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里写死版本号，比如fastmcp==2.3.1，升级前先在测试环境验证。同时关注 MCP 官方文档和 FastMCP 的更新日志，了解新特性和废弃项。

如果你打算长期做 Agent 开发，建议把 MCP 服务器当成一个独立服务来维护，而不是嵌在应用代码里。这样工具可以复用，多个 AI 宿主可以连接同一个 MCP 服务器。你可以用 Docker 打包 MCP 服务器，用环境变量注入配置，用健康检查接口监控状态。这样部署和扩缩容都会方便很多。

最后，如果你在接入过程中遇到模型调用问题，可以回到 TaoToken 的模型对话页面单独测试模型能力，确认模型本身是否支持工具调用。MCP 通道的稳定性取决于模型、客户端、服务端三方的配合，任何一环出问题都会导致调用失败。分步验证，逐层排查，是最有效的方法。