通过MCP Server接入PolarDB PostgreSQL Agentic Database

背景信息

PolarDB PostgreSQL Agentic Database MCP Server采用API Key认证机制，确保使用者身份可信、操作范围可控。

API Key中内嵌了Agentic Database集群和租户信息，MCP Server在首次连接时自动完成三层校验（格式校验→Payload解析→远程验证），验证通过后创建Session，后续调用在该Session上下文中执行，AI Agent和使用者全程不接触任何数据库地址、账号或密码。

适用范围

• 已注册阿里云账号并完成实名认证。

• 已下载并安装支持MCP协议的客户端，例如Qoder、Hermes、Cursor、Claude Desktop/CLI等。

步骤一：获取API Key

1. 登录PolarDB控制台，在左侧导航栏选择PolarDB AI > AgenticDB 集群列表，进入AgenticDB集群列表页面。

2. 在页面顶部切换至PostgreSQL页签，选择已开通的AgenticDB集群，进入租户管理。

3. 单击创建API Key，系统将生成格式为pagc_key_xxx的密钥。

4. 请妥善保存API Key（仅创建时展示一次）。

步骤二：本地部署MCP Server

当前PolarDB PostgreSQL Agentic Database MCP Server未提供远端服务，需要在本地以HTTP模式部署运行。

MCP_TRANSPORT=http npx -y mcp-server-polardb-agentic

npm install -g mcp-server-polardb-agentic
MCP_TRANSPORT=http mcp-server-polardb-agentic

启动成功后，MCP Server监听在http://127.0.0.1:3000/mcp。

步骤三：在MCP客户端中配置连接

在客户端的MCP Server配置中添加以下条目（以JSON配置文件为例）：

{
  "mcpServers": {
    "polardb-agentic": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer pagc_key_xxxxx.yyyyy"
      }
    }
  }
}

将pagc_key_xxxxx.yyyyy替换为步骤一中获取的实际API Key。

操作示例

mcp_servers:
  polardb_agentic:
    url: http://127.0.0.1:3000/mcp
    headers:
      Authorization: Bearer pagc_key_xxxxx.yyyyy
    timeout: 180
    connect_timeout: 60
    request_timeout: 120
    read_timeout: 120
    tool_call_timeout: 120
    max_retries: 0
    retry: false

{
  "mcpServers": {
    "polardb-agentic": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer pagc_key_xxxxx.yyyyy"
      }
    }
  }
}

步骤四：验证连接

配置完成后，客户端显示连接成功状态即表示认证通过。您可以直接使用自然语言与AI Agent交互，例如：

• “列出我所有的项目”

• “在项目 my-app 中创建一个新分支”

• “查看 users 表的表结构”

• “执行 SELECT * FROM orders LIMIT 10”

功能概览

PolarDB PostgreSQL Agentic Database MCP Server提供以下工具能力。

日常使用

连接建立后，MCP客户端通过Session ID维持会话状态，后续使用无需再次认证。使用示例如下：

• 创建项目：“创建一个名为 my-app 的新项目，并建立 users 表包含 id、name、email 和 created_at 字段。”

• 查看Schema：“查看 my-app 项目中 users 表的完整结构。”

• 分支操作：“从 main 分支创建一个名为 feature-auth 的开发分支。”

• 对象存储：“将这份 CSV 数据上传到 Lakebase，然后从数据库中查询它。”

安全机制

常见问题

• Q：API Key过期后需要重新配置吗？

  A：是的。API Key过期后连接会返回401错误，需要在控制台重新创建API Key并更新客户端配置。

• Q：多人或多Agent如何使用？

  A：每个Agent使用独立的API Key连接，各自拥有独立的Session，互不干扰。同一租户下可创建多个API Key。

• Q：哪些操作需要人工确认？

  A：所有标记为破坏性的操作（delete_project、delete_branch、含DROP/DELETE/TRUNCATE的SQL、lakebase_delete_object）都不会自主执行，Agent会先向您确认。

• Q：可以限制Agent只执行只读操作吗？

  A：当前版本暂不支持只读模式配置，但Agent在执行写操作前会遵循确认机制。

• Q：支持哪些MCP客户端？

  A：支持所有实现了MCP Streamable HTTP协议的客户端，包括Qoder、Cursor、Claude Desktop、Windsurf等。

故障排查