1. 从一次搜索请求说起MCP Server 到底解决了什么问题你在百度搜索框里敲下“帮我查一下明天北京到上海的高铁顺便看看沿途天气”几秒钟后一个能直接对话、能调工具、能返回结构化结果的 AI 应用出现在结果页。这个体验背后用户、应用、大模型三方并不是天然打通的——中间缺一层标准化的“工具调用协议”。百度搜索 AI 开放计划里的 MCP Server就是干这件事的。MCPModel Context Protocol模型上下文协议你可以理解成“AI 世界的 USB-C 接口”。以前每个大模型要调用外部工具都得为每个工具单独写一套适配代码有了 MCP工具方按统一协议暴露能力模型方按统一协议发现和调用双方解耦。百度搜索 AI 开放计划把搜索流量、文心大模型和 MCP 工具能力串成一条链路用户搜索需求 → 百度智能分发 → AI 应用 → MCP 工具 → 文心大模型组织回答。这篇文章面向已经写过一点 Python、想把自己或团队的 API 能力接进这条链路的开发者。我会把重点放在“怎么配、怎么跑、怎么排错”上而不是复述发布会内容。整条链路里MCP Server 是你要交付的核心产物文心大模型是最终消费你能力的“大脑”百度搜索是流量入口。三者通过标准协议通信你只需要保证自己的 MCP Server 协议正确、鉴权正确、返回结构正确。需要先明确一个边界MCP Server 不是让你去替代编辑器或 IDE它是给大模型提供“可调用工具”的服务端。你写的是一个能被模型发现、被模型调用的函数集合而不是一个给人看的网页。理解这一点后面配置时就不会跑偏。在动手之前建议先把本地环境理顺Python 3.10、pip 可用、能访问外网 API 端点。如果你后续要接的模型服务走的是兼容 OpenAI 协议的网关那 Base URL、API Key、Model ID 这三件套要提前准备好后面配置里会反复用到。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套在把 MCP Server 接到文心大模型之前很多开发者会先用一个兼容 OpenAI 协议的网关把本地调试跑通这样能快速验证“模型能不能正确调用我的工具”。TaoToken 就是这样一个入口它提供统一的 API 端点和模型路由方便你在正式接入百度生态前做端到端联调。你需要准备三样东西我称之为“三件套”第一Base URL。TaoToken 的 API 端点是https://taotoken.net/api注意这里不带任何查询参数直接作为 OpenAI SDK 的base_url使用。很多 401 报错就是因为把带 UTM 的官网地址误填进了 base_url。第二API Key。到控制台的 API Keys 页面创建格式通常是sk-开头的一串字符。创建后立刻复制保存页面刷新后就不再完整显示。建议按项目命名比如mcp-search-dev方便后续轮换和审计。第三Model ID。这是你实际要调用的模型标识比如gpt-4o、claude-3-5-sonnet这类。Model ID 必须和网关支持的列表一致写错了会返回model not found。你可以在模型对话页面先手动发一条消息确认这个 Model ID 能正常响应再写进代码。把这三件套写进环境变量是最稳妥的做法避免硬编码进仓库export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的实际key export TAOTOKEN_MODEL_IDgpt-4o如果你用的是 Claude Code 这类工具配置方式略有不同需要写进 settings 文件。下面这段 JSON 可以直接复制路径按你本机的实际位置调整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际key, ANTHROPIC_MODEL: claude-3-5-sonnet } }注意ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个键名是 Claude Code 识别的固定字段不要改成别的名字。Model ID 填你确认可用的那个。配置完成后重启工具让它重新读取环境变量。如果你用的是 Codex 系列配置写在auth.json里结构类似{ base_url: https://taotoken.net/api, api_key: sk-你的实际key, model: gpt-4o }三件套的核心逻辑是Base URL 决定请求发到哪API Key 决定你有没有权限Model ID 决定用哪个模型。任何一个错了链路都跑不通。建议在进入 MCP Server 开发前先用一段最小 Python 代码验证三件套是否生效from openai import OpenAI import os client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_ID], messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)如果打印出“通了”说明网关侧没问题可以进入下一步。如果报 401先检查 Key 是否复制完整如果报连接错误检查 Base URL 是否写成了带 UTM 的官网地址。3. 可复制配置把 MCP Server 接进文心大模型调用链这一节是全文的核心。你要交付的是一个能被文心大模型发现并调用的 MCP Server同时保证它和 TaoToken 网关、百度生态的配置语义一致。我按“先本地跑通、再对接网关、最后对齐百度侧”的顺序写。先写一个最小可用的 MCP Server。用官方推荐的fastmcp框架定义一个查询天气的工具from mcp.server.fastmcp import FastMCP mcp FastMCP(weather-mcp) mcp.tool() def get_weather(city: str) - dict: 查询指定城市的当前天气。 Args: city: 城市名称例如 北京、上海 # 这里替换成你真实的天气 API 调用 return {city: city, temp: 22, condition: 晴} if __name__ __main__: mcp.run()mcp.tool()装饰器会把函数注册成模型可调用的工具函数签名和 docstring 就是模型理解工具用途的依据。docstring 写得越清楚模型调用越准确。返回结构建议用 dict字段名保持稳定方便模型解析。接下来是关键的配置片段。如果你要把这个 MCP Server 通过网关暴露给模型调用需要在客户端侧写一份 MCP 配置。以 Cline 的 MCP 配置为例路径通常在~/.cline/mcp_settings.json内容如下{ mcpServers: { weather-mcp: { command: python, args: [/absolute/path/to/weather_mcp.py], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的实际key, TAOTOKEN_MODEL_ID: gpt-4o } } } }这段配置里command和args决定 MCP Server 怎么启动env把三件套注入进去。注意args里的路径必须是绝对路径相对路径在不同工作目录下会找不到文件这是新手最常见的坑之一。如果你用的是 CC Switch 管理多套配置那三件套要写全Base URL 填https://taotoken.net/apiKey 填你的实际 KeyModel ID 填确认可用的模型。CC Switch 的好处是可以在不同项目间快速切换但每个 profile 都要独立填全不能只填一半。百度侧对齐时MCP Server 的元信息要填清楚名称、描述、图标、版本号。描述里要包含你的工具能解决什么问题的关键词因为百度 MCP 广场的智能搜索会基于描述做语义匹配。比如“查询实时天气、支持全国城市、返回温度与天气状况”就比“天气工具”更容易被检索到。配置完成后建议先用 MCP Inspector 或类似工具本地验证工具能否被正确列出和调用。确认无误后再提交到百度开发者后台。整个配置过程的核心原则是三件套在每一层都要写全路径用绝对路径Model ID 和网关支持列表保持一致。4. 端到端验证从用户请求到文心大模型响应的完整链路配置写完不算完必须跑一遍端到端验证确认“用户请求 → 应用 → MCP 工具 → 文心大模型 → 返回结果”这条链路真的通了。我按可观测的顺序拆成四步。第一步验证 MCP Server 本身能启动并列出工具。启动你的 Server 后用 MCP 客户端发一个tools/list请求预期返回你注册的所有工具及其参数 schema。如果这一步失败后面都不用看先解决 Server 启动问题。第二步验证模型能发现工具。通过网关发一条带工具定义的请求观察模型是否返回tool_calls。用 Python 写一个验证脚本from openai import OpenAI import os, json client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) tools [{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: {city: {type: string}}, required: [city], }, }, }] resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_ID], messages[{role: user, content: 北京今天天气怎么样}], toolstools, ) print(json.dumps(resp.choices[0].message.tool_calls, ensure_asciiFalse, indent2))预期结果是模型返回一个tool_calls数组里面包含get_weather和参数{city: 北京}。如果返回的是普通文本而不是 tool_calls说明模型没识别到工具检查 tools 定义和 Model ID 是否支持 function calling。第三步把工具执行结果回传给模型拿到最终自然语言回答。这一步是完整闭环tool_call resp.choices[0].message.tool_calls[0] result get_weather(**json.loads(tool_call.function.arguments)) final client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_ID], messages[ {role: user, content: 北京今天天气怎么样}, resp.choices[0].message, {role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse)}, ], ) print(final.choices[0].message.content)预期输出类似“北京今天晴气温 22 摄氏度”。到这一步链路就通了。第四步在百度开发者后台提交 MCP Server 后用平台提供的测试功能再跑一遍。平台会自动做功能测试和安全检测测试通过后提交审核审核周期通常 1-3 个工作日。审核通过后你的 MCP 会被百度搜索索引所有基于文心大模型的 AI 应用都可以调用。验证过程中要记录每一步的请求和响应尤其是tool_calls的 id 和参数。这些日志在排错时非常有用。如果某一步结果不符合预期先回退到上一步确认不要跳步排查。5. 常见报错排查401、local proxy failed 与 reading choices链路跑不通时报错信息往往指向具体环节。我把最常见的几类报错和排查路径列出来你对照着看。401 Unauthorized这是鉴权失败九成出在 API Key 上。先确认 Key 是否复制完整有没有多余空格再确认 Key 有没有过期或被禁用最后确认请求头里的Authorization格式是Bearer sk-xxx。如果你用的是 Claude Code检查ANTHROPIC_API_KEY是否写对用 Codex 就检查auth.json里的api_key字段。还有一种情况是 Base URL 写成了带 UTM 的官网地址导致请求发到了错误端点也会返回 401 或 404。local proxy failed这个报错通常出现在本地 MCP Server 启动阶段意思是客户端连不上你配置的本地服务。排查顺序先确认command和args能手动在终端跑起来再确认args里的路径是绝对路径然后确认端口没有被占用最后检查防火墙有没有拦截本地回环连接。如果你用的是 Cline 或 CC Switch重启客户端让它重新读取配置。reading choices 相关报错这类报错一般出现在解析模型响应时比如list index out of range或reading choices。原因是响应结构和你预期的不一致常见于模型返回了错误对象而不是正常 completion。排查方法先把原始响应print出来看resp里到底有什么。如果resp里有error字段那就是网关侧返回了错误按错误信息处理如果choices为空可能是模型被限流或请求被拦截。OAuth 相关报错如果你接的是需要 OAuth 的 MCP 服务报错通常和 token 过期或 scope 不足有关。检查 token 有效期确认申请的 scope 覆盖了你要调用的工具。OAuth 流程里回调地址必须和注册时一致差一个字符都会失败。model not foundModel ID 写错了或者网关不支持这个模型。到模型对话页面确认可用列表复制准确的 Model ID。工具调用返回空参数模型识别到了工具但没填参数通常是 docstring 描述不清或参数 schema 不完整。把参数说明写具体required 字段列全。排查时记住一个原则先看原始响应再看错误信息最后改配置。不要凭猜测改代码那样只会引入新问题。每次只改一个变量改完立刻验证这样能快速定位到真正的原因。6. 把链路跑稳之后接入路径与后续动作链路跑通只是第一步真正要上线到百度搜索 AI 开放计划还需要把 MCP Server 的元信息、鉴权、限流、监控都补齐。百度开发者后台提供了调用次数、用户量、收入等数据面板上线后要定期看这些指标根据用户反馈优化工具描述和返回结构。如果你在排错或接入阶段卡住了可以直接到 API Keys 页面确认 Key 状态或者翻接入文档对照配置项。文档里有各语言 SDK 的完整示例比对着改最快。验证模型能力时建议先用模型对话页面手动发几条消息确认 Model ID 和网关都正常再写进 MCP 配置。这样能把“模型问题”和“MCP 问题”分开排查效率高很多。如果你打算长期做编码类或 Agent 类应用Coding Plan 更适合持续调用场景额度和路由策略都比按次调用更划算。接入前先把三件套在本地跑通再提交到百度生态这样审核通过后能直接上线不用来回返工。最后提醒一句MCP Server 的 docstring 和参数 schema 是模型理解你能力的唯一入口花时间把它写清楚比事后调 prompt 有效得多。我试过把工具描述从一句话扩成三句话模型调用准确率明显提升。这个细节值得你多花十分钟。