把 MCP 挂进 docmd，AI 助手调用走 TaoToken 记账

1. 从 docmd 的 MCP 入口切进 TaoToken 记账链路

如果你正在用 docmd 把 Markdown 资料生成文档站，并且准备把它的 AI 助手和 MCP 能力接到 Claude Code、Codex 或自研客户端，第一步不是改 Markdown，而是先到 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_intro 拿一个可用的 Key，并把工具里的 Base URL 统一写成https://taotoken.net/api。这样做的原因很直接：docmd 负责把散落的 Markdown 变成可检索、可浏览的文档站，MCP 负责让 AI 助手以标准工具协议读取这些文档，而 TaoToken 负责把 docmd AI 助手与 MCP 调用产生的每一次模型请求落到同一个账号下，方便看模型、看 Key、看调用量。

很多团队在搭文档站时，会先解决“文档能不能生成”和“页面好不好看”，但一旦接入 AI 助手，问题就变成“它到底读没读到文档”“这次回答消耗了多少 Token”“是哪个 Key 在调用”“MCP 工具链有没有断”。docmd 自带的 AI 助手和 MCP 很适合做这件事：一条命令把 Markdown 资料生成文档站，同时把文档检索暴露给 MCP 客户端。但模型请求最终要有一个稳定的出口，否则你会在多个客户端、多个 Key、多个模型之间来回切换。本文以 MCP 集成开发者视角，给出一套可复现的接入方式：docmd 侧启用 AI 助手与 MCP，Claude Code / Codex / CC Switch 侧挂载 docmd MCP Server，模型请求统一走 TaoToken，最后通过记账日志和调用链排查问题。

需要先说明边界：本文不会让 MCP 或 Agent 直连 Oracle、生产数据库或其他敏感系统。docmd 的 MCP 只应读取你明确暴露的 Markdown 文档目录，SQL、运维命令、数据导出等动作应由读者在本地或受控环境执行。MCP 的定位是“让 AI 助手安全地拿到文档上下文”，不是把生产权限交给模型。

2. 准备 TaoToken Key、Base URL 与 docmd 项目骨架

第一步是把账号和 Key 准备好。打开 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_prepare ，进入控制台后创建 API Key。创建入口可以直接用这个 deep link：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_apikey 。Key 创建后只显示一次，复制到安全位置，本文后续统一用YOUR_API_KEY占位。不要把真实 Key 写进 Markdown、Git 仓库或前端代码。

TaoToken 在工具配置里的 Base URL 固定写：

https://taotoken.net/api

注意，Base URL 本身不带 UTM 参数。UTM 只用于官网入口和 deep link 跳转，不用于 API 请求地址。很多 401、404 问题都来自把浏览器地址和 API Base URL 混在一起，或者把/v1重复拼了两次。后面我们会把请求路径写成${BASE_URL}/v1/chat/completions这类形式。

准备一个本地 docmd 演示项目：

mkdir -p docmd-mcp-demo/docs cd docmd-mcp-demo npm init -y

创建几篇 Markdown 资料，例如：

cat > docs/quickstart.md <<'MD' # Quickstart docmd 可以把 Markdown 资料生成文档站。 本文档用于验证 MCP 检索与 TaoToken 记账。 MD cat > docs/api.md <<'MD' # API Base URL: https://taotoken.net/api Key: YOUR_API_KEY MD

然后按你本地安装的 docmd CLI 初始化并启动。不同版本命令名可能略有差异，核心是init、dev、build、mcp这几个子命令：

npx docmd@latest --help npx docmd@latest init docs npx docmd@latest dev --root ./docs

如果init会生成docmd.config.json、docmd.config.js或类似配置文件，保留它，下一步我们会把 AI 助手和 MCP 的模型出口指向 TaoToken。这里不追求页面主题多复杂，先保证三件事：Markdown 能生成站点、AI 助手能调用模型、MCP 能暴露文档检索工具。

设置环境变量，让后续所有子进程都能拿到 TaoToken Key 和 Base URL：

