1. 飞书私有文档读不到，问题到底卡在哪

Claude Code 本身是个跑在终端里的编码助手，它能读你本地的代码文件、能跑命令、能改配置，但它默认够不到你企业飞书里的私有文档。原因不复杂：飞书文档在云端，而且带企业权限校验，不是公开网页，Claude Code 没有一条合法的通道去拉取它。

很多人第一反应是「我直接把文档链接贴给 Claude Code 不就行了」。实测下来，它要么说无法访问，要么尝试用 curl 抓一个需要登录态的页面，拿回来一堆登录跳转的 HTML，根本读不到正文。这不是 Claude Code 笨，而是它缺少一个被授权、能代表你身份去访问飞书开放接口的中间层。

这个中间层就是 MCP。MCP 全称 Model Context Protocol，你可以把它理解成给 AI 助手外接的「工具插座」：Claude Code 通过 MCP 协议去调用一个 MCP Server，由这个 Server 拿着你的授权凭证去飞书开放平台换数据，再把文档内容以结构化形式回传给模型。整条链路里，Claude Code 不直接碰飞书，它只跟 MCP Server 对话。

那为什么标题里要强调「把 MCP endpoint 改到 TaoToken」？因为 MCP Server 的接入地址（endpoint）决定了你的请求最终发到哪个网关。TaoToken 提供统一的 API 入口，把模型调用和 MCP 工具调用收敛到同一个 Base URL 下，你只需要维护一套 Key 和一套地址，Claude Code 的模型请求和飞书文档读取请求都走这里，配置面收窄，排障也简单。对于需要在本地开发环境里让 AI 助手读取企业飞书文档的开发者来说，这套组合能省掉大量「这个 Key 配哪、那个地址填哪」的来回折腾。

适合谁看：你已经在用 Claude Code 写代码，团队文档沉淀在飞书 wiki/docs/drive 里，你希望在不把文档导出成明文文件的前提下，让 Claude Code 直接读原文。下面从零把这条链路配通，每一步都给可复制的片段。

2. 前置准备：TaoToken 的 Key、Base URL 与飞书应用授权

在动 Claude Code 的配置之前，先把两样东西备齐：TaoToken 的访问凭证，以及飞书自建应用的读权限。这两样缺一个，后面 MCP 调用都会在鉴权环节挂掉。

先说 TaoToken 侧。你需要一个 API Key，用来在请求头里做身份识别。获取入口在控制台的 API Keys 页面，登录后新建一个 Key，复制出来先存到本地环境变量里，别直接写死在配置文件里提交到 Git。Base URL 统一用https://taotoken.net/api，注意这个地址不带任何查询参数，MCP 和模型调用都指向它。如果你后面要长期跑编码 Agent，可以顺带了解下 Coding Plan，它面向的就是这种持续调用场景。

export TAOTOKEN_API_KEY="sk-你的实际Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

再说飞书侧。飞书开放平台要求你创建一个「自建应用」，由企业管理员审批通过后，这个应用才有资格代表企业内成员去读文档。流程大致是：在开放平台创建自建应用，拿到 App ID 和 App Secret；然后给这个应用申请文档读权限，具体是 wiki、docs、drive 三个域的读取权限；最后走一次用户授权，让应用拿到代表你访问的 token。

这里有个容易踩的坑：应用创建和权限申请都需要企业审批，不是点一下立刻生效。如果你在个人测试企业里操作，审批通常很快；如果是正式企业，得等管理员点通过。审批没通过之前，任何读取请求都会返回权限不足，别误以为是配置写错了。

飞书侧的凭证同样建议放环境变量：

export LARK_APP_ID="cli_你的AppID" export LARK_APP_SECRET="你的AppSecret"

把这两组凭证备齐，MCP Server 才有东西可用。接下来进入 Claude Code 的配置环节，核心就是把 MCP endpoint 指向 TaoToken，并让 MCP Server 知道用哪套飞书凭证去换文档。

3. 可复制配置：把 MCP endpoint 指向 TaoToken

Claude Code 的 MCP 配置有两种常见落法：一种是项目级的.mcp.json，放在仓库根目录，跟着项目走；另一种是用户级的 settings，放在~/.claude/settings.json，对所有项目生效。团队协作场景建议用项目级，个人多项目复用建议用用户级。下面给项目级 JSON 片段，路径就是仓库根目录的.mcp.json。

{ "mcpServers": { "feishu-docs": { "command": "npx", "args": [ "-y", "@larksuite/cli@latest", "mcp", "serve" ], "env": { "LARK_APP_ID": "${LARK_APP_ID}", "LARK_APP_SECRET": "${LARK_APP_SECRET}", "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}" } } } }

这段配置做了三件事：用 npx 拉起飞书的 CLI 并以 MCP serve 模式运行；把飞书应用凭证通过 env 注入；把 TaoToken 的 Base URL 和 Key 一并注入，让 MCP Server 在需要调用模型侧能力时也走统一网关。注意${VAR}这种写法依赖 Claude Code 启动时能读到对应环境变量，所以前面 export 的那几个变量要在同一个 shell 会话里生效。

如果你更习惯用户级配置，把同样的mcpServers块塞进~/.claude/settings.json即可，结构一致。区别只是作用范围。

配完之后，Claude Code 启动时会去拉起这个 MCP Server。你可以用一条命令确认它被识别到了：

claude mcp list

预期能看到feishu-docs出现在列表里，状态是 connected 或类似字样。如果显示 failed，先别急着改配置，去看下一节的报错对照。

