版本：26.x

SelectDB MCP 快速开始

把 AI Agent 接入 SelectDB MCP，验证连接，并完成第一次只读查询。开始之前，你不需要配置语义模型。

准备工作

开始之前，请确认你已具备：

MCP Connection URL：在 SelectDB Cloud 控制台打开你的仓库，点击 Connection 即可看到 MCP Connection URL。
仓库用户名和密码：仓库用户的用户名和密码。创建和管理仓库用户，请参见权限管理。
受支持的 MCP 客户端或网关：例如 Claude Code、Cursor、Visual Studio Code、Codex 或 LiteLLM。
如果你想查询自己的数据，需要能访问仓库中的至少一个数据库。

客户端或网关会以 Bearer Token 的形式发送你的仓库用户名和密码，格式如下：

Authorization: Bearer <username>:<password>

1. 配置你的 AI 客户端或网关

从下列客户端或网关中选择一种。把示例中的 URL 和凭证替换为你的 MCP Connection URL 和仓库凭证。

Claude Code

运行：

claude mcp add --transport http selectdb https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp \
  --header "Authorization: Bearer <username>:<password>"

添加完成后重启 Claude Code。

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "selectdb": {
      "url": "https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer <username>:<password>"
      }
    }
  }
}

保存文件后重载 Cursor 窗口。

Visual Studio Code

在工作区根目录创建 .vscode/mcp.json：

{
  "servers": {
    "selectdb": {
      "type": "http",
      "url": "https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <username>:<password>"
      }
    }
  }
}

打开命令面板，运行 MCP: List Servers，选择 selectdb 并启动连接。

Codex

把服务添加到 ~/.codex/config.toml，或使用受信任项目中的 .codex/config.toml：

[mcp_servers.selectdb]
url = "https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp"
http_headers = { Authorization = "Bearer <username>:<password>" }

保存配置后重启 Codex 客户端。在 Codex 终端界面中，使用 /mcp 查看已连接的服务。Codex CLI、IDE 扩展和桌面应用共享同一份 MCP 配置。

LiteLLM

当你希望通过集中式 AI 网关提供 SelectDB MCP 工具时，可以使用 LiteLLM Proxy。开始之前，请先安装 LiteLLM Proxy。

在 litellm-config.yaml 中添加：

mcp_servers:
  selectdb:
    transport: http
    url: https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp
    auth_type: bearer_token
    auth_value: "<username>:<password>"
    static_headers:
      Accept: application/json, text/event-stream

保存配置后重启 LiteLLM Proxy。

代理启动后，按照 LiteLLM Model Management 通过 /model/new 添加一个支持工具调用的模型。提供模型名称、提供商模型和提供商凭证。必须启用数据库存储，模型才能在重启后保留。

2. 验证连接

向 AI Agent 提问：

检查服务健康状态。

AI Agent 会调用 check_service_health，返回 SelectDB Cloud 连接状态和每个语义 workspace 的状态。如果返回结果中显示 SelectDB Cloud 已连接，说明客户端或网关已准备好查询仓库。

workspace 状态不决定 MCP 连接是否成功：

Workspace 状态	含义	接下来怎么做
`healthy`	语义模型已加载，指标可用。	查询指标，或使用元数据和只读 SQL。
`no_models`	尚未发布语义模型。这是正常的初始状态。	继续使用元数据和只读 SQL。
`not_ready`	存在模型文件，但无法加载。	继续使用元数据和 SQL，并请管理员修复模型。

3. 运行你的第一次查询

从元数据发现开始。这条路径不需要语义模型。

提问：

列出我可以访问的数据库。

从结果中选择一个数据库，然后提问：

列出 <database-name> 库中的表。

选择一张表，运行你的第一次只读数据查询：

描述 <database-name>.<table-name>，然后显示其中最多 10 行数据。

AI Agent 会依次调用 list_databases、list_tables、describe_table 和 execute_query。execute_query 工具只接受 SELECT、SHOW、DESCRIBE 和 EXPLAIN 语句。

当 AI Agent 返回了你的仓库用户能访问的表的元数据或数据行时，快速开始即完成。no_models 状态不会阻碍这条查询路径。

4. 可选：用 Semantic Web UI 部署示例

如果你想体验语义查询路径，仓库管理员可以部署内置的示例。这一步是可选的，不影响你用只读 SQL 查询现有仓库数据。

Semantic Web UI 是查看语义 workspace 和模型的可视化界面。仓库管理员还用它在其中管理工作区、编辑和发布模型，以及部署内置示例。

打开 Semantic Web UI 并部署示例：