export TAOTOKEN_API_KEY="YOUR_API_KEY" export DOCMD_AI_BASE_URL="https://taotoken.net/api" export DOCMD_AI_API_KEY="$TAOTOKEN_API_KEY" export DOCMD_AI_MODEL="<你的模型ID>"

<你的模型ID>不要凭感觉填。你可以先在 TaoToken 的模型对话页面确认可用模型名：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_chat 。如果 docmd 的 AI 配置字段与示例不同，优先保留三个核心值：Base URL 为https://taotoken.net/api，Key 从环境变量读取，模型名使用控制台里实际存在的 ID。

可以用一个最小请求验证 Key 和 Base URL 是否可用：

curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<你的模型ID>", "messages": [ { "role": "user", "content": "只回复：TaoToken 记账测试" } ], "max_tokens": 32 }' | jq -r '.choices[0].message.content'

如果这里能返回内容，说明 Key、Base URL、模型名至少有一组是通的。如果返回 401，优先检查 Key 是否完整、是否带了Bearer；如果返回 404，检查 URL 是否被写成了https://taotoken.net/api/api/v1/...或漏了/v1；如果提示模型不存在，回到模型对话页复制准确模型 ID。

3. docmd 侧配置：让 AI 助手与 MCP 都走 TaoToken

docmd 的配置通常围绕站点根目录、构建输出、AI 助手和 MCP 展开。下面给出一份“可迁移骨架”，字段名请按你安装的 docmd 版本替换，但值的方向保持一致：AI 助手和 MCP 内部需要模型时，都走 TaoToken。

{ "site": { "title": "MCP 文档站", "root": "./docs", "output": "./dist" }, "ai": { "enabled": true, "provider": "openai-compatible", "baseURL": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "model": "<你的模型ID>", "systemPrompt": "只基于当前文档站内容回答，回答时给出文档相对路径。" }, "mcp": { "enabled": true, "transport": "stdio", "tools": [ "list_docs", "search_docs", "read_doc" ] } }

如果你的 docmd 版本使用 JavaScript 配置，可以写成：

// docmd.config.js export default { site: { title: 'MCP 文档站', root: './docs' }, ai: { enabled: true, provider: 'openai-compatible', baseURL: process.env.DOCMD_AI_BASE_URL || 'https://taotoken.net/api', apiKey: process.env.TAOTOKEN_API_KEY, model: process.env.DOCMD_AI_MODEL || '<你的模型ID>', systemPrompt: '只基于当前文档站内容回答，引用相对路径。' }, mcp: { enabled: true, transport: 'stdio', tools: ['list_docs', 'search_docs', 'read_doc'] } }

这里的关键点有三个：

第一，baseURL或baseUrl必须指向https://taotoken.net/api，不要带 UTM，也不要带多余的/v1。OpenAI 兼容请求通常会自动拼接/v1/chat/completions，具体以 docmd 的 HTTP 客户端实现为准。

第二，API Key 不要硬编码。用TAOTOKEN_API_KEY、DOCMD_AI_API_KEY这类环境变量传入。Claude Code、Codex、CC Switch 启动 docmd MCP 时，如果只配置了 MCP 命令却没有把环境变量传给子进程，就会出现“本地 curl 能通，MCP 调用却 401”的经典问题。

第三，MCP 工具先只开只读能力。list_docs、search_docs、read_doc已经能覆盖大多数文档问答场景。不要让 MCP 工具拥有写文件、执行 Shell、访问数据库的能力。文档站是知识入口，不是运维入口。

启动 docmd 并观察日志：

npx docmd@latest dev --root ./docs

然后在另一个终端里测试 MCP Server 是否可启动。不同版本可能把 MCP 入口暴露为mcp子命令：

TAOTOKEN_API_KEY="YOUR_API_KEY" \ DOCMD_AI_BASE_URL="https://taotoken.net/api" \ DOCMD_AI_MODEL="<你的模型ID>" \ npx -y docmd mcp --root ./docs

