企业官网建设流程全解析

1. 从一次工具调用失败说起：MCP 协议链路到底卡在哪

如果你正在做 AI Agent 或者智能助手，大概率听过 MCP（Model Context Protocol）这个词。它本质上是一套让 AI 应用和外部数据源、工具之间安全交互的标准化协议，2024 年由 Anthropic 提出，现在已经被 Claude Desktop、Continue、Cline 等一批工具采纳。简单说，MCP 就是给大模型装了一双能伸向外部世界的手：Resources 让它读数据，Tools 让它执行动作，Prompts 让它按模板完成任务。适合谁？适合那些不满足于“模型只会聊天”，想让模型真正操作文件、查数据库、调 API 的开发者。

但很多人第一次接 MCP 的时候，会遇到一个很迷惑的现象：配置文件写好了，服务也启动了，可模型就是不用工具，或者调用时报一堆看不懂的错。我试过在本地搭一个文件系统 MCP 服务端，结果客户端发出去的tools/call请求石沉大海，日志里只有一行local proxy failed。后来把整条链路拆开看，才发现问题出在初始化握手阶段——客户端根本没完成能力协商，服务端不知道客户端支持什么，客户端也不知道服务端注册了哪些工具。

这篇文章就聚焦 MCP 从初始化握手、能力协商到工具调用的完整链路，面向想理解 MCP 底层机制的开发者。我会交付可复制的 MCP 服务端配置片段和客户端调用示例，并给出逐步验证协议交互的调试动作。读完你不仅能跑通一个文件系统 MCP 服务端，还能看懂每一条 JSON-RPC 消息在干什么，遇到报错知道去哪一层排查。

整条链路的核心其实就三件事：握手、发现、调用。握手是initialize请求和响应，双方交换协议版本和能力；发现是客户端发tools/list、resources/list，拿到服务端注册的清单；调用是模型决定用某个工具后，客户端发tools/call，服务端执行并返回结果。听起来简单，但每一层都有坑，下面逐个拆。

2. TaoToken 前置准备：把模型侧和 MCP 侧接起来

在深入协议细节之前，得先把运行环境准备好。MCP 服务端本身不依赖任何特定模型，但你要验证整条链路，需要一个能发起工具调用的客户端。这里我用 TaoToken 作为模型接入层，它提供兼容 OpenAI 风格的 API，同时支持 Claude Code、Cline 这类支持 MCP 的编码工具。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

为什么先讲这个？因为 MCP 的调试链路里，模型侧和协议侧是分开的。协议侧你可以用纯 Python 脚本手动发 JSON-RPC 消息验证，但真实场景下是模型生成tool_use请求，客户端把它转成 JSON-RPC。如果你只调协议不接模型，很多问题（比如模型不触发工具、参数 schema 不匹配）根本暴露不出来。所以我的做法是：先用脚本验证协议层，再接上模型跑端到端。

TaoToken 这边你需要准备三样东西：Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api，API Key 在控制台的 API Keys 页面生成，Model ID 根据你用的模型填，比如claude-sonnet-4-20250514这类。如果你用的是 Claude Code，它本身支持 MCP 配置，可以直接在 settings 里挂载 MCP 服务端；如果你用的是 Cline，它内置了 MCP 市场，也可以手动填配置。

这里有个关键点：MCP 服务端和模型接入层是解耦的。MCP 服务端只负责暴露 Resources、Tools、Prompts，它不关心背后是哪个模型。模型接入层负责把用户的自然语言转成工具调用意图，再通过 MCP 客户端发给服务端。所以你在调试时，可以先用simple_client.py手动发请求，确认服务端没问题，再接模型。这样出问题时能快速定位是协议层还是模型层。

另外提醒一句，MCP 服务端建议跑在独立进程里，通过 stdio 和客户端通信。不要把它和你的主应用塞在一个进程，否则一个工具执行卡住，整个应用都僵了。下面进入具体配置。

3. 可复制配置：MCP 服务端与客户端 settings 片段

这一节直接给可复制的配置。先看 MCP 服务端的核心结构。我用 Python 写一个文件系统服务端，暴露三个工具：read_file、list_directory、search_files。服务端基于 JSON-RPC over stdio，每条消息一行 JSON。

先看服务端的启动配置。你需要一个server.py，核心是注册工具和资源，然后进入 stdio 循环。下面是关键片段，路径按你本地实际调整：

