FAQ

Mon, 01 Jan 0001 00:00:00 +0000

快速开始 FAQ#

应该优先选择哪种运行模式？#

建议按以下优先级判断：

streamable-http: 更现代的 MCP 传输方式，生产环境优先
sse: 兼容性最好，适合快速接入和广泛客户端适配

如果没有明确约束，先用 sse 验证链路，再迁移到 streamable-http。

为什么会返回 `401 unauthorized`？#

按顺序排查：

运行时是否启用了 MCP_AUTH_ENABLED=true。
MCP_AUTH_MODE 是否为 apikey、bearer、basic 之一。
apikey 模式下 MCP_AUTH_API_KEY 是否非空且与请求一致。
请求是否通过 X-Api-Key 头或 api_key 查询参数携带密钥。
修改配置后是否重启了进程或容器。

两种方式都支持，生产环境建议优先使用 Header：

1
2
3


curl -sS -N \
 -H "X-Api-Key: ChangeMe-Strong-Key-123!" \
 http://127.0.0.1:8080/api/aggregate/sse

Query 参数建议只用于本地快速验证。

如何减少返回内容，避免模型上下文过大？#

优先调用摘要类工具，再决定是否拉取明细。
大结果集优先使用分页能力。
通过 MCP_DISABLED_SERVICES 禁用暂不需要的服务。
配置限流，避免突发请求堆积。

可以只启用部分服务吗？#

可以，示例如下：

故障排除

Mon, 01 Jan 0001 00:00:00 +0000

故障排除#

当安装或运行出现异常时，可按本页步骤快速定位问题。

1. 服务无法启动#

先排查端口占用和启动日志：

1
2
3
4
5


# 查看 8080 端口占用
ss -lntp | rg 8080

# 以 debug 日志启动
./cloud-native-mcp-server --mode=sse --addr=127.0.0.1:8080 --log-level=debug

如果使用 Docker：

1

docker logs --tail=200 cloud-native-mcp-server

2. `/health` 无法访问或非 200#

1

curl -sv http://127.0.0.1:8080/health

若连接失败，请确认：

进程/容器是否正常运行
监听地址与端口映射是否正确
防火墙或安全组策略是否放行

3. SSE 能连接但握手异常#

1
2
3


curl -svN --connect-timeout 5 --max-time 15 \
 -H "Accept: text/event-stream" \
 "http://127.0.0.1:8080/api/aggregate/sse"

再执行内置自检：

快速开始 on 云原生 MCP 服务器

FAQ

快速开始 FAQ#

应该优先选择哪种运行模式？#

为什么会返回 `401 unauthorized`？#

API Key 应该放在 Header 还是 Query？#

如何减少返回内容，避免模型上下文过大？#

可以只启用部分服务吗？#

故障排除

故障排除#

1. 服务无法启动#

2. `/health` 无法访问或非 200#

3. SSE 能连接但握手异常#

快速开始 on 云原生 MCP 服务器

FAQ

快速开始 FAQ#

应该优先选择哪种运行模式？#

为什么会返回 401 unauthorized？#

API Key 应该放在 Header 还是 Query？#

如何减少返回内容，避免模型上下文过大？#

可以只启用部分服务吗？#

故障排除

故障排除#

1. 服务无法启动#

2. /health 无法访问或非 200#

3. SSE 能连接但握手异常#

为什么会返回 `401 unauthorized`？#

2. `/health` 无法访问或非 200#