如果它通过 stdio 等待握手，说明入口正常。如果命令直接退出，先看是否有--help或mcp --help，确认参数名是--root还是--docs。MCP 挂载配置最怕“命令名错、工作目录错、环境变量没传”这三类问题。

为了后续排查调用链，建议在 docmd 项目里加一个明确的项目标识，例如：

export DOCMD_PROJECT="mcp-doc-site" export DOCMD_MCP_TOOLSET="readonly"

如果 docmd 支持在请求头里带自定义元数据，可以把项目名带上；如果不支持，就在 TaoToken 控制台里按 Key 区分项目。比如为docmd-mcp-demo单独创建一个 Key，而不是复用个人主 Key。

4. 把 docmd MCP Server 挂进 Claude Code、Codex 与 CC Switch

MCP 集成开发者的日常通常不是只用一个客户端。你可能在 Claude Code 里调试文档问答，在 Codex 里跑仓库级任务，再用 CC Switch 管理多套供应商配置。这里的原则是：客户端可以不同，但 docmd MCP Server 的启动方式一致，模型出口也一致走 TaoToken。

4.1 Claude Code：settings.json 与 ANTHROPIC_*

Claude Code 侧使用settings.json或项目级配置。下面示例同时设置 Claude Code 自身的模型出口和 docmd MCP Server 子进程环境。真实路径以你本地为准，常见用户级路径为~/.claude/settings.json。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "<你的模型ID>" }, "mcpServers": { "docmd": { "command": "npx", "args": [ "-y", "docmd", "mcp", "--root", "./docs" ], "env": { "TAOTOKEN_API_KEY": "YOUR_API_KEY", "DOCMD_AI_BASE_URL": "https://taotoken.net/api", "DOCMD_AI_MODEL": "<你的模型ID>", "DOCMD_PROJECT": "mcp-doc-site" } } } }

这里ANTHROPIC_*只用于 Claude Code 自身，不要把这些变量套到 Codex。Claude Code 的 MCP 列表可以通过/mcp查看，如果配置正确，应该能看到docmd以及它的只读工具。需要更完整的 Claude Code 配置说明时，可以看 TaoToken 的 Claude Code 文档：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_claudecode 。

一个容易忽略的点：cwd。如果 Claude Code 启动 MCP 子进程时的工作目录不是 docmd 项目根目录，--root ./docs就会指向错误位置。可以在 args 里写绝对路径，或者确认客户端支持cwd字段：

{ "mcpServers": { "docmd": { "command": "npx", "args": ["-y", "docmd", "mcp", "--root", "/ABS/PATH/docmd-mcp-demo/docs"], "env": { "TAOTOKEN_API_KEY": "YOUR_API_KEY", "DOCMD_AI_BASE_URL": "https://taotoken.net/api", "DOCMD_AI_MODEL": "<你的模型ID>" } } } }

4.2 Codex：config.toml 与 model_providers

Codex 使用~/.codex/config.toml。这里不要写ANTHROPIC_*，Codex 的供应商配置走自己的model_providers和mcp_servers。

model = "<你的模型ID>" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat" [mcp_servers.docmd] command = "npx" args = ["-y", "docmd", "mcp", "--root", "./docs"] env = { TAOTOKEN_API_KEY = "YOUR_API_KEY", DOCMD_AI_BASE_URL = "https://taotoken.net/api", DOCMD_AI_MODEL = "<你的模型ID>", DOCMD_PROJECT = "mcp-doc-site" }

wire_api用chat还是其他值，取决于 Codex 版本和模型兼容层。如果启动报协议不匹配，先用模型对话页确认模型能力，再调整wire_api。Codex 的 MCP 配置字段名也可能随版本变化，核心仍是command、args、env三件套。

4.3 CC Switch：三件套配置

CC Switch 适合管理多套供应商配置。你可以把 TaoToken 作为一个供应商加入，然后分别绑定到 Claude Code、Codex 和通用 MCP 客户端。三件套建议这样填：