# servers/filesystem/server.py import os import asyncio import sys from pathlib import Path class FileSystemServer: def __init__(self, root_dir: str): self.root_dir = Path(root_dir).resolve() self.tools = {} self._register_tools() def _register_tools(self): self.tools["read_file"] = { "name": "read_file", "description": "Read the content of a file in the allowed directory", "inputSchema": { "type": "object", "properties": { "path": {"type": "string", "description": "Relative path under root"} }, "required": ["path"] } } self.tools["list_directory"] = { "name": "list_directory", "description": "List files and directories in a given path", "inputSchema": { "type": "object", "properties": { "path": {"type": "string"} }, "required": ["path"] } } def _safe_path(self, rel_path: str) -> Path: full = (self.root_dir / rel_path).resolve() if not str(full).startswith(str(self.root_dir)): raise ValueError("Access denied: path outside root") return full async def handle_tools_call(self, params: dict) -> dict: name = params.get("name") args = params.get("arguments", {}) if name == "read_file": p = self._safe_path(args["path"]) if not p.is_file(): return {"content": [{"type": "text", "text": f"Error: {args['path']} not a file"}]} with open(p, "r", encoding="utf-8") as f: return {"content": [{"type": "text", "text": f.read()}]} if name == "list_directory": p = self._safe_path(args["path"]) if not p.is_dir(): return {"content": [{"type": "text", "text": f"Error: {args['path']} not a dir"}]} items = [f"{'[D]' if i.is_dir() else '[F]'} {i.name}" for i in p.iterdir()] return {"content": [{"type": "text", "text": "\n".join(items) or "(empty)"}]} return {"content": [{"type": "text", "text": f"Unknown tool: {name}"}]} async def run_stdio(self): while True: line = sys.stdin.readline() if not line: break try: msg = json.loads(line) except json.JSONDecodeError: continue method = msg.get("method") msg_id = msg.get("id") if method == "initialize": result = { "protocolVersion": "0.1.0", "capabilities": {"tools": {}, "resources": {}}, "serverInfo": {"name": "filesystem-mcp", "version": "1.0.0"} } elif method == "tools/list": result = {"tools": list(self.tools.values())} elif method == "tools/call": result = await self.handle_tools_call(msg.get("params", {})) else: result = None if msg_id is not None: resp = {"jsonrpc": "2.0", "id": msg_id, "result": result} sys.stdout.write(json.dumps(resp) + "\n") sys.stdout.flush() if __name__ == "__main__": root = sys.argv[1] if len(sys.argv) > 1 else "/tmp" server = FileSystemServer(root) asyncio.run(server.run_stdio())

注意_safe_path里的路径逃逸防护，这是 MCP 服务端必须做的。没有它，模型可以通过../../etc/passwd读到不该读的文件。

再看客户端侧的 settings 配置。如果你用 Claude Code，在项目根目录的.claude/settings.json里加 MCP 服务端：

{ "mcpServers": { "filesystem": { "command": "python", "args": ["/path/to/mcp_demo/servers/filesystem/server.py", "/Users/me/allowed_folder"], "env": { "PYTHONPATH": "/path/to/mcp_demo" } } } }

如果你用 Cline，配置在 Cline 的 MCP 设置里，格式类似，关键是command、args、env三件套。Base URL 填https://taotoken.net/api，API Key 填你生成的，Model ID 填你用的模型。这三件套在 Cline 的 API 配置里单独填，和 MCP 配置是分开的。

如果你用 Codex，它的auth.json里需要填 API Key 和 Base URL，MCP 配置在单独的mcp.json里。不管哪个客户端，核心都是：Base URL + Key + Model ID 三件套负责模型接入，MCP 配置负责工具接入，两者独立。

4. 验证请求：手动发 JSON-RPC 看完整链路

配置写好了，别急着接模型。先用脚本手动发 JSON-RPC，把协议链路走一遍。这样你能看到每一条消息的原始格式，出问题也知道是哪一步。

启动服务端：

cd mcp_demo/servers/filesystem python server.py /tmp

服务端会阻塞在 stdin 等待输入。另开一个终端，用 echo 发初始化请求：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}}}' | python server.py /tmp

你会看到类似这样的响应：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"0.1.0","capabilities":{"tools":{},"resources":{}},"serverInfo":{"name":"filesystem-mcp","version":"1.0.0"}}}

这一步是握手。客户端告诉服务端自己支持的协议版本和能力，服务端回自己的版本和能力。注意id必须原样返回，这是 JSON-RPC 的请求-响应匹配机制。

接着发tools/list：

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python server.py /tmp

响应里会列出read_file和list_directory的完整 schema。这一步是能力发现，客户端拿到工具清单后，会把它转成模型能理解的函数描述。

最后发tools/call：

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"test.txt"}}}' | python server.py /tmp

如果/tmp/test.txt存在，你会看到文件内容包在content数组里返回。注意返回格式必须是{"content":[{"type":"text","text":"..."}]}，这是 MCP 规范定义的，客户端和模型都按这个格式解析。

