MCP 常见问题

端点为什么返回 404？

按以下顺序检查：

1. 模块的 EnableMcpServer 是否为 true。
2. 模块程序集是否成功扫描和注册。
3. 启动日志中是否出现 MCP 服务或路由注册失败。
4. 地址是否使用完整模块路由，例如： http://localhost:5000/mcp-senparc-xncf-mcp/sse。
5. 是否误用了旧地址 /sse/sse。

浏览器打开端点为什么一直加载？

SSE 是长连接。持续等待事件不等于失败。请使用 MCP 客户端完成“连接、列出 工具、调用无副作用工具”的完整验证。

为什么服务已注册但没有工具？

• 工具类型需要 [McpServerToolType]。
• 工具方法需要 [McpServerTool]。
• 默认只扫描模块 Register 所在程序集。
• 查看启动输出中是否有“未检测到 MCP Tool Type”提示。

为什么配置了 McpAccessToken 仍然没有 401？

当前自动映射的 MapMcp(routePattern) 路径没有启用该 token 的查询参数校验。 旧文档中的 ?token=... 示例不能证明认证已生效。请在反向代理或应用授权层 实现并测试真实认证，不要直接公开默认端点。

NuGet 显示 0.4.0-preview3，模块页为什么显示 0.1.0？

.csproj 的 <Version> 是 NuGet 包版本；Register.Version 是 XNCF 模块 生命周期版本。两者当前没有强制保持相同，排障时应同时提供。

MCP 调用为什么无法使用 AI 模型？

MCP Server 工具注册和 AI 模型配置是两条不同链路。使用 MCP Manager 的 AI 调用功能前，还需要在 AIKernel 中配置可用的聊天模型、凭据和网络访问。

生产环境最低要求是什么？

• HTTPS；
• 身份认证和按工具授权；
• 工具白名单与最小权限；
• 限流、超时、取消和幂等性；
• 调用审计及敏感数据脱敏；
• 高风险操作的人工批准或等价门控。