1. 为什么要把 Loki 查询接进 AI 客户端Loki MCP Server 是一个用 Go 写的 MCP 服务端它把 Grafana Loki 的日志查询能力包装成三个标准 MCP Tool让 Claude Desktop、Claude Code、Cursor 这类客户端可以用自然语言代替手写 LogQL。你不再需要记住{appxxx} | ERROR这种语法直接说帮我查一下 prod 环境最近 5 分钟的错误日志就行。它适合谁运维、后端、SRE以及任何需要频繁翻日志但不想每次打开 Grafana 点来点去的人。三个 Tool 分别是loki_query执行 LogQL 查询、loki_label_names拿所有标签名、loki_label_values拿某个标签的值列表覆盖了日常排查的绝大多数动作。但真正落地时会遇到一个现实问题MCP 服务端和 AI 客户端之间的模型调用链路如果直连官方端点在稳定性、计费和密钥管理上都不太顺手。这篇要解决的就是把这条链路统一改到 TaoToken 上——服务端的 endpoint 走 TaoToken客户端的 Base URL 也走 TaoToken用一次自然语言日志检索来验证整条链路通不通。我试过把 MCP 服务端和客户端分开配置结果两边认证对不上排查了半天。所以下面会把服务端和客户端两侧的配置都写清楚你照着填就行。2. TaoToken 前置准备与 MCP 链路改造思路在动手改配置之前先把 TaoToken 这边的准备工作做完。你需要一个可用的 API Key以及确认要用的模型 ID。这两样东西后面在服务端和客户端配置里都会反复出现。2.1 拿 Key 和确认模型打开 TaoToken 控制台在 API Keys 页面创建一个新的 Key。创建时建议按用途命名比如loki-mcp-dev方便后面区分。Key 只在创建时完整显示一次复制下来存好。模型 ID 这块Claude Desktop 和 Claude Code 走的是 Anthropic 兼容协议Cursor 走 OpenAI 兼容协议两者在 TaoToken 上都支持。你可以在模型对话页面先试一下目标模型能不能正常返回确认可用再写进配置。2.2 为什么服务端和客户端都要改这里有个容易搞混的点。Loki MCP Server 本身是个独立的 HTTP 服务它负责跟 Loki 通信而 AI 客户端Claude Desktop 等负责跟模型通信。这两条链路是分开的服务端 → Loki这条链路走的是 Loki 的 API跟 TaoToken 无关配置的是LOKI_URL。客户端 → 模型这条链路才是走 TaoToken 的地方配置的是客户端的 Base URL 和 API Key。所以把 endpoint 和 Base URL 改到 TaoToken指的是MCP 服务端对外暴露的地址客户端连它用的保持你自己的部署地址而客户端连模型用的 Base URL 改成 TaoToken。如果你用的是托管型 MCP 服务那服务端 endpoint 本身也可能需要指向 TaoToken 的接入地址。2.3 三件套先备齐不管哪个客户端接入时都要凑齐三件套Base URL、API Key、Model ID。缺一个就连不上。下面这张表先给你一个全局印象项目值用在哪Base URLhttps://taotoken.net/api客户端模型调用API Key控制台创建客户端认证Model ID控制台确认客户端指定模型LOKI_URL你的 Loki 地址MCP 服务端连 Loki把这几项写在一个便签里后面配置直接抄。3. 可复制配置Claude Desktop / Claude Code / Cursor 三端接入这一节是重点三个客户端的配置文件路径和字段都不一样我逐个给出来。所有配置里的 Base URL 都指向 TaoTokenKey 换成你自己的。3.1 Claude Desktop 配置Claude Desktop 的 MCP 配置在claude_desktop_config.json里。macOS 路径是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 是%APPDATA%\Claude\claude_desktop_config.json。如果你用本地 Docker 跑 Loki MCP Server配置长这样{ mcpServers: { loki: { command: docker, args: [ run, --rm, -i, -e, LOKI_URLhttp://host.docker.internal:3100, loki-mcp-server:latest ] } } }但模型调用这块Claude Desktop 本身不直接读 Base URL 配置它走的是账号体系。如果你要让它走 TaoToken需要在客户端层面把模型端点指过去。对于支持自定义端点的版本配置项类似{ apiBaseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: 你的_Model_ID }注意host.docker.internal是 Docker 访问宿主机的地址Mac 和 Windows 都支持Linux 上要换成宿主机实际 IP。3.2 Claude Code 配置Claude Code 用命令行接入最省事。Streamable HTTP 是推荐的传输方式claude mcp add --transport http --scope user loki https://你的-mcp-地址/stream这条命令把 Loki MCP Server 注册到用户级配置里。--scope user表示对所有项目生效如果只想当前项目用去掉这个参数。模型端点这块Claude Code 读的是环境变量。在 shell 配置文件~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_Key export ANTHROPIC_MODEL你的_Model_ID改完执行source ~/.zshrc生效。这里的三件套就是前面说的 Base URL、Key、Model ID一个都不能少。3.3 Cursor 配置Cursor 的 MCP 配置在~/.cursor/mcp.json全局或项目下的.cursor/mcp.json。格式跟 Claude Desktop 类似{ mcpServers: { loki: { command: docker, args: [ run, --rm, -i, -e, LOKI_URLhttp://host.docker.internal:3100, loki-mcp-server:latest ] } } }Cursor 的模型端点走 OpenAI 兼容协议在设置里找到 Models 面板填入{ baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: 你的_Model_ID }Cursor 支持在设置界面直接填也可以改配置文件。填完记得点 Verify 验证一下连通性。3.4 服务端环境变量对照MCP 服务端这边跟 TaoToken 无关但必须配对的是 Loki 相关变量。如果你把服务端也部署在需要走 TaoToken 的场景参考这张表变量用途示例LOKI_URLLoki 地址http://localhost:3100LOKI_ORG_ID多租户 ID空LOKI_TOKENBearer Token空PORT服务端口8080服务端启动后监听 8080同时支持 stdio、SSE/sse、Streamable HTTP/stream三种传输一个端口全搞定。4. 验证请求用自然语言查一次日志配置写完得验证整条链路。这一步分两段先确认 MCP 服务端本身能查到 Loki再确认 AI 客户端能通过自然语言触发查询。4.1 先验证服务端到 Loki在客户端之前先用脚本确认服务端能正常查 Loki。项目里带了测试脚本./insert-loki-logs.sh --num 20 --job custom-job --app my-app ./test-loki-query.sh {jobvarlogs} -1h now 50第一条插入测试日志第二条查询验证。如果返回了日志行说明服务端到 Loki 这条链路是通的。4.2 再验证客户端到模型打开 Claude Code输入/mcp看 Loki 有没有注册上。然后直接说人话loki 查看所有可用的标签名正常的话客户端会调用loki_label_names返回一列标签名像app、env、job、namespace、pod这些。这一步验证的是客户端能识别 MCP Tool 并触发调用。4.3 完整自然语言检索接着做一次真正的日志检索查询 appmy-app envprod 的近 5 分钟错误日志帮我分析下客户端会调用loki_query参数里带上 LogQL 查询、时间范围和 limit。返回结果后模型会做一轮归纳比如按错误类型分类、统计条数、给出优先级建议。这里有个实测会踩的坑时间格式。start: 5m这种写法服务端不认会报invalid start time: unsupported time format: 5m。得用 RFC3339 格式比如2026-04-08T07:00:00Z或者用-5m这种带负号的相对时间。这个在下一节排错里细说。4.4 成功返回长什么样一次成功的查询返回结构大致是先列出命中的日志条数再按错误类型分布给个表格然后逐类分析原因最后给建议。比如 172 条日志里TRADE_MAX_ORDERS_ERROR占 91.9%LiqService清算异常占 5.2%模型会分别说明每类的含义和关注点。如果返回结果太大客户端会提示result exceeds maximum allowed tokens并把完整输出存到本地文件让你用jq或cat分段读。这是正常行为不是报错。5. 本篇常见错排查401、proxy failed、choices 报错配置过程中最容易卡在几个固定报错上我按实际遇到的顺序列出来。5.1 401 Unauthorized最常见。原因通常是 Key 没填对或者填到了错误的位置。检查三处客户端的 API Key 字段、环境变量ANTHROPIC_API_KEY、以及 MCP 服务端如果也走认证的话。注意 Key 前后不要有空格复制时容易带上。如果是 Claude Code确认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是成对出现的只改一个会认证失败。5.2 local proxy failed这个报错一般出现在客户端配置了本地代理但代理没起来或者 Base URL 写成了本地地址。检查你的 Base URL 是不是https://taotoken.net/api而不是http://localhost:xxxx。如果你本地跑了个转发服务确认它监听的端口和配置里写的一致。5.3 reading choices 报错这个通常出现在 OpenAI 兼容协议的客户端比如 Cursor上返回体里没有choices字段。原因可能是模型 ID 填错了或者请求打到了不兼容的端点。确认 Model ID 在 TaoToken 控制台里是存在的且客户端用的是 OpenAI 兼容格式。5.4 OAuth 相关报错有些客户端默认走 OAuth 流程如果你用的是 API Key 认证需要在配置里显式关掉 OAuth 或者选择 API Key 模式。Claude Code 里如果看到 OAuth 报错检查是不是ANTHROPIC_API_KEY没设导致它回退到了 OAuth。5.5 MCP 服务端连不上claude mcp get loki可以看注册状态。如果显示连不上先确认服务端进程在跑curl http://localhost:8080/healthz应该返回ok。Docker 环境下Loki 启动需要时间等 healthcheck 通过再连 MCP 服务端。5.6 时间戳显示 2262 年这是 Loki MCP Server 早期版本的一个已知 bug。Loki 返回的是纳秒时间戳如果代码里用time.Unix(ts, 0)把纳秒当秒处理就会显示成 2262 年。修复方式是time.Unix(0, int64(ts))第一个参数为 0 秒第二个参数为纳秒。如果你自己编译确认用的是修复后的版本。5.7 查询无结果先确认 Loki 在那个时间范围内确实有数据。用loki_label_names查一下有哪些标签可用再用loki_label_values确认标签值拼写正确。多租户场景下检查X-Scope-OrgID头有没有带上。6. 把链路固定下来接入文档与后续动作配置跑通之后建议把三件套写进项目的 README 或者团队 wiki避免下次换机器又要重新摸一遍。Base URL 固定用https://taotoken.net/apiKey 走环境变量注入不要硬编码进配置文件提交到仓库。如果你要长期跑编码和 Agent 任务可以考虑用 Coding Plan把模型调用额度固定下来避免临时 Key 额度不够。验证模型可用性的时候模型对话页面是最快的入口先在那里确认目标模型能正常返回再写进客户端配置。接入文档里有各客户端的详细字段说明遇到配置项不确定的时候翻一下比猜快。API Keys 页面用来管理 Key 的创建和吊销建议按用途分 Key方便排查问题时定位是哪个客户端出的错。最后留一个实用技巧MCP 服务端的/healthz端点可以接到你的监控里K8s 环境下配 readiness 和 liveness probe 都用它。服务端本身无状态可以水平扩展多个副本同时跑没问题。日志查询这种读多写少的场景加个副本数基本就够用了。