功能上新 | YiAsk MCP 直连 WorkBuddy/Codex、ClickHouse 表同步与建模升级

1. YiAsk MCP 直连 WorkBuddy 与 Codex 的场景拆解YiAsk MCP 是一套把「数据问答能力」封装成 MCP 服务的方案它能让 WorkBuddy、Codex 这类客户端通过标准 MCP 协议直接调用 YiAsk 的查询与建模能力。简单说你不再需要手动把 ClickHouse 表结构复制到对话框里也不用每次重新描述字段含义客户端会自己把工具列表拉过去按需触发查询。适合谁一类是天天在 Codex 里写 SQL、做数据核对的后端和数据分析同学另一类是团队里用 WorkBuddy 做内部知识问答、希望把 ClickHouse 实时数据接进对话流的同学。我先把整体链路讲清楚后面再逐段给配置。链路是这样的WorkBuddy 或 Codex 作为 MCP Client读取一份 MCP Server 配置配置里写明服务地址、鉴权方式和要暴露的工具YiAsk MCP Server 收到请求后去连 ClickHouse把表同步和建模结果作为工具返回。这里有个关键点模型调用本身走的是 OpenAI 兼容接口所以 Base URL 和 Key 需要指向 TaoToken而不是各家默认地址。很多同学第一次配的时候只改了 MCP 部分忘了把模型请求也切过来结果工具能列出来但一调用就报鉴权错这个坑后面第五节会专门讲。为什么要把模型请求也统一到 TaoToken因为 MCP 工具调用会产生多轮请求客户端在拿到工具结果后还要再让模型总结一次。如果模型侧走的是另一个地址、另一套 Key排查问题时你根本分不清是 MCP 服务挂了还是模型鉴权失败。统一入口之后日志里看到的 401、超时、模型名不存在都能在一个地方定位。这也是我建议先配模型侧、再配 MCP 侧的原因。ClickHouse 表同步与建模升级这块本质是把「表结构 字段语义 建模口径」做成 MCP 工具能读到的元数据。以前的做法是写死在 prompt 里表一改就得改 prompt升级后由 YiAsk MCP 动态读取表同步完成工具返回的字段描述就是最新的。你要做的动作有两个一是确认 ClickHouse 连接信息正确二是同步完成后核对工具返回的表清单和字段是否和库里一致。这两步在第四节有具体的验证命令。场景讲完了接下来是前置准备。你需要一个可用的 TaoToken API Key、一份能访问 ClickHouse 的网络环境、以及 WorkBuddy 或 Codex 的安装。注意这里说的网络环境是指你的服务能正常访问 ClickHouse 和 TaoToken 接口不涉及任何特殊网络工具正常公司内网或云主机即可。Key 的获取和文档入口我放在第二节配置片段放在第三节都是可以直接复制改的。2. TaoToken 前置准备与 Key 获取路径在动手改配置之前先把 TaoToken 这边的准备工作做完。你需要的是三样东西API Key、Base URL、以及要用的 Model ID。这三样在后面的 Codex auth.json、MCP 配置、以及验证请求里都会反复出现建议先记在一个临时文件里。API Key 的获取入口在控制台的 API Keys 页面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后新建一个 Key复制出来。注意 Key 只在创建时完整显示一次关掉页面就看不到了所以复制后先存好。如果你之前已经建过直接复用也行但建议给 MCP 场景单独建一个方便后面按 Key 维度看调用量。Base URL 统一用 https://taotoken.net/api 这个地址不加任何查询参数直接填在需要 Base URL 的地方。Model ID 按你实际要用的模型填比如做代码和工具调用比较多的场景选一个支持 function calling 的模型即可。具体有哪些模型、各自适合什么可以在模型对话页面里试地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在那边发一条消息能正常返回就说明 Key 和 Base URL 没问题再去配 MCP 会省很多事。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了 OpenAI 兼容接口的调用方式、参数说明和常见返回。配 MCP 之前扫一遍尤其是鉴权头和请求体格式那两段后面排障会用到。如果你打算长期跑编码和 Agent 任务可以看下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用的场景这里先不展开。前置准备里还有一个容易忽略的点确认你的运行环境能解析并访问 taotoken.net。有些内网环境对出站域名有白名单如果没放行你会看到连接超时而不是鉴权错误。验证方法很简单在准备跑 MCP 的机器上执行一条 curl能拿到返回就说明网络通。这个命令我放在第四节和连通性验证一起做。另外提醒一句Key 不要写进会提交到代码仓库的文件里。Codex 的 auth.json、MCP 的配置文件如果放在项目目录下记得加进 .gitignore。我见过有人把带 Key 的配置直接 push 上去虽然可以事后吊销但麻烦。用环境变量引用是更稳的做法第三节的配置里我会同时给直接填和用环境变量两种写法。3. 可复制配置MCP 服务端、Codex auth.json 与 Base URL这一节是全文的核心给的都是可以直接复制、改完就能用的片段。分三块MCP 服务端配置、Codex 的 auth.json、以及 Base URL 的落点。每块我都会说明路径和字段含义你按自己环境替换占位符即可。先看 MCP 服务端配置。不同客户端的配置文件位置不一样WorkBuddy 和 Codex 读取的路径也不同但结构大同小异核心是 mcpServers 这个对象。下面这份是通用结构你把它放到对应客户端的 MCP 配置里{ mcpServers: { yiask: { command: npx, args: [ -y, yiask-mcp-server ], env: { YIASK_BASE_URL: https://taotoken.net/api, YIASK_API_KEY: sk-你的TaoTokenKey, YIASK_MODEL: 你的ModelID, CLICKHOUSE_HOST: 你的ClickHouse地址, CLICKHOUSE_PORT: 8123, CLICKHOUSE_USER: default, CLICKHOUSE_PASSWORD: 你的密码, CLICKHOUSE_DATABASE: 你的库名 } } } }这里几个字段要重点说。YIASK_BASE_URL 填 https://taotoken.net/api 不要带结尾斜杠也不要加 UTM 参数接口地址加参数会导致路径拼接错误。YIASK_API_KEY 填你在第二节拿到的 Key。YIASK_MODEL 填支持工具调用的模型 ID。下面四个 CLICKHOUSE_ 开头的字段按你实际库填端口默认 8123 是 HTTP 接口如果你用的是 9000 原生协议要确认 MCP 服务支持哪种一般用 8123 更省事。如果你不想把 Key 明文写在配置里把 env 里的值改成环境变量引用。以 macOS 或 Linux 为例先在 shell 里 exportexport YIASK_API_KEYsk-你的TaoTokenKey export CLICKHOUSE_PASSWORD你的密码然后配置里写成YIASK_API_KEY: ${YIASK_API_KEY}。注意不同客户端对变量展开的支持不一样WorkBuddy 和 Codex 都支持${VAR}形式但如果你用的是别的客户端先确认它是否支持不支持就还是直接填。再看 Codex 的 auth.json。Codex 把鉴权信息放在用户目录下的 .codex/auth.json路径通常是~/.codex/auth.json。内容结构如下{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api }这里两个字段名是 Codex 认的不要改成别的。OPENAI_API_KEY 填 TaoToken 的 KeyOPENAI_BASE_URL 填 https://taotoken.net/api 。改完之后 Codex 发起的模型请求就会走 TaoToken。如果你之前配过别的地址记得整个替换掉不要留旧字段否则可能出现两个地址同时存在、行为不确定的情况。Base URL 的落点有三个地方要检查一是 Codex 的 auth.json二是 MCP 配置里的 YIASK_BASE_URL三是如果你在环境变量里设了 OPENAI_BASE_URL也要一并改。三处保持一致后面排障才简单。Model ID 同理Codex 侧如果单独配了模型名要和 MCP 配置里的 YIASK_MODEL 对得上或者至少都是 TaoToken 支持的模型。配置改完先别急着跑做一次语法检查。JSON 文件最容易出问题的就是多一个逗号、少一个引号。用下面这条命令校验python3 -m json.tool ~/.codex/auth.json能正常输出格式化后的 JSON 就说明语法没问题。MCP 配置文件同理把路径换成你的文件即可。这一步花十秒能省掉后面半小时的排查。4. 连通性验证与 ClickHouse 表同步结果核对配置写完接下来是验证。验证分两层先确认模型侧通再确认 MCP 工具能列出来、能调用最后核对 ClickHouse 表同步结果。顺序不要乱从下往上排障最快。第一层验证 TaoToken 接口连通。在跑 MCP 的机器上执行curl -s -o /dev/null -w %{http_code}\n https://taotoken.net/api/models \ -H Authorization: Bearer sk-你的TaoTokenKey返回 200 说明网络和 Key 都没问题。如果返回 401是 Key 不对或没带上返回超时是网络没通检查出站白名单。这一步过了再往下。第二层验证 MCP 工具列表。启动你的客户端让它加载 MCP 配置。以 Codex 为例启动后输入查看工具的指令正常会列出 yiask 相关的工具比如查询表、执行 SQL、获取表结构之类。如果工具列表是空的说明 MCP 服务没起来去看客户端的 MCP 日志通常是 command 或 args 写错或者 npx 拉包失败。npx 第一次拉包需要网络如果环境不能访问 npm 源需要提前装好或换源。第三层调用一次工具验证 ClickHouse 连通。让客户端执行一个最简单的查询比如列出当前库的表SELECT name FROM system.tables WHERE database 你的库名 LIMIT 10如果返回了表名列表说明 ClickHouse 连接正常。如果报连接被拒检查 CLICKHOUSE_HOST 和 PORT如果报认证失败检查 USER 和 PASSWORD如果报库不存在检查 CLICKHOUSE_DATABASE。这一步的结果就是表同步的基线你记下返回的表数量。第四层核对表同步与建模升级结果。表同步完成后让 MCP 工具返回某张表的字段描述和你直接在 ClickHouse 里查 system.columns 的结果对比SELECT name, type, comment FROM system.columns WHERE database 你的库名 AND table 你的表名两边字段名、类型、注释要一致。如果 MCP 返回的字段比库里少说明同步没跑完或缓存没刷新重新触发一次同步。建模升级的部分重点看字段语义描述是否更新比如你给某个字段加了注释MCP 返回里应该能看到新注释。这一步是很多人会跳过的但恰恰是「表同步与建模升级」是否真正生效的判断依据。验证通过后建议把这次成功的配置和验证命令记下来。下次换环境或加新表直接照着跑一遍比重新摸索快得多。如果你在验证模型返回时想快速试不同模型的表现可以用模型对话页面发几条测试消息地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 那边能直观看到返回不用每次都走 MCP 链路。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每条都给现象、原因、动作。你遇到哪个直接对号入座。401 Unauthorized。现象是模型请求或 MCP 工具调用返回 401。原因通常是三种Key 填错、Key 没带上、或者 Base URL 和 Key 不匹配。动作先用第四节的 curl 命令单独验证 Key通了再检查 MCP 配置里的 YIASK_API_KEY 和 Codex auth.json 里的 OPENAI_API_KEY 是否一致。如果 curl 通但 MCP 报 401多半是 MCP 服务读到的环境变量没生效检查 env 字段拼写或者变量展开是否被客户端支持。local proxy failed。现象是客户端启动时报本地代理失败或者请求发不出去。原因一般是客户端配置了本地代理地址但那个地址没在跑或者端口被占。动作检查客户端和系统的代理设置把指向本地端口的代理关掉让请求直连。注意这里说的是关掉本地代理配置不是让你去用什么特殊网络工具正常直连 taotoken.net 即可。如果公司网络要求走统一出口按公司规范配不要自己加中间层。reading choices 相关报错。现象是返回体解析失败提示读取 choices 字段出错。原因是返回的不是标准 OpenAI 格式常见于 Base URL 填错请求打到了非兼容接口上。动作确认 Base URL 是 https://taotoken.net/api 结尾没有多余路径和参数。如果你填成了带 /v1 或其他后缀的地址改回来。另外检查 Model ID 是否是 TaoToken 支持的不支持的模型名可能返回错误结构。OAuth 相关报错。现象是 Codex 提示 OAuth 登录或 token 失效。原因是 Codex 某些版本默认走 OAuth 流程而你用的是 API Key 模式。动作确认 auth.json 里用的是 OPENAI_API_KEY 字段而不是 OAuth 的 token 字段把 OAuth 相关字段清掉。如果客户端强制走 OAuth查一下它的配置项切到 API Key 模式。改完重启客户端让它重新读 auth.json。还有一类不报错但行为不对的情况工具能列出来调用也返回但结果是旧的。这通常是 ClickHouse 表同步缓存没刷新。动作重新触发同步或者重启 MCP 服务再按第四节第四层核对一次。如果还不对检查 CLICKHOUSE_DATABASE 是否指向了正确的库有时候默认库和实际库不是一个。排查时有个通用技巧把 MCP 服务的日志级别调高让它打印每次请求的 URL、状态码和返回体前几百字符。大部分问题看日志就能定位比猜快。日志里如果看到请求地址不是 taotoken.net/api 开头那就是 Base URL 没配对如果看到 Key 是空的那就是环境变量没读到。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔查一次数据上面的配置够用了。但如果你打算把 YiAsk MCP 长期用在编码和 Agent 任务里有几个点值得提前处理。第一Key 和配置的分离。把 Key 放环境变量配置文件进版本库时只放模板。这样换 Key 不用改文件也不会误提交。团队协作时每个人用自己的 Key调用量按人区分出问题好定位。第二模型选择。工具调用密集的场景选一个 function calling 稳定的模型比选一个单纯对话强的模型更重要。你可以在模型对话页面多试几个看工具调用返回是否规范。地址还是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试的时候重点看它会不会正确触发工具、参数格式对不对。第三表同步的频率。ClickHouse 表结构变更不频繁的话手动触发同步就行如果经常加字段考虑定时同步。同步本身不复杂关键是同步后要核对别让 MCP 返回的元数据和库里脱节。第四接入文档常备。参数、返回格式、错误码这些文档里都有地址 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。遇到没见过的问题先翻文档比到处问快。第五高频调用看 Coding Plan。如果你的 Agent 任务一天要跑很多轮按量计费可能不划算Coding Plan 更适合这种场景地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。具体选哪个按你的调用量算一下就知道。最后说个实操细节MCP 服务启动后第一次工具调用会慢一点因为要初始化 ClickHouse 连接和拉取表元数据。这是正常的别以为是卡住了。等第一次返回后后续调用会快很多。如果你在客户端里看到转圈很久先等十秒还没反应再去看日志。配置改完、验证跑通、表同步核对无误这套链路就算落地了。后面加新表、换模型、调 Key都按第三节改配置、第四节验证的顺序走一遍即可。