通过MCP Server接入PolarDB PostgreSQL Agentic Database

背景信息

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

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

适用范围

• 已创建创建PolarDB PostgreSQL Agentic Database集群，并获取API Key（pagc_key_xxx）。

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

步骤一：获取 API Key

1. 登录PolarDB控制台。

2. 在左侧导航栏，选择AgenticDB 集群列表 > PostgreSQL，进入AgenticDB 集群列表页面。

3. 选择已开通的AgenticDB 集群，进入配置与管理 > API Key 管理页面。

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

步骤二：配置本地 MCP 工具

配置 MCP Server 前，请满足以下条件：

• Node.js >= 20.0.0。

• 已获取阿里云 AccessKey ID 和 AccessKey Secret（用于调用 PolarDB OpenAPI）。

在客户端的 MCP Server 配置中添加以下条目。以下示例使用 JSON 配置文件：

{
  "mcpServers": {
    "polardb-agentic": {
      "command": "npx",
      "args": ["-y", "mcp-server-polardb-agentic@latest"],
      "env": {
        "POLARDB_ACCESS_KEY_ID": "<your-accesskey-id>",
        "POLARDB_ACCESS_KEY_SECRET": "<your-accesskey-secret>",
        "POLARDB_AGENTIC_API_KEY": "pagc_key_xxx"
      }
    }
  }
}

将配置中的 pagc_key_xxx 替换为步骤一获取的实际 API Key，并将 your-accesskey-id 和 your-accesskey-secret 分别替换为已获取的 AccessKey ID 和 AccessKey Secret。添加后，客户端会自动发起连接。MCP Server 将校验 API Key 并建立 Session。

{
  "mcpServers": {
    "polardb-agentic": {
      "command": "npx",
      "args": ["-y", "mcp-server-polardb-agentic@latest"],
      "env": {
        "POLARDB_ACCESS_KEY_ID": "<your-accesskey-id>",
        "POLARDB_ACCESS_KEY_SECRET": "<your-accesskey-secret>",
        "POLARDB_AGENTIC_API_KEY": "pagc_key_xxx"
      }
    }
  }
}

{
  "mcpServers": {
    "polardb-agentic": {
      "command": "npx",
      "args": ["-y", "mcp-server-polardb-agentic@latest"],
      "env": {
        "POLARDB_ACCESS_KEY_ID": "<your-accesskey-id>",
        "POLARDB_ACCESS_KEY_SECRET": "<your-accesskey-secret>",
        "POLARDB_AGENTIC_API_KEY": "pagc_key_xxx"
      }
    }
  }
}

mcp_servers:
  polardb_agentic:
    command: "npx"
    args: ["-y", "mcp-server-polardb-agentic@latest"]
    env:
      POLARDB_ACCESS_KEY_ID: "<your-accesskey-id>"
      POLARDB_ACCESS_KEY_SECRET: "<your-accesskey-secret>"
      POLARDB_AGENTIC_API_KEY: "pagc_key_xxx"

步骤三：验证连接

配置完成后，客户端显示连接成功状态即表示认证通过。您可以直接使用自然语言与 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 stdio 协议的客户端，包括 Qoder、Cursor、Claude Desktop 和 Windsurf 等。

故障排查