provider: name: TaoToken base_url: https://taotoken.net/api api_key: YOUR_API_KEY models: default: "<你的模型ID>" claude_code: env: ANTHROPIC_BASE_URL: https://taotoken.net/api ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY ANTHROPIC_MODEL: "<你的模型ID>" codex: config: model: "<你的模型ID>" model_provider: taotoken model_providers: taotoken: base_url: https://taotoken.net/api env_key: TAOTOKEN_API_KEY wire_api: chat mcp_servers: docmd: command: npx args: ["-y", "docmd", "mcp", "--root", "./docs"] env: TAOTOKEN_API_KEY: YOUR_API_KEY DOCMD_AI_BASE_URL: https://taotoken.net/api DOCMD_AI_MODEL: "<你的模型ID>"

CC Switch 的价值在于减少手改配置文件。但要注意：切换供应商后，某些客户端需要重启，MCP Server 也需要重启。否则你以为已经切到 TaoToken，实际 docmd 子进程还在用旧环境变量。

5. 验证调用链：从 MCP 握手到记账日志

配置完成后，不要只看页面能不能打开。MCP 集成要验证完整调用链：客户端发起问题，MCP 客户端发现 docmd 工具，docmd 读取 Markdown，模型请求走 TaoToken，最后在控制台看到用量。

第一步，检查 MCP Server 是否被客户端识别。Claude Code 里执行/mcp，Codex 里查看 MCP 列表。你应该看到类似：

docmd tools: - list_docs - search_docs - read_doc

第二步，发一个只依赖文档的问题，例如：

请用 docmd 的 search_docs 查找 quickstart.md，然后总结它说了什么。

如果客户端没有调用工具，而是直接凭记忆回答，说明 MCP 工具没有被触发。检查 docmd MCP Server 是否真的启动、工具描述是否可读、客户端是否需要显式允许工具调用。

第三步，看 docmd 侧日志。理想情况下能看到工具调用顺序：

[mcp] tool call: list_docs [mcp] tool call: search_docs query="quickstart" [mcp] tool call: read_doc path="quickstart.md" [ai] request baseURL=https://taotoken.net/api model=<你的模型ID> [ai] response usage.prompt_tokens=812 completion_tokens=143

第四步，看 TaoToken 记账。进入 API Keys 页面或用量日志，按 Key、模型、时间筛选。你应该能对应到刚才那次请求。一个典型的记账记录会包含请求 ID、模型、Token 用量和调用时间：

{ "request_id": "req_xxx", "key_hint": "sk-...abcd", "model": "<你的模型ID>", "usage": { "prompt_tokens": 812, "completion_tokens": 143, "total_tokens": 955 }, "project": "mcp-doc-site", "source": "docmd-mcp" }

如果项目字段没有自动带过去，就用独立 Key 区分。比如为docmd-mcp-demo建一个 Key，为其他 MCP Server 建另一个 Key。这样在 TaoToken 控制台里按 Key 过滤，就能看出 docmd AI 助手与 MCP 的消耗占比。

第五步，验证“助手调用链”是否可复现。建议固定一个测试问题，每次改配置后都跑一遍：

# 只做 Key 连通性测试 curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<你的模型ID>", "messages": [{"role": "user", "content": "列出你看到的文档工具名"}], "max_tokens": 64 }' | jq .

然后在 MCP 客户端里问：

请调用 docmd 的 list_docs，列出当前文档站可读文件。

如果两边都能通，但 MCP 客户端里没有记账，重点查 MCP 子进程环境变量。env没有继承时，子进程会拿不到TAOTOKEN_API_KEY。

6. 常见故障排查：401、404、模型名与 MCP 超时

6.1 401 Unauthorized

优先检查三处：

echo $TAOTOKEN_API_KEY curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"<你的模型ID>","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

如果 curl 不通，问题在 Key 或 Base URL；如果 curl 通、MCP 不通，问题在 MCP 客户端没有把环境变量传给 docmd 子进程。Claude Code 的settings.json、Codex 的config.toml、CC Switch 的 MCP 配置里，都要显式写TAOTOKEN_API_KEY。