在 MCP Connection URL 后面追加 /web 打开 Semantic Web UI。例如，打开 https://<warehouse-id>.<region>.aws.selectdb.cloud/mcp/web。
使用仓库 admin 用户名和密码登录。
点击 Deploy example。
等待后台部署完成。页面会检查部署状态，完成后自动跳转。
回到 AI Agent，让它再次检查服务健康状态。

部署会创建：

dw.orders、dw.users、dw.products 和 dw.dim_date 示例表。
example 语义 workspace。
orders.yaml、users.yaml、products.yaml 和 project.yaml 模型文件。
total_amount、order_count、avg_amount、unique_users 和 user_count 等指标。

example workspace 显示 healthy 后，提问：

列出 example workspace 中的所有指标。

然后运行一次语义查询：

显示过去 7 天各渠道的订单总金额。

AI Agent 会调用 list_metrics 查找指标，调用 list_dimensions_for_metric 查找分组字段，然后调用 query_metric 执行语义查询。

查询示例

以下示例使用 Deploy example 安装的示例数据和语义模型。

探索数据结构

你：列出所有数据库
AI：[调用 list_databases]
    dw

你：dw 库中有哪些表？
AI：[调用 list_tables]
    orders, users, products, dim_date

你：显示 orders 表的结构
AI：[调用 describe_table]
    Column      Type      Comment
    order_id    BIGINT    Order ID
    user_id     BIGINT    User ID
    amount      DECIMAL   Amount
    channel     VARCHAR   Channel
    status      VARCHAR   Status
    order_date  DATE      Order date

用只读 SQL 查询数据

你：显示最近一周各状态的订单数和总金额
AI：[调用 execute_query]
    status      count   total_amount
    completed   1234    567890.00
    pending     567     89012.00
    cancelled   89      12345.00

查询语义指标

你：列出所有可用的指标
AI：[调用 list_metrics]
    total_amount      Total order amount
    order_count       Order count
    avg_amount        Average order value
    unique_users      Distinct ordering users
    user_count        User count

你：显示过去 7 天各渠道的订单总金额
AI：[调用 list_dimensions_for_metric] -> channel
    [调用 query_metric]
    channel   total_amount
    Online    12345.00
    Offline   15678.00
    ...

语义查询对话

用户：2026 年 4 月各渠道的订单总金额是多少？

AI 思考：
  1. get_query_guide -> 获取指引
  2. check_service_health -> workspace "example" healthy, 5 metrics
  3. 涉及"总金额"和"渠道" -> 走语义层
  4. list_metrics(example) -> total_amount
  5. list_dimensions_for_metric(example, total_amount) -> channel
  6. query_metric(example, metrics=[total_amount], group_by=[channel],
                  where="order_date >= '2026-04-01' AND order_date < '2026-05-01'")

AI 回复：
  channel  total_amount
  WEB      1,096.00
  APP      2,396.00
  MINI       298.00

故障排查

连接报 401

确认 Authorization 请求头中携带的是你的仓库用户名和密码，用英文冒号拼接为 username:password 格式。

健康检查显示 `no_models`

连接成功，但没有可用的语义模型。你可以查询仓库元数据并运行只读 SQL。如果需要体验语义指标，请仓库管理员发布模型或部署内置示例。

语义查询报 "workspace not found"

确认 workspace 名称正确。example workspace 只有在仓库管理员部署内置示例后才存在。登录 Semantic Web UI 查看可用的 workspace。

AI Agent 能否执行写操作？

不能。execute_query 只允许 SELECT、SHOW、DESCRIBE 和 EXPLAIN 语句。

查询很慢

数据量大时，让 AI Agent 加上 LIMIT 或缩小时间范围。

语义层能用哪些指标？

让 AI Agent 列出所有指标，或登录 Semantic Web UI 查看每个 workspace 配置的指标。

下一步

概述：了解可用工具以及 AI Agent 如何在语义查询和只读 SQL 之间选择。
语义模型概念：了解实体、维度、度量和指标定义。
创建和管理语义模型：了解如何创建、校验、提交和发布受治理的业务指标。

准备工作​

1. 配置你的 AI 客户端或网关​

Claude Code​

Cursor​

Visual Studio Code​

Codex​

LiteLLM​

2. 验证连接​

3. 运行你的第一次查询​

4. 可选：用 Semantic Web UI 部署示例​

查询示例​

探索数据结构​

用只读 SQL 查询数据​

查询语义指标​

语义查询对话​

故障排查​

连接报 401​

健康检查显示 no_models​

语义查询报 "workspace not found"​

AI Agent 能否执行写操作？​

查询很慢​

语义层能用哪些指标？​

下一步​