SelectDB MCP 服务概述
SelectDB MCP 服务通过 Model Context Protocol (MCP) 将 AI Agent 连接到 SelectDB Cloud。把 MCP Connection URL 添加到支持的客户端后，你就可以用自然语言探索仓库元数据、运行只读 SQL、查询受治理的业务指标。
你可以从 Claude Code、Cursor、Visual Studio Code、Codex 等兼容 MCP 的客户端使用该服务，也可以通过 LiteLLM 等 MCP 网关进行路由。
查询路径
服务支持两条查询路径：
- 有语义模型：语义查询。Agent 发现受治理的指标和维度，然后由服务生成 SQL。
- 没有语义模型：SQL 查询。Agent 先发现数据库、表和列，再生成只读查询。
连接该服务不要求必须配置语义模型。新部署可能显示 no_models 状态，但依然可以提供元数据和只读 SQL 查询。
查询能力
接入后，你用自然语言提问，AI Agent 会自动调用匹配的 MCP 工具。
元数据发现
| 你想做什么 | 直接说 | 调用了哪个 Tool |
|---|---|---|
| 看有哪些数据库 | "列出所有数据库" | list_databases |
| 看库下有哪些表 | "列出 sales 库中的表" | list_tables |
| 看表结构 | "显示 orders 表的字段" | describe_table |
没有语义模型：SQL 查询
如果没有 healthy workspace 包含匹配请求的指标的语义模型，Agent 会先发现可用的表和列，再生成只读 SQL 语句并调用 execute_query。在这条路径下，结果质量取决于 Agent 对请求的理解和 SQL 生成是否准确。
| 你想做什么 | 直接说 | 调用了哪个 Tool |
|---|---|---|
| 查数据 | "显示 top 10 订单" | execute_query |
| 无匹配指标时的聚合分析 | "按状态统计订单数" | execute_query |
execute_query 仅允许只读 SQL：SELECT、SHOW、DESCRIBE 和 EXPLAIN。
有语义模型：语义查询
如果 healthy workspace 中的语义模型定义了匹配请求的指标，Agent 会优先走语义查询路径，而不是在生成的 SQL 里重新实现该指标。Agent 分三步完成指标查询：
list_metrics列出可用的指标及其描述。list_dimensions_for_metric列出可以对所选指标进行分组或过滤的维度。query_metric编译并执行语义查询。
语义模型管控指标的计算逻辑、维度、关系和过滤条件。因此结果的准确性和一致性取决于这些定义是否正确。定义错误或不完整时，即使查询成功，结果也可能不正确。
| 你想做什么 | 直接说 | 调用了哪个 Tool |
|---|---|---|
| 看有哪些指标 | "列出所有指标" | list_metrics |
| 查营收趋势 | "显示过去 7 天的营收，按天分组" | query_metric |
| 看可用维度 | "total_amount 可以按哪些维度分析？" | list_dimensions_for_metric |
| 检查服务状态 | "检查服务健康状态" | check_service_health |
指标工具都需要 workspace 参数。内置的 example workspace 只有在仓库管理员部署示例后才可用。
AI Agent 查询工作流
Agent 在每次对话中按以下流程工作：
- 调用
get_query_guide加载查询工作流。 - 调用
check_service_health验证 SelectDB Cloud 连接并发现 workspace 状态。 - 如果请求涉及数据库、表或列，使用元数据工具。
- 如果 healthy workspace 中存在匹配的指标，调用
list_metrics、list_dimensions_for_metric和query_metric。 - 如果没有语义模型或匹配指标，调用
list_databases、list_tables、describe_table和execute_query。
当存在匹配的语义指标时，Agent 使用 query_metric，而不是用裸 SQL 重新实现该指标。如果没有指标匹配，Agent 会先说明语义层未覆盖该请求，再使用只读 SQL。
安全与权限
- 每个请求都使用 MCP 客户端提供的仓库 SQL 用户凭证。查询以该仓库 SQL 用户的权限运行。
execute_query仅接受只读语句。- 普通仓库用户可以查询数据和查看已发布的语义模型。
- 仓库
admin用户通过 Semantic Web UI 管理工作区和语义模型。