通过MCP接入PolarDB Agentic Database实践教程-云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

本文以QoderWork客户端为例，介绍如何通过两阶段验证（OAuth身份认证 + 实例开通）接入PolarDB Agentic Database。完成接入后，AI Agent即可通过MCP协议直接调用SQL工具操作数据库，整个过程无需手动配置数据库地址、账号或密码。

说明

PolarDB Agentic Database目前处于公测阶段，如需使用该功能或对当前功能有任何疑问，可通过钉钉搜索群号入群咨询。钉钉群号：28000021116。

背景信息

PolarDB Agentic Database MCP采用两阶段验证机制，确保使用者身份可信、数据库实例可控。两个阶段在一次浏览器会话内连续完成，您无需在多个页面之间手动切换。

阶段	目的	完成后获得
Phase 1：OAuth身份认证	验证使用者的阿里云身份。	身份：阿里云账号 UID。
Phase 2：实例开通	为您创建或分配PolarDB Agentic Database实例。	MCP Token（可调用`run_sql`等工具）。

两个阶段完成后，MCP客户端（如QoderWork、Cursor、Claude Desktop等）即可通过MCP Token直接调用SQL工具，整个过程中AI Agent和使用者都不会接触到任何数据库地址、账号或密码。

适用范围

已注册阿里云账号并完成实名认证。
阿里云主账号或子账号需具有AliyunRAMFullAccess权限。
已下载并安装最新版QoderWork客户端。
当前PolarDB Agentic Database MCP服务仅在华东1（杭州）地域提供。

步骤一：添加MCP Server

方式一（推荐）：一键快捷接入，QoderWork客户端已在官方连接器市场中上架专属PolarDB Agentic Database连接器，您可直接在连接器 > 数据存储中单击PolarDB进行Oauth身份认证。
说明
若您在QoderWork客户端未找到相关配置，请更新先至最新版QoderWork客户端。
方式二：MCP方式接入，您可在各AI应用客户端中手动填写服务器类型与服务器地址以添加MCP Server。在首次连接MCP Server时，由于尚未获得Token，Server会返回401 Unauthorized，并向客户端提供OAuth元数据端点地址，客户端会自动发起标准OAuth流程，您无需手动操作。以QoderWork客户端为例：
1. 进入QoderWork的连接器模块，单击右上角的添加，选择手动添加配置。
2. 将服务器类型选择为Streamable HTTP，服务器名称请根据业务场景进行填写。
3. 在服务器地址输入框中填入PolarDB Agentic Database的MCP Server URL：https://mcp-polardb.cn-hangzhou.aliyuncs.com/mcp/。
4. 然后单击添加。

步骤二：完成OAuth身份认证

添加MCP Server后，QoderWork客户端会自动打开浏览器并跳转到阿里云登录页面。

说明

安全说明：PolarDB Agentic Database仅请求openid、aliuid和profile三个OAuth scope，只读取阿里云账号的唯一标识和基础信息，不获取任何云资源操作权限。

使用阿里云主账号或具有AliyunRAMFullAccess权限的子账号登录阿里云。
在授权页面，单击授权。

登录成功后，MCP Server从阿里云获取身份信息（UID），完成Phase 1。浏览器随后自动跳转到Phase 2的实例开通页面。

步骤三：开通PolarDB Agentic Database实例

OAuth认证完成后，浏览器自动跳转到PolarDB Agentic Database开通页面，页面上会显示您的阿里云账号 UID和两种实例选项。

版本	适用场景	计费	数据保障	有效期
免费体验版	快速体验PolarDB Agentic Database能力，进行功能验证。	免费。	不保证数据安全性，请勿存放重要数据。	3天，有操作时自动续期。
专属版（敬请期待）	生产环境使用，承载正式业务。	按PolarDB Agentic Database实例计费标准计费。	独享实例，数据完全隔离。	无限期。

免费体验版

在开通页面单击免费开通。系统行为：

从预建的免费实例池中为您分配一台独立的PolarDB Agentic Database实例。
分配成功后页面自动跳转回QoderWork客户端。
实例在约10秒内即可使用。

专属版

说明

专属版暂不支持开通，请您先使用免费体验版。

在开通页面单击开通专属版。系统行为：

在您的阿里云账号下创建一台独享的PolarDB Agentic Database实例。
自动完成数据库配置（包括创建账号、建库、网络配置）。
整个过程约1分钟。
实例创建完成后浏览器自动跳转回QoderWork客户端。

