GuanMCP 常见问题排查
本文只收录能够根据明确现象直接处理的问题。 文中的配置、字段和错误提示均来自现有 GuanMCP 实现。
连接与会话问题
Streamable HTTP 返回 401
将请求头配置为 Authorization: Bearer <MCP 服务凭证>，并确认凭证与服务端
MCP_ENTRYPOINT_TOKEN 完全一致。不要把 BI_APP_TOKEN 填入客户端请求头。
Streamable HTTP 返回 404 或 SSE 类型错误
如果先出现 Error POSTing to endpoint: Not Found，随后出现
Invalid content type, expected text/event-stream，请把 MCP 地址改为完整入口：
https://<GuanMCP 地址>/mcp
不要填写站点根地址、/healthz 或 /mcp/。
外部地址带自定义前缀时，网关需要把该前缀改写到后端 /mcp。
返回 mcp_session_not_found
服务端已经没有客户端携带的旧会话。 重新连接 MCP 服务或新建对话，让客户端重新执行初始化。
豆包工作伙伴无法连接私有化 GuanMCP
客户的观远 BI 和 GuanMCP 均为私有化部署。
若豆包工作伙伴无法连接 GuanMCP，请联系豆包工作伙伴（原飞书 Aily）技术支持，
检查 MCP 客户端 → 客户观远域名 的网络连通性。
工具与本地配置问题
本地 stdio 无法启动或看不到工具
使用 PAT 时，可以从以下最小配置开始：
{
"mcpServers": {
"guanbi": {
"command": "npx",
"args": ["-y", "@guandata/guanbi-mcp-server@latest"],
"env": {
"MCP_TRANSPORT": "stdio",
"BI_BASE_URL": "https://bi.example.com",
"BI_PUBLIC_PATH": "",
"BI_PAT": "<你的 PAT>"
}
}
}
}
保存后重新加载或重启 MCP 客户端，并确认：
- Node.js 不低于 20，客户端进程可以执行
npx。 BI_BASE_URL只填写 BI 站点根地址；子路径填写到BI_PUBLIC_PATH。- stdio 不配置远程
url、HTTP Header 或MCP_HTTP_*。
可以在终端执行以下命令确认包能启动：
npx -y @guandata/guanbi-mcp-server@latest --version
数据查询与消费问题
query_card_data 分页与大数据量消费
query_card_data 默认返回 100 行，单页最多返回 1000 行，并受 4 MiB 响应预算保护。
调用方按返回的 page 字段续页：
| 返回字段 | 处理方式 |
|---|---|
page.has_more=false | 分页结束。 |
page.has_more=true 且有 page.next_offset | 下一次调用把 offset 设置为 next_offset。 |
diagnostic.partial_reason=response_bytes | 当前页达到响应预算，使用 next_offset 继续。 |
diagnostic.partial_reason=backend_limit | 增加 filters 缩小范围，并从 offset=0 重新查询。 |
续页时只修改 offset，其他查询参数保持不变。
大数据量场景同时使用 filters 缩小范围、使用 columns 裁剪列，并逐页处理结果。
完整明细导出请使用观远 BI 的导出能力。
分页结果出现 � 或 ���
这是客户端或中间层按字节分片后分别解码 UTF-8 导致的。
修复客户端，使解码器跨分片保留状态；不要对每个分片单独调用 decode()。
JavaScript 示例：
const decoder = new TextDecoder("utf-8", { fatal: true });
let text = "";
for await (const chunk of responseBody) {
text += decoder.decode(chunk, { stream: true });
}
text += decoder.decode();
已经变成 � 的页面无法恢复原字符，应丢弃该页并在修复解码后重新请求。
降低 limit 只能临时改变分片位置，不能替代解码修复。
execute_sql_query 不可用或表名报错
execute_sql_query 要求 BI 数据版本不低于 8.2.0，并需要在「管理后台 > 高级设置 > 对应域名」
开启高级 SQL 查询。工具未显示时，先调用 get_bi_capabilities 查看 executeSqlQuery 能力。
SQL 中使用 get_dataset_detail 返回的数据集名称和字段名称。
中文、空格或其他特殊字符使用反引号。
inputs 只填写 SQL 引用的数据集 ID，不能把数据集 ID、字段 ID 或 input0 当作表名。
SELECT `城市`, SUM(`销售额`) AS `销售额合计`
FROM `销售明细数据集`
WHERE `城市` = '杭州'
GROUP BY `城市`
如果返回 TABLE_OR_VIEW_NOT_FOUND，并且
diagnostic.tableBindings[].sqlReference 提供了值，请保持 inputs 不变，将 SQL 的
FROM 或 JOIN 表引用改为该值。单数据集 Spark 查询可能返回固定引用 __THIS__。
返回行数由 GuanMCP 的 BI_MAX_ROWS 控制，通常不需要自行添加 LIMIT。