企业官网建设流程全解析

1. 为什么要把 Loki 查询接进 AI 客户端

Loki MCP Server 是一个用 Go 写的 MCP 服务端，它把 Grafana Loki 的日志查询能力包装成三个标准 MCP Tool，让 Claude Desktop、Claude Code、Cursor 这类客户端可以用自然语言代替手写 LogQL。你不再需要记住{app="xxx"} |= "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。缺一个就连不上。下面这张表先给你一个全局印象：

把这几项写在一个便签里，后面配置直接抄。

3. 可复制配置：Claude Desktop / Claude Code / Cursor 三端接入

这一节是重点，三个客户端的配置文件路径和字段都不一样，我逐个给出来。所有配置里的 Base URL 都指向 TaoToken，Key 换成你自己的。

3.1 Claude Desktop 配置

Claude Desktop 的 MCP 配置在claude_desktop_config.json里。macOS 路径是~/Library/Application Support/Claude/claude_desktop_config.json，Windows 是%APPDATA%\Claude\claude_desktop_config.json。

如果你用本地 Docker 跑 Loki MCP Server，配置长这样：

{ "mcpServers": { "loki": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "LOKI_URL=http://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_URL="https://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_URL=http://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 的场景，参考这张表：

服务端启动后监听 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 '{job="varlogs"}' '-1h' 'now' 50

第一条插入测试日志，第二条查询验证。如果返回了日志行，说明服务端到 Loki 这条链路是通的。

4.2 再验证客户端到模型

打开 Claude Code，输入/mcp看 Loki 有没有注册上。然后直接说人话：

loki 查看所有可用的标签名

正常的话，客户端会调用loki_label_names，返回一列标签名，像app、env、job、namespace、pod这些。这一步验证的是客户端能识别 MCP Tool 并触发调用。

4.3 完整自然语言检索

接着做一次真正的日志检索：

查询 app=my-app env=prod 的近 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/api，Key 走环境变量注入，不要硬编码进配置文件提交到仓库。

如果你要长期跑编码和 Agent 任务，可以考虑用 Coding Plan，把模型调用额度固定下来，避免临时 Key 额度不够。验证模型可用性的时候，模型对话页面是最快的入口，先在那里确认目标模型能正常返回，再写进客户端配置。

接入文档里有各客户端的详细字段说明，遇到配置项不确定的时候翻一下比猜快。API Keys 页面用来管理 Key 的创建和吊销，建议按用途分 Key，方便排查问题时定位是哪个客户端出的错。

最后留一个实用技巧：MCP 服务端的/healthz端点可以接到你的监控里，K8s 环境下配 readiness 和 liveness probe 都用它。服务端本身无状态，可以水平扩展，多个副本同时跑没问题。日志查询这种读多写少的场景，加个副本数基本就够用了。