给 docmd 的 Markdown 文档站加 MCP，TaoToken 只提供 Key

1. 把 docmd 文档站、MCP Server、MCP 客户端拆开看

如果你正在给 docmd 生成的 Markdown 文档站挂 MCP，先别急着改主题。TaoToken 在这条链路里只提供 Key 和 Base URL：先到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=docmd_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_KEY，Base 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.json

docs/是内容源，docmd.config.json是站点配置。你可以在本地先跑通文档站，再挂 MCP。启动开发服务可以用：

cd ~/knowledge-base npx docmd@latest dev --root ./docs --port 4321

如果只想生成静态产物：

cd ~/knowledge-base npx docmd@latest build --root ./docs --out ./dist

不同版本的 docmd 子命令可能略有差异，执行前建议先看帮助：

npx docmd@latest --help

如果dev、build、mcp这些子命令名称有变化，以--help输出为准。本文关注的是接入方法，不是某个固定版本的生命周期。文档站能正常打开后，再在另一个终端启动 MCP Server：

cd ~/knowledge-base npx docmd@latest mcp --stdio --root ./docs

这里的mcp --stdio表示通过标准输入输出与 MCP 客户端通信。如果你的 docmd 版本把 MCP 入口放在serve --mcp或其他子命令下，只需要替换启动参数，后面的客户端配置结构不变。TaoToken 不负责启动 docmd，也不接管你的文档目录，它只提供模型请求所需的 Key 和 Base URL。你可以再回到官网确认 Key 的创建入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_quickstart 。

3. 创建 TaoToken Key：只记两个值

在配置任何 MCP 客户端之前，先把模型入口确定下来。到 TaoToken 控制台创建 API Key：

https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_key_step

创建完成后，你只需要记两个值：

为了本地终端方便，可以临时导出环境变量：

export TAOTOKEN_API_KEY="YOUR_API_KEY" export TAOTOKEN_BASE_URL="https://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", "docmd@latest", "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 docmd@latest --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 Code：settings.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 URL，ANTHROPIC_AUTH_TOKEN填你的YOUR_API_KEY，ANTHROPIC_MODEL按你实际可用的模型名替换。不要把ANTHROPIC_*写到 Codex 的config.toml里，两套客户端的键名不同。

Claude Code 的项目级 MCP 配置可以放在.mcp.json：

{ "mcpServers": { "docmd": { "command": "npx", "args": [ "-y", "docmd@latest", "mcp", "--stdio", "--root", "./docs" ], "env": { "DOCS_ROOT": "./docs" } } } }

如果你希望 docmd 的 AI 助手也走 TaoToken，可以在env里补充对应变量：

{ "mcpServers": { "docmd": { "command": "npx", "args": [ "-y", "docmd@latest", "mcp", "--stdio", "--root", "./docs" ], "env": { "DOCS_ROOT": "./docs", "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "YOUR_API_KEY" } } } }

配置完成后，在项目目录启动 Claude Code：

cd ~/knowledge-base claude

进入对话后可以执行：

/mcp

如果 MCP Server 注册成功，你应该能看到docmd这个 server。若没有出现，优先检查.mcp.json是否放在项目根目录、JSON 是否合法、npx docmd@latest --help是否能正常执行。Claude Code 的模型请求和 MCP 工具调用是两条链路：模型请求走ANTHROPIC_*，工具调用走.mcp.json，两边都要配置正确。

6. Codex：config.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 中导出 Key：

export TAOTOKEN_API_KEY="YOUR_API_KEY"

如果 Codex 版本要求其他wire_api取值，以官方配置说明为准；但供应商名称、Base URL、Key 环境变量这三者的关系不变。然后配置 docmd 的 MCP Server：

[mcp_servers.docmd] command = "npx" args = ["-y", "docmd@latest", "mcp", "--stdio", "--root", "./docs"] env = { DOCS_ROOT = "./docs" }

如果 docmd 内置 AI 助手需要模型变量，可以追加：

[mcp_servers.docmd] command = "npx" args = ["-y", "docmd@latest", "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 或其他客户端之间切换，建议把配置拆成“三件套”：

CC Switch 的作用是帮你切换不同客户端配置，不改变 TaoToken 的接入方式。Claude Code 的 profile 应该生成或写入ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL；Codex 的 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_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_ccswitch 。创建后先在一个 profile 里小范围验证，确认模型对话、MCP 工具调用都正常，再复制到其他 profile。

8. 启动 docmd、验证 MCP 工具调用结果

现在把链路跑通。终端 A 启动文档站：

cd ~/knowledge-base npx docmd@latest dev --root ./docs --port 4321

浏览器打开http://localhost:4321，确认 Markdown 页面能正常渲染。终端 B 启动 MCP Server：

cd ~/knowledge-base npx docmd@latest 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_TOKEN，Codex 看env_key指定的变量。

第二类问题是 404。最常见原因是 Base URL 写错。工具配置里统一使用：

https://taotoken.net/api

不要写成带 UTM 的官网链接，也不要随意追加/v1、/chat/completions等路径。Base URL 是供应商入口，不是具体接口地址。如果你在浏览器里复制了带查询参数的地址，请把查询参数去掉。

第三类问题是 MCP Server 启动失败。先在终端手动执行：

npx docmd@latest 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 docmd@latest dev --root ./docs --port 4321 # 3. 另开终端确认 MCP Server 可手动启动 npx docmd@latest mcp --stdio --root ./docs # 4. 启动 Claude Code 或 Codex claude # 或 codex

然后在客户端里执行/mcp，确认 docmd server 在线。之后让客户端扫描文档、生成侧边栏、补全索引、检查失效链接。所有生成结果先以草稿形式输出，由你本地审阅后再写入 Markdown。需要创建新 Key 或查看额度时，从官网入口进入：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_end 。

12. 下一步：按顺序完成模型对话、Coding Plan、Key 与 Claude Code 文档

如果你还没有验证 TaoToken 的模型对话，可以先打开：

https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_chat

确认模型可用后，如果你准备把 docmd、Claude Code、Codex 长期用于文档工程，可以查看 Coding Plan：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_coding

接着创建或管理 API Key：

https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_keys_cta

最后，Claude Code 的完整配置说明见：

https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=docmd_mcp_claude_doc

按这个顺序走完，你就有了一个可复现的 docmd + MCP + TaoToken 工作流：Markdown 资料在本地编译成文档站，MCP 客户端通过 docmd 工具读取和整理文档，模型请求统一走https://taotoken.net/api，Key 只作为客户端与工具链的凭据。剩下的，就是把你的知识库目录整理干净，然后让 MCP 客户端开始调用。