6.2 404 Not Found

最常见原因是路径拼接错误。Base URL 写https://taotoken.net/api，实际请求路径通常是https://taotoken.net/api/v1/chat/completions。不要再写成：

https://taotoken.net/api/v1/v1/chat/completions https://taotoken.net/api/api/v1/chat/completions https://taotoken.net/api?utm_source=...

最后一个尤其要注意：UTM 参数只用于官网和 deep link，不要带进 API Base URL。

6.3 模型名不存在

模型名不要写“默认”“最强”“便宜版”这种描述。到模型对话页复制准确 ID： https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_chat 。如果 docmd 的 AI 助手和 MCP 工具使用不同模型，建议分别配置：助手用对话模型，MCP 检索后的总结用同一模型或更轻量模型。

6.4 MCP 握手失败或超时

先本地直接启动 docmd MCP：

TAOTOKEN_API_KEY="YOUR_API_KEY" \ DOCMD_AI_BASE_URL="https://taotoken.net/api" \ DOCMD_AI_MODEL="<你的模型ID>" \ npx -y docmd mcp --root ./docs

如果本地启动不了，客户端一定挂不上。常见原因包括：

• npx不在客户端 PATH 中，改为绝对路径；
• --root指向错误目录，改为绝对路径；
• Node 版本不满足 docmd 要求；
• 文档站太大，首次索引超时，先限制只读目录；
• 客户端把 stderr 当成协议输出，查看客户端 MCP 日志。

6.5 记账不显示或消耗异常

如果 TaoToken 控制台看不到 docmd 的调用，先确认 MCP 子进程环境变量，再确认 docmd 的 AI 请求是否真的走了 TaoToken。可以在本地开一个临时日志，打印 baseURL 和模型名，但不要打印完整 Key。若是消耗异常，检查是否存在重复索引、重复问答、工具循环调用。MCP 工具最好限制最大调用次数，并在 system prompt 里要求“先 search 再 read，不要反复列目录”。

7. 生产化建议与 CTA

把 MCP 挂进 docmd 之后，建议按项目拆 Key。例如：

TAOTOKEN_KEY_DOCMD_SITE=YOUR_API_KEY TAOTOKEN_KEY_DOCMD_MCP=YOUR_API_KEY TAOTOKEN_KEY_CLAUDE_CODE=YOUR_API_KEY TAOTOKEN_KEY_CODEX=YOUR_API_KEY

在 TaoToken 控制台里按 Key 看用量，比在一个大 Key 里猜来源要清晰得多。MCP 调用链建议保留三个关联字段：docmd 工具名、MCP 客户端名、TaoToken 请求 ID。这样出问题时可以快速定位是“文档没读到”还是“模型没调用”。

另外，docmd 的 MCP 只读工具不要扩展成写操作。需要更新文档时，由人修改 Markdown 并提交到版本库，再由 docmd 重新构建。不要给 MCP 直接执行 SQL、访问生产库、修改线上配置的能力。MCP 集成开发者的重点是把文档上下文安全地交给 AI 助手，而不是把系统权限交出去。

如果你还没有 Key，先到 TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_cta 注册并创建。然后按这个顺序走一遍：

1. 在模型对话页确认模型 ID：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_chat
2. 查看 Coding Plan，选择适合 docmd AI 助手与 MCP 的套餐：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_plan
3. 创建项目独立 Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_apikey
4. 如果主要用 Claude Code 调 MCP，参考 Claude Code 文档：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=mcp_docmd_claudecode

配置完成后，用一句“请调用 docmd 的 search_docs 查 quickstart.md”做验收。看到 MCP 工具调用、docmd 日志、TaoToken 记账记录三件事都串起来，再把 Base URLhttps://taotoken.net/api和YOUR_API_KEY固化到你的 CC Switch 或项目配置里。这样 docmd 负责文档站，MCP 负责工具协议，TaoToken 负责把 AI 助手与 MCP 的每一次模型消耗记清楚。