1. 把 docmd 文档站、MCP Server、MCP 客户端拆开看如果你正在给 docmd 生成的 Markdown 文档站挂 MCP先别急着改主题。TaoToken 在这条链路里只提供 Key 和 Base URL先到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_intro 拿 Key再把 MCP 客户端的模型入口写成 https://taotoken.net/api 。docmd 负责把docs/里的 Markdown 资料编译成可浏览、可搜索的文档站docmd 暴露的 MCP Server 负责把文档目录、页面内容、构建动作包装成 MCP 工具真正消耗 Token 的通常是挂进 docmd 的 MCP 客户端例如 Claude Code、Codex或者由 CC Switch 管理的多套配置。很多技术写作者第一次接 MCP 时容易把三件事混在一起文档站在哪里运行、MCP Server 由谁启动、模型请求走哪个供应商。这篇文章按可复现路径拆开写先准备 Markdown 资料和 docmd 启动命令再创建 TaoToken Key然后分别给 Claude Code、Codex、CC Switch 写配置最后验证 MCP 工具调用结果。本文所有配置里的 Key 占位符统一用YOUR_API_KEYBase URL 统一写https://taotoken.net/api不要把 UTM 参数带进工具配置。需要提前说明边界不要让 MCP 或 Agent 直连 Oracle、生产数据库或其他线上关键系统。文档索引、构建、SQL 类命令都应该由你在本地终端执行MCP 客户端只读取你允许的文档目录。这样既能保留 MCP 的自动化效率又能避免把生产环境暴露给模型工具链。2. 准备 Markdown 资料与 docmd 启动命令docmd 的典型使用方式是把散落在仓库里的 Markdown 资料变成文档站并附带 AI 助手和 MCP 能力。假设你的知识库目录如下knowledge-base/ docs/ index.md guide/ install-docmd.md configure-taotoken.md mcp/ client-config.md troubleshooting.md docmd.config.jsondocs/是内容源docmd.config.json是站点配置。你可以在本地先跑通文档站再挂 MCP。启动开发服务可以用cd ~/knowledge-base npx docmdlatest dev --root ./docs --port 4321如果只想生成静态产物cd ~/knowledge-base npx docmdlatest build --root ./docs --out ./dist不同版本的 docmd 子命令可能略有差异执行前建议先看帮助npx docmdlatest --help如果dev、build、mcp这些子命令名称有变化以--help输出为准。本文关注的是接入方法不是某个固定版本的生命周期。文档站能正常打开后再在另一个终端启动 MCP Servercd ~/knowledge-base npx docmdlatest mcp --stdio --root ./docs这里的mcp --stdio表示通过标准输入输出与 MCP 客户端通信。如果你的 docmd 版本把 MCP 入口放在serve --mcp或其他子命令下只需要替换启动参数后面的客户端配置结构不变。TaoToken 不负责启动 docmd也不接管你的文档目录它只提供模型请求所需的 Key 和 Base URL。你可以再回到官网确认 Key 的创建入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_quickstart 。3. 创建 TaoToken Key只记两个值在配置任何 MCP 客户端之前先把模型入口确定下来。到 TaoToken 控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_key_step创建完成后你只需要记两个值配置项值Base URLhttps://taotoken.net/apiAPI KeyYOUR_API_KEY为了本地终端方便可以临时导出环境变量export TAOTOKEN_API_KEYYOUR_API_KEY export TAOTOKEN_BASE_URLhttps://taotoken.net/api不要把这些值写进docs/下的 Markdown 文件也不要提交到 Git 仓库。MCP 客户端配置里出现的YOUR_API_KEY必须替换成真实 Key但真实 Key 只应存在于本地环境变量、用户级配置文件或密钥管理工具中。如果你使用 CC Switch 管理多套客户端配置建议把 TaoToken 单独做成一个 profile名称为taotoken-docmd避免和其他供应商混用。4. 给 docmd 挂 MCP客户端配置先行docmd 的 MCP Server 本身可以独立启动但要让 Claude Code、Codex 这类客户端发现它需要在客户端侧注册 MCP Server。以 Claude Code 常用的项目级.mcp.json为例可以写成{ mcpServers: { docmd: { command: npx, args: [ -y, docmdlatest, mcp, --stdio, --root, ./docs ], env: { DOCS_ROOTP: ./docs, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: YOUR_API_KEY } } } }上面这段配置做了三件事让客户端用npx拉起 docmd 的 MCP 入口把文档根目录限定在./docs如果 docmd 内置的 AI 助手需要调用模型则把模型请求指向 TaoToken 的 Base URL。实际字段名请以npx docmdlatest --help和 docmd 当前文档为准。如果你的版本不读取OPENAI_BASE_URL、OPENAI_API_KEY而是读取DOCMD_AI_*之类的变量就按帮助信息替换变量名但 Base URL 仍然写https://taotoken.net/api。这里再次强调Token 消耗方是挂进 docmd 的 MCP 客户端。Claude Code 和 Codex 在对话时会把上下文、工具定义、工具返回结果发送给模型因此真正需要 TaoToken Key 的是这些客户端而不是 Markdown 文件本身。docmd 的 MCP Server 主要负责暴露工具例如列出页面、读取页面、扫描目录、生成导航草稿等。不要让 MCP Server 直接连接生产数据库需要查询数据时由你在本地终端执行命令再把结果整理成 Markdown 交给 docmd。5. Claude Codesettings.json 与 .mcp.json 分开写Claude Code 使用ANTHROPIC_*系列变量。你可以在用户级或项目级settings.json里配置模型入口{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5 } }这里的ANTHROPIC_BASE_URL填 TaoToken 的 Base URLANTHROPIC_AUTH_TOKEN填你的YOUR_API_KEYANTHROPIC_MODEL按你实际可用的模型名替换。不要把ANTHROPIC_*写到 Codex 的config.toml里两套客户端的键名不同。Claude Code 的项目级 MCP 配置可以放在.mcp.json{ mcpServers: { docmd: { command: npx, args: [ -y, docmdlatest, mcp, --stdio, --root, ./docs ], env: { DOCS_ROOT: ./docs } } } }如果你希望 docmd 的 AI 助手也走 TaoToken可以在env里补充对应变量{ mcpServers: { docmd: { command: npx, args: [ -y, docmdlatest, mcp, --stdio, --root, ./docs ], env: { DOCS_ROOT: ./docs, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: YOUR_API_KEY } } } }配置完成后在项目目录启动 Claude Codecd ~/knowledge-base claude进入对话后可以执行/mcp如果 MCP Server 注册成功你应该能看到docmd这个 server。若没有出现优先检查.mcp.json是否放在项目根目录、JSON 是否合法、npx docmdlatest --help是否能正常执行。Claude Code 的模型请求和 MCP 工具调用是两条链路模型请求走ANTHROPIC_*工具调用走.mcp.json两边都要配置正确。6. Codexconfig.toml 走另一套键名Codex 不使用ANTHROPIC_*。它通常读取~/.codex/config.toml。可以新增一个 TaoToken 供应商model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后在 shell 中导出 Keyexport TAOTOKEN_API_KEYYOUR_API_KEY如果 Codex 版本要求其他wire_api取值以官方配置说明为准但供应商名称、Base URL、Key 环境变量这三者的关系不变。然后配置 docmd 的 MCP Server[mcp_servers.docmd] command npx args [-y, docmdlatest, mcp, --stdio, --root, ./docs] env { DOCS_ROOT ./docs }如果 docmd 内置 AI 助手需要模型变量可以追加[mcp_servers.docmd] command npx args [-y, docmdlatest, mcp, --stdio, --root, ./docs] env { DOCS_ROOT ./docs, OPENAI_BASE_URL https://taotoken.net/api, OPENAI_API_KEY YOUR_API_KEY }再次提醒不要在config.toml里写ANTHROPIC_BASE_URL或ANTHROPIC_AUTH_TOKEN。Codex 和 Claude Code 的配置键名不同混用会导致模型请求失败。配置完成后在项目目录启动 Codex让它列出可用 MCP 工具。如果 Codex 能读取docmd的工具列表但对话时报 401就检查TAOTOKEN_API_KEY是否真的进入环境如果报 404就检查base_url是否误写成https://taotoken.net/api/v1或其他带额外路径的地址。7. CC Switch 三件套Base URL、API Key、模型名如果你用 CC Switch 在 Claude Code、Codex 或其他客户端之间切换建议把配置拆成“三件套”项目Claude Code ProfileCodex ProfileBase URLhttps://taotoken.net/apihttps://taotoken.net/apiAPI KeyYOUR_API_KEYYOUR_API_KEY模型名从可用模型列表选择从可用模型列表选择CC Switch 的作用是帮你切换不同客户端配置不改变 TaoToken 的接入方式。Claude Code 的 profile 应该生成或写入ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODELCodex 的 profile 应该生成或写入base_url、env_key、model。不要把 Claude Code 的ANTHROPIC_*复制到 Codex也不要把 Codex 的env_key思路硬套到 Claude Code。切换 profile 后记得重启对应的 MCP 客户端否则它可能仍然读取旧的环境变量或旧的 MCP Server 列表。如果你还没有创建 TaoToken Key可以在这里完成https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_ccswitch 。创建后先在一个 profile 里小范围验证确认模型对话、MCP 工具调用都正常再复制到其他 profile。8. 启动 docmd、验证 MCP 工具调用结果现在把链路跑通。终端 A 启动文档站cd ~/knowledge-base npx docmdlatest dev --root ./docs --port 4321浏览器打开http://localhost:4321确认 Markdown 页面能正常渲染。终端 B 启动 MCP Servercd ~/knowledge-base npx docmdlatest mcp --stdio --root ./docs然后在 Claude Code 或 Codex 中查看 MCP 工具列表。以 Claude Code 为例/mcp你应该能看到类似docmd的 server以及它暴露的工具。工具名称会随 docmd 版本变化下面只展示一种调用结果的结构。你可以在客户端里输入请调用 docmd 工具扫描 ./docs 下所有 Markdown输出按目录分组的侧边栏草稿并列出每篇的一级标题。一次可能的工具调用结果如下{ server: docmd, tool: docmd.scan, arguments: { root: ./docs, include: [**/*.md], exclude: [node_modules/**, dist/**] }, result: { fileCount: 12, sidebar: [ { title: 快速开始, items: [ 安装 docmd, 配置 TaoToken Key, 启动本地文档站 ] }, { title: MCP 接入, items: [ MCP 客户端配置, Claude Code settings.json, Codex config.toml, CC Switch 三件套 ] }, { title: 排障, items: [ 401 与 403, 404 与 Base URL, MCP Server 启动失败 ] } ], headings: [ { file: docs/index.md, level: 1, text: 知识库首页 }, { file: docs/guide/install-docmd.md, level: 1, text: 安装 docmd } ] } }实际工具名可能是list_pages、read_doc、build_nav等以客户端 discovery 结果为准。重点不是背工具名而是确认三件事MCP Server 已连通、文档根目录被正确限制、模型请求走了 TaoToken 的 Base URL。只要这三件事成立你就可以继续让客户端生成侧边栏、摘要、索引页草稿甚至把结果写回 Markdown 文件。9. 常见报错与排查第一类问题是 401 或 403。表现是模型对话直接失败或者 MCP 工具调用时附带模型请求返回未授权。优先检查YOUR_API_KEY是否替换、环境变量是否在启动客户端的同一个 shell 中导出、CC Switch 是否切到了正确的 profile。Claude Code 看ANTHROPIC_AUTH_TOKENCodex 看env_key指定的变量。第二类问题是 404。最常见原因是 Base URL 写错。工具配置里统一使用https://taotoken.net/api不要写成带 UTM 的官网链接也不要随意追加/v1、/chat/completions等路径。Base URL 是供应商入口不是具体接口地址。如果你在浏览器里复制了带查询参数的地址请把查询参数去掉。第三类问题是 MCP Server 启动失败。先在终端手动执行npx docmdlatest mcp --stdio --root ./docs如果手动执行就失败说明问题在 docmd 命令、Node 版本或./docs路径而不是客户端。如果手动执行能进入等待状态但客户端里看不到 server就检查.mcp.json或config.toml的路径、JSON/TOML 语法、客户端是否需要重启。第四类问题是 Codex 不生效。优先检查是否误把ANTHROPIC_*写进了config.toml。Codex 应使用model_provider、base_url、env_key这一套。Claude Code 才使用ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。第五类问题是工具能列出但执行超时。先减少扫描范围例如只扫描docs/guide再检查是否有超大 Markdown 文件或循环符号链接。不要让 MCP 扫描整个用户目录也不要让它访问包含密钥、数据库转储、生产配置的目录。10. 安全边界Key、文档目录与生产库TaoToken 只提供 Key 和 Base URL不托管你的文档站也不应该接管你的生产系统。推荐把 Key 放在环境变量或用户级配置里项目里的.mcp.json只写YOUR_API_KEY占位符真实值用本地环境覆盖。提交代码前检查git diff -- .mcp.json git status如果发现 Key 被写入文件立刻撤销并重新生成。文档目录也要做白名单例如只允许./docs不要允许./、~/、/。MCP 工具可以读取 Markdown但不应直接连接 Oracle、MySQL、PostgreSQL 等生产库。涉及数据查询、迁移、清理的命令必须由你在本地终端手动执行再把需要公开的结果整理成 Markdown 交给 docmd。对于文档站里的敏感信息也要提前清理。比如内部地址、账号、Token、客户名称、数据库连接串不要放进 Markdown 源文件。MCP 客户端会把工具返回内容发送给模型模型侧会消耗 Token也可能产生上下文泄露风险。把文档目录当作“可公开给模型阅读”的内容区而不是全量知识库。11. 可复用模板把 docmd TaoToken 固定成工作流最后把配置收敛成一个可复用模板。Claude Code 用户记住settings.json管模型.mcp.json管 docmd 工具。Codex 用户记住config.toml里用model_providers.taotoken和mcp_servers.docmd不要碰ANTHROPIC_*。CC Switch 用户记住三件套Base URL、API Key、模型名Claude 和 Codex 分开存 profile。日常流程可以固定为# 1. 进入知识库 cd ~/knowledge-base # 2. 本地启动文档站 npx docmdlatest dev --root ./docs --port 4321 # 3. 另开终端确认 MCP Server 可手动启动 npx docmdlatest mcp --stdio --root ./docs # 4. 启动 Claude Code 或 Codex claude # 或 codex然后在客户端里执行/mcp确认 docmd server 在线。之后让客户端扫描文档、生成侧边栏、补全索引、检查失效链接。所有生成结果先以草稿形式输出由你本地审阅后再写入 Markdown。需要创建新 Key 或查看额度时从官网入口进入https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_end 。12. 下一步按顺序完成模型对话、Coding Plan、Key 与 Claude Code 文档如果你还没有验证 TaoToken 的模型对话可以先打开https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_chat确认模型可用后如果你准备把 docmd、Claude Code、Codex 长期用于文档工程可以查看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_coding接着创建或管理 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_keys_cta最后Claude Code 的完整配置说明见https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentdocmd_mcp_claude_doc按这个顺序走完你就有了一个可复现的 docmd MCP TaoToken 工作流Markdown 资料在本地编译成文档站MCP 客户端通过 docmd 工具读取和整理文档模型请求统一走https://taotoken.net/apiKey 只作为客户端与工具链的凭据。剩下的就是把你的知识库目录整理干净然后让 MCP 客户端开始调用。