手动验证通过后，用simple_client.py跑一遍完整交互。这个脚本会启动服务端子进程，依次发 initialize、tools/list、tools/call，打印每一步的响应。跑通后你会看到类似这样的日志：

Initialize response: {'jsonrpc': '2.0', 'id': 1, 'result': {...}} Tools: {'tools': [{'name': 'read_file', ...}, {'name': 'list_directory', ...}]} Read file result: {'content': [{'type': 'text', 'text': 'Hello World'}]}

到这一步，协议链路就通了。接下来接模型，让模型自己决定调哪个工具。在 Claude Code 或 Cline 里输入“请读取我桌面上的 test.txt 内容”，模型会生成tool_use请求，客户端转成tools/call发给服务端，服务端返回内容，模型再基于内容生成最终回复。整条链路是：用户输入 → 模型生成工具调用意图 → 客户端转 JSON-RPC → 服务端执行 → 结果回传模型 → 模型生成自然语言回复。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

链路跑通不代表一帆风顺，下面这几个报错是我踩过的坑，对照着排查能省不少时间。

401 Unauthorized：这个通常出在模型接入层，不是 MCP 协议层。检查你的 API Key 是否填对，Base URL 是否是https://taotoken.net/api。如果你用的是 Claude Code，检查settings.json里的env是否把 Key 传进去了。注意 Key 不要有多余空格，也不要放在会被 git 提交的文件里。

local proxy failed：这个报错在 MCP 客户端启动服务端时出现，意思是客户端无法拉起服务端子进程。常见原因有三个：command路径不对，比如你写了python但系统里只有python3；args里的脚本路径不对；env里的PYTHONPATH没设，导致服务端 import 自己的模块失败。排查方法是在终端手动执行command+args的组合，看能不能跑起来。如果手动能跑，客户端跑不了，那就是客户端的工作目录和你的终端不一样，把路径改成绝对路径。

reading choices 相关报错：这个通常出现在模型返回格式不符合预期时。比如模型返回的tool_use块里input不是合法 JSON，或者客户端解析响应时字段对不上。检查你的工具inputSchema是否严格符合 JSON Schema，特别是required字段和type字段。模型有时候会传字符串给期望数字的参数，schema 写清楚能减少这类问题。

OAuth 相关报错：如果你接的 MCP 服务端是远程的，走 SSE 或 WebSocket，可能会遇到 OAuth 认证问题。MCP 规范里远程服务端可以用 OAuth 做授权，但本地 stdio 服务端不需要。如果你在本地调试却看到 OAuth 报错，检查是不是客户端把本地服务端误判成远程了，或者配置里混入了远程服务端的字段。

还有一个隐蔽的坑：服务端返回的content数组里，type必须是text，text必须是字符串。如果你返回了嵌套对象，客户端解析会失败，模型也读不到内容。我见过有人把 JSON 对象直接塞进text，结果模型收到的是[object Object]。

排查顺序建议：先看模型接入层（401 类），再看进程启动层（local proxy failed 类），再看协议格式层（reading choices 类），最后看认证层（OAuth 类）。每一层都有独立的日志，别混在一起看。

6. 把 MCP 链路用起来：从调试到长期编码

协议链路拆完，配置和排查也给了，最后说怎么把它用起来。如果你只是临时验证，手动发 JSON-RPC 就够了。但如果你要长期做 Agent 开发，建议把 MCP 服务端做成独立仓库，每个工具一个模块，用官方的mcpPython SDK 或 TypeScript SDK 来写，省得自己处理 JSON-RPC 的边界情况。

模型侧我建议用 TaoToken 的 Coding Plan，它适合长期编码和 Agent 场景，Base URL 还是https://taotoken.net/api，Key 和 Model ID 在控制台配好。这样你的 MCP 服务端和模型接入层就彻底解耦了，换模型不用改 MCP 配置，加工具不用动模型配置。

调试的时候有个技巧：在服务端的tools/call处理函数里加一行日志，把收到的params原样打到 stderr。stderr 不会干扰 stdio 的 JSON-RPC 通信，但你能在客户端日志里看到模型实际传了什么参数。很多“模型不调工具”的问题，其实是模型传的参数和 schema 对不上，看一眼原始参数就明白了。

另外，MCP 的initialize响应里有个capabilities字段，服务端可以声明自己支持resources.subscribe、tools.listChanged等能力。如果你要做动态工具注册，记得把这个字段填对，否则客户端不会监听变更通知。这个细节在官方文档里写得比较散，但实际做动态能力发现时很关键。

整条链路的核心就是三句话：握手交换能力，发现拿到清单，调用执行并回传。把这三步的 JSON-RPC 消息格式记牢，遇到任何 MCP 报错都能定位到具体哪一层。剩下的就是按你的业务需求，往服务端里加工具、加资源、加提示模板。