GuanMCP 常见问题排查
本文只收录能够根据明确现象直接处理的问题。 文中的配置、字段和错误提示均来自现有 GuanMCP 实现。
连接与会话问题
Streamable HTTP 返回 401
按接入方式检查凭证：
- 成员使用个人 PAT 连接远程服务：请求头应为
X-Personal-Token: <本人 PAT>，确认令牌完整且有效， 并使用管理员提供的个人 PAT 接入地址。该方式无需额外配置Authorization，不能使用Authorization: Bearer <PAT>代替。 - 管理员统一身份映射接入：请求头应为
Authorization: Bearer <MCP 服务凭证>， 确认凭证与服务端MCP_ENTRYPOINT_TOKEN完全一致。不要把BI_APP_TOKEN填入客户端请求头。
个人 PAT 的完整配置示例见 成员各自接入。
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 服务或新建对话，让客户端重新执行初始化。
豆包工作伙伴 MCP 连通性问题
若豆包工作伙伴提示「GuanMCP 数据服务连接异常」「所有工具调用均失败」或「MCP 连通性不通过」，
例如 get_bi_capabilities、global_search 均报错，请先查看运行日志中的具体错误。
需由客户侧负责运维的人员，在 BI 所在服务器（如阿里云服务器）的网络管理处配置访问白名单， 将豆包工作伙伴的 MCP 出口 IP（含工作流、自定义智能体的智能体节点调用 MCP 时需额外放行的 IPv4 和 IPv6 网段） 作为允许访问的来源地址，并放行对外提供 MCP 服务的端口。 完整 IP 清单、配置位置和验证步骤见 豆包工作伙伴 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。