MCP 故障排查
MCP 服务器未在客户端中列出
现象： AI 客户端没有显示数据墙DBW 的 MCP 工具，或服务器未出现在列表。
排查步骤：
- 确认
dab-config.json中runtime.mcp.enabled为true（默认启用）。 - 客户端配置文件中是否正确注册了数据墙DBW 作为 MCP 服务器。
- Stdio 模式：确认
dab命令在客户端环境中可执行（which dab/where dab）。 - HTTP 模式：确认数据墙DBW 正在运行且
mcp端点可访问——curl http://localhost:5000/mcp。
工具调用返回权限错误
现象： AI 代理调用 MCP 工具时返回 permission denied / unauthorized。
排查步骤：
- 检查实体的
permissions——当前角色是否包含所需操作。Stdio 模式默认anonymous。 - 如果实体只配置了
authenticated的权限，anonymous角色无法使用。 - 实体级
mcp.dml-tools是否为false——设为false的实体对代理完全不可见。 - 全局
dml-tools中对应的工具是否被关闭（如"delete-record": false）。
代理看不到实体描述
现象： AI 代理无法正确理解数据结构，或因为缺少上下文生成错误的工具调用。
原因： 配置中没有设置实体和字段的 description。代理只能看到技术名称，无法理解业务含义。
解决：
- 为每个实体添加
--description。 - 为关键字段添加
--fields.name xxx --fields.description "..."。 - 为存储过程参数添加
--parameters.description "..."。 - 描述应包含业务含义、单位、格式等上下文信息。
Stdio 模式启动失败
现象： dab start --mcp-stdio 启动失败，错误信息为 Failed to start the engine in MCP stdio mode。
排查步骤：
- 运行
dab validate确认配置文件无错误。 - 确认数据库连接可达。
- 确认
runtime.mcp.enabled为true。 - 确认需要的实体至少有一个配置了当前角色的权限。
Stdio 模式输出乱码
现象： MCP 客户端报 JSON 解析错误。
原因： Stdio 模式下 stdout 只能输出 MCP JSON 消息。日志输出或其他文本混入会导致客户端解析失败。
解决：
- 添加
--LogLevel Error减少日志输出。 - 不要直接在
dab start前执行echo等输出命令（比如在脚本中）。 - 确认没有启动脚本向 stdout 输出非 MCP 内容。
工具列表不完整
现象： 代理看到的工具比预期的少。
排查步骤：
- 全局
dml-tools中某些工具是否被设为false。 - 所有实体的
mcp.dml-tools是否为true（默认），某些实体可能被单独关闭。 - 当前角色在某些实体上可能没有对应操作的权限——只有可执行的实体才出现在工具中。
- 存储过程实体需要配置
mcp.custom-tool: true才会以命名工具形式出现。
聚合查询超时
现象： AI 代理调用聚合工具时返回超时错误。
解决：
- 调高 MCP 聚合超时：
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 120。 - 确认数据库连接字符串超时也足够大——MCP 聚合超时和数据库超时取更短者。
- 优化聚合查询——确保统计字段有索引。
execute_entity 工具不可用
现象： execute_entity 工具不在 tools/list 中。
排查步骤：
- 确认有存储过程实体配置了
execute权限。 - 确认当前角色有
execute权限。 - 确认
dml-tools.execute-entity全局未被设为false。 - 确认数据库类型支持存储过程（仅 SQL Server）。
自定义工具未出现
现象： 配置了 mcp.custom-tool: true 的存储过程未以命名工具出现。
排查步骤：
mcp.custom-tool仅对存储过程有效——表或视图上设置会导致配置错误。- 确认实体类型为
stored-procedure。 - 确认命名转换——PascalCase 实体名在 MCP 中显示为 snake_case（
GetBookById→get_book_by_id）。