1. 为什么我决定把 Gemini 文档接进 MCP如果你最近在用 Gemini CLI、Claude Code 或者 Cursor 这类工具写代码大概率遇到过同一个尴尬模型一本正经地给你一段 Gemini API 调用示例参数名看着眼熟跑起来直接 400。原因不复杂——模型的训练数据有截止时间而 Gemini API 的版本、字段、认证方式一直在动。你手动去官网翻文档、复制粘贴一轮下来十分钟没了AI 还未必理解你贴的那段。MCPModel Context Protocol就是来解决这个断层的。它是一套开放协议让 AI 助手通过标准化接口去连外部工具和数据源。放到 Gemini 这个场景里Google 提供了官方的文档 MCP 服务器AI 在需要的时候自己去查最新文档而不是靠记忆瞎编。传统链路是「你查文档 → 复制 → 贴给 AI → AI 生成」MCP 链路是「AI 直接连文档服务器 → 按需取片段 → 生成」。差别在于AI 拿到的永远是当前版本的 API 说明。这篇面向的是需要让 AI 工具直连文档的开发者尤其是已经在用 Gemini CLI 或 Claude Code、想让编码过程少踩版本坑的人。我会给出可直接复制的 MCP 服务器配置骨架settings.json 和 config.toml 两种演示一条配置完成文档直连后的验证动作再把常见的连接失败、SSE 超时、环境变量被屏蔽这些坑逐个排掉。全程不需要你改编辑器源码配置层面就能跑通。2. 接入前先把 TaoToken 这层准备好MCP 服务器负责「查文档」但真正发起模型请求的那一层你还需要一个稳定的 API 入口。我自己的做法是把模型调用统一走 TaoToken这样 Gemini CLI、Claude Code、以及后面要接的 MCP 服务器都能共用同一套 Key 和额度不用在多个平台之间来回切。TaoToken 在这里的角色是模型 API 的接入层官网是 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 的管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后先别急着配 MCP先把模型对话跑通确认这层没问题再去接文档服务器排障的时候能少一半干扰。如果你只是想先验证模型能不能正常回话可以直接用模型对话页试一条 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。长期做编码或者要跑 Agent 的话Coding Plan 更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和参数说明统一看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意MCP 服务器和模型 API 是两层东西。MCP 管「查什么文档」TaoToken 管「谁来生成回答」。两层都配好链路才完整。3. 可复制的 MCP 服务器配置骨架MCP 是通用协议不锁定某一个客户端。下面给两套配置你按自己用的工具选一套即可。核心都是往mcpServers里加一个指向 Gemini 文档服务器的条目。3.1 Gemini CLI 的 settings.jsonGemini CLI 的配置文件在~/.gemini/settings.json。如果目录不存在就先建mkdir -p ~/.gemini然后写入下面这段。注意url指向的是文档 MCP 服务器的 SSE 端点type显式声明为sse避免客户端猜错传输方式{ mcpServers: { gemini-docs: { type: sse, url: https://gemini-api-docs-mcp.dev/sse, timeout: 30000 } } }timeout单位是毫秒默认值偏小网络稍慢就会在握手阶段断掉我一般给到 30000。如果你所在网络到该端点延迟高可以再往上调但别超过 60000否则失败反馈太慢。3.2 Claude Code 的 settings.jsonClaude Code 用的是项目级或用户级的.claude/settings.json。项目级放在仓库根目录的.claude/下用户级放在~/.claude/下。内容结构一致{ mcpServers: { gemini-docs: { type: sse, url: https://gemini-api-docs-mcp.dev/sse, timeout: 30000 } } }3.3 用 config.toml 的客户端怎么写有些客户端比如部分 Rust 生态的 CLI用 TOML 而不是 JSON。等价写法如下字段名保持一致只是语法换了[mcp_servers.gemini-docs] type sse url https://gemini-api-docs-mcp.dev/sse timeout 300003.4 把模型请求也指向 TaoTokenMCP 配好之后模型这一层建议统一走 TaoToken。以环境变量方式注入最省事Gemini CLI 和 Claude Code 都认export GEMINI_API_BASEhttps://taotoken.net/api export GEMINI_API_KEY你的_TaoToken_KeyClaude Code 侧对应的是export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_KeyClaude Code 的接入细节在文档里有单独一节 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。把这两组变量写进~/.zshrc或~/.bashrc重开终端生效。4. 验证请求一条配置到底通没通配置写完不代表通了。MCP 的坑在于它失败时往往不报错只是「静默不生效」AI 照样回答只是回答里没有实时文档。所以必须做一次可观测的验证。4.1 先看服务器有没有被加载Gemini CLI 启动后输入/mcp之类的状态命令不同版本命令名略有差异用help查一下。正常的话能看到gemini-docs处于connected状态。如果显示disconnected或压根没列出来说明配置没被读到先检查文件路径和 JSON 语法。JSON 最常见的低级错误是尾逗号和多层引号转义。用下面这条命令快速校验python3 -m json.tool ~/.gemini/settings.json能正常输出格式化结果就说明语法没问题。4.2 用一个「版本敏感」的问题触发文档查询验证 MCP 是否真的在工作关键是问一个模型靠记忆答不准、必须查文档的问题。比如直接问Gemini API 当前推荐的 generateContent 请求体里 system instruction 字段的准确名称和位置是什么给出一个最小可运行示例。如果 MCP 生效回答里会引用当前版本的字段名并且通常会带上文档来源的片段。如果没生效模型会给你一个「看起来对但字段名是旧版」的答案。这一步是判断成败的核心别跳过。4.3 看 Token 消耗和响应结构MCP 服务器不是把整份文档塞给模型而是按查询返回相关片段。所以生效时你会观察到两个特征一是回答里出现精确到字段级别的说明二是单次请求的 Token 消耗没有暴涨。如果发现 Token 突然翻好几倍多半是某个环节把全量文档加载进来了检查是不是误配了 stdio 模式的本地文档服务。4.4 成功结果长什么样跑通之后典型表现是你问一个 Gemini API 的编码任务AI 直接给出当前版本的参数格式不需要你手动贴文档连续追问几轮它依然能保持字段一致不会前后矛盾。我实测下来接入前同一组任务平均要 3 到 4 轮才能收敛接入后 1 到 2 轮基本就对了手动修正的次数也明显下降。这个收益主要来自「按需取片段」而不是「全量加载」。5. 本篇常见错排查5.1 配置写了但 MCP 没加载先确认文件路径对不对。Gemini CLI 读的是~/.gemini/settings.json不是项目目录下的同名文件Claude Code 项目级配置在.claude/settings.json用户级在~/.claude/settings.json。路径错了不会报错只会静默忽略。其次确认 JSON 顶层就是mcpServers不要多包一层。5.2 SSE 连接超时或握手失败报错通常是SSE connection timeout或failed to connect。先加大timeout到 30000 以上如果还不行用 curl 直接探一下端点可达性curl -N -H Accept: text/event-stream https://gemini-api-docs-mcp.dev/sse能持续收到事件流说明端点正常问题在客户端配置如果卡住或报错就是网络到该端点的链路问题跟 MCP 配置无关。5.3 环境变量被屏蔽导致认证失败Gemini CLI 默认会屏蔽一批敏感环境变量防止泄露给第三方 MCP 服务器匹配的模式包括*TOKEN*、*SECRET*、*PASSWORD*、*KEY*、*AUTH*、*CREDENTIAL*。如果你的 Key 变量名正好命中这些模式它可能不会传给 MCP 子进程。解决办法是换一个不含这些关键词的变量名或者在客户端配置里显式声明允许透传的变量白名单。5.4 模型答的还是旧版 API这种情况八成是 MCP 没真正生效而不是模型「不听话」。回到 4.2 的验证步骤用一个版本敏感的问题测一下。如果/mcp显示 connected 但回答仍是旧版检查是不是同时配了多个文档服务器、请求被路由到了缓存较旧的那个。5.5 同时配了 TaoToken 和 MCP 后请求 401401 基本是 Key 或 Base URL 的问题。确认GEMINI_API_BASE指向的是https://taotoken.net/api结尾不要多加/v1之类的路径Key 从控制台重新复制一次注意别带前后空格。改完环境变量记得重开终端export在当前会话之外不生效。6. 接下来怎么走MCP 这条链路配通之后最直接的收益是编码时不用再手动喂文档。我的建议是先把 Gemini CLI 或 Claude Code 的 MCP 配置跑通用 4.2 那个版本敏感问题验证一次确认文档直连真的在工作再去接更多官方 MCP 服务器。Google 目前提供的官方服务器覆盖了 BigQuery、Maps、GKE、Firebase、Cloud Run 等场景配置方式跟本篇的文档服务器完全一致都是往mcpServers里加一条。模型这一层继续走 TaoToken 就行Key 和额度统一管理MCP 服务器换多少个都不影响。需要长期跑编码任务或 Agent 的Coding Plan 的额度模型更适合持续调用 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入过程中如果卡在认证或参数上文档里有完整的字段说明和示例 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。先把一条配置跑通剩下的服务器照着加就行。