这里再强调一次三件套的完整性：Base URL 是https://taotoken.net/api，Key 是你在控制台新建的那串，Model ID 在 MCP 场景下通常由 Server 内部决定，但如果你同时配了模型调用，Model ID 要填你实际开通的模型名。三者缺一，请求就会在某一层断掉。

4. 验证请求：从发起读取到拿到文档正文

配置就绪后，做一次完整的读取验证，确认私有文档真能被拉回来。验证分两步：先确认 MCP 工具已注册，再实际读一篇有权限的飞书文档。

启动 Claude Code，进入交互界面后输入斜杠命令查看可用工具：

/mcp

正常情况下列表里会出现飞书文档相关的工具，比如读取 wiki 节点、读取 doc 内容、列出 drive 文件等。看到这些工具，说明 MCP Server 已经把手伸到飞书开放接口了。

接着贴一篇你有权限的飞书文档 URL，让 Claude Code 去读。比如：

帮我读取这篇飞书文档的内容并总结要点： https://your-tenant.feishu.cn/wiki/xxxxxxxxxxxx

如果链路通了，Claude Code 会调用 MCP 工具，MCP Server 拿着你的授权去飞书换文档正文，然后把内容回传给模型。你会看到它开始输出文档的摘要，而不是「无法访问」或「需要登录」。

想更直接地验证返回结构，可以绕过模型，直接看 MCP 工具的原始返回。在 Claude Code 里让它调用工具并打印结果：

调用 feishu-docs 的读取工具，把返回的 JSON 原样贴出来，不要总结

预期返回里会有文档标题、正文块、以及节点元信息。看到title和正文段落，就说明私有文档确实被正确拉取了。这一步很关键，因为模型总结可能掩盖「其实只读到了标题没读到正文」的问题，看原始 JSON 才能确认数据完整。

实测下来，第一次读取可能会慢几秒，因为要完成一次 token 交换。后续同一会话内再读会快很多。如果返回的是空正文，八成是权限只授到了 wiki 节点层，没授到文档内容层，回飞书后台把 docs 读权限补上。

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

配 MCP 这条链路，报错基本集中在鉴权和网络两层。下面按真实遇到的错误对照排查。

401 Unauthorized。这是最常见的一个。含义是请求到了服务端但身份没通过。分两种：一种是 TaoToken 侧 Key 无效或没带上，检查TAOTOKEN_API_KEY是否 export 成功、是否有多余空格；另一种是飞书侧 token 过期或权限没批，回飞书开放平台看应用审批状态和权限列表。判断方法：看报错里带的是哪家的域名，带 taotoken 就是前者，带 feishu/larksuite 就是后者。

local proxy failed / connection refused。这类报错说明 Claude Code 根本没连上 MCP Server，或者 Server 进程没起来。先跑claude mcp list看状态，再手动执行配置里的 command 看能不能起来：

npx -y @larksuite/cli@latest mcp serve

如果手动跑报模块找不到，是 npx 缓存或网络问题；如果手动能跑但 Claude Code 里 failed，多半是 env 没传进去，检查.mcp.json里的${VAR}是否在启动 shell 里存在。

reading choices / 返回结构解析失败。这个报错通常出现在模型侧，意思是它期望拿到结构化的 choices 字段但没拿到，往往是因为 MCP 返回的内容格式和模型预期不一致，或者 Base URL 配错导致请求打到了非预期端点。核对TAOTOKEN_BASE_URL是不是https://taotoken.net/api，别多加斜杠或路径。同时确认 MCP Server 版本是最新的，老版本返回结构可能不兼容。

OAuth 相关报错。飞书授权走的是 OAuth 流程，如果报 OAuth 失败，通常是回调地址没配、或者授权链接过期。重新走一次授权，确保在有效期内完成确认。企业审批没过的应用，OAuth 也会失败，先确认审批状态。

排查顺序建议固定：先claude mcp list确认 Server 活着，再手动跑 command 确认能起，再看 env 是否齐全，最后才怀疑飞书权限。按这个顺序走，能少绕很多弯。

6. 把这条链路用起来：接入文档与后续调用

链路通了之后，日常使用就是贴文档 URL 让 Claude Code 读。但有几个实用技巧能让它更稳。

第一，把常用文档的读取封装成固定提示词，减少每次描述成本。比如在项目里放一个CLAUDE.md，写明「读取飞书文档时优先调用 feishu-docs 工具，返回原始 JSON 后再总结」，模型会更守规矩。

第二，注意权限边界。MCP Server 能读的范围，严格等于你给飞书应用授的权限范围。你授了 wiki 和 docs，它就读不了 drive 里没授权的文件。这是好事，等于给 AI 划了一条数据边界，不会越权。

第三，Key 和凭证的轮换。TaoToken 的 Key 和飞书 App Secret 都建议定期换，换完记得同步更新环境变量，别让旧值残留在 shell 配置里。

如果你要把这套接入固化到团队流程里，接入文档里有完整的参数说明和示例，照着核对一遍能避免手写配置时的拼写错误。需要新建或轮换 Key 时，去 API Keys 页面操作。想先验证模型侧是否正常，可以用模型对话快速发一条测试请求，确认 Base URL 和 Key 没问题，再回来调 MCP。

长期跑编码 Agent、频繁调用文档读取的场景，Coding Plan 的额度模型比按次调用更划算，适合把这条链路当成日常工具而不是偶尔试一次的人。

最后留一个我踩过的坑：.mcp.json里的 env 用了${VAR}，但我在 IDE 内置终端里启动 Claude Code，那个终端没继承我 export 的变量，结果一直 401。后来把变量写进 shell 的启动文件，或者直接在配置里填值（注意别提交到公开仓库），问题就没了。配置这东西，报错往往不在你以为的那一层，按顺序排查最省时间。