说明

计费提示：专属版实例为计费资源，开通后将按PolarDB Agentic Database实例的计费标准产生费用。

开通完成

无论选择哪种版本，开通成功后浏览器都会自动跳转到QoderWork客户端监听的本地端口，此时代表登录成功。客户端获得MCP Token并显示连接成功状态，两阶段验证全部完成。

步骤四：开始使用

完成两阶段验证后，MCP Server 已与您的 PolarDB Agentic Database 实例建立可信通道。您可直接在 QoderWork（或任意支持 MCP 的 AI 客户端）的聊天窗口中，用自然语言下达任务，AI Agent 会自主规划步骤、创建表、写入数据，全程无需您手动编写 DDL 或 DML。

示例：调研主流 AI Agent 框架并保存对比结果

在 QoderWork 聊天窗口输入以下提示词：

帮我调研主流 AI Agent 开发框架，包括 LangGraph、AutoGen、CrewAI 三款，整理为对比表并保存到数据库，字段包括框架名称、发布团队、核心亮点。

AI Agent 会自动完成以下步骤，无需您干预：
- 规划表结构：根据字段要求生成 CREATE TABLE 语句，例如 ai_agent_frameworks(name VARCHAR(64), team VARCHAR(64), highlight TEXT)。
- 调用 run_sql 工具：执行 CREATE TABLE 语句完成建表。
- 再次调用 run_sql 工具：将三款框架的对比数据逐行插入。
- 返回执行摘要：告知您表已创建、写入行数以及后续可继续使用的查询建议。
验证数据已成功入库。您可以让 Agent 继续执行查询，例如输入：
```
帮我查询 ai_agent_frameworks 表的所有记录。
```
或直接告诉 Agent 通过 run_sql 工具执行以下 SQL：
```
SELECT * FROM ai_agent_frameworks;
```

日常使用

两阶段验证完成后，QoderWork客户端已持有有效的MCP Token，后续使用无需再次验证。

安全机制

PolarDB Agentic Database内置多层安全保障：

凭证隔离：数据库地址、账号、密码由MCP Server加密托管，AI Agent上下文中不会出现任何连接信息。
访问控制：每个使用者只能操作自己绑定的实例，不能跨账号访问。

Token管理

自动续期：MCP Token过期后，客户端会自动使用Refresh Token续期，无需您干预。
续期失败：如果Refresh Token也过期（默认30天有效），客户端状态回退到未连接，需要重新完成两阶段验证。
免费版续期：每次执行SQL操作时，免费实例的租约会自动延长3天。

常见问题

Q：两阶段验证需要多长时间？
A：免费版整个过程通常在30秒内完成，其中大部分时间在阿里云登录页面。专属版因为需要创建独享实例，会额外等待约1分钟。
Q：可以跳过控制台开通页面吗？
A：不可以。开通页面是两阶段验证的必要环节，您需要明确选择实例版本并确认计费条款。
Q：多人或多子账号如何使用？
A：每个阿里云子账号需独立完成两阶段验证，各自获得独立的实例。同一主账号下的子账号互不干扰。
Q：Token失效后需要重新走完整流程吗？
A：不一定。如果Refresh Token仍然有效（默认30天），客户端会自动续期。只有Refresh Token也过期时，才需要重新走两阶段验证。
Q：免费版实例被回收后，数据还能恢复吗？
A：不能。免费版实例被回收后，数据库和所有数据会被永久删除。如需保留数据，请使用专属版。

故障排查

现象	可能原因	解决方法
浏览器未自动弹出。	客户端阻止了浏览器跳转。	检查QoderWork客户端日志，手动复制授权URL到浏览器打开。
阿里云登录页报错。	OAuth应用配置异常。	联系管理员检查RAM的OAuth应用配置，或通过钉钉群（28000021116）反馈。
开通页面提示免费名额已满。	免费实例池资源不足。	稍后重试，或选择专属版开通。
开通后客户端仍显示未连接。	跳转回调失败。	关闭QoderWork客户端后重新打开，重试连接。
`run_sql`返回“实例准备中”。	实例正在创建（专属版约1分钟）。	等待片刻后重试。
`run_sql`返回“未开通”。	您尚未完成Phase 2实例开通。	在QoderWork客户端中重新连接，完成实例开通流程。