Use MCP to connect to PolarDB Agentic Database-PolarDB(PolarDB)-阿里云帮助中心

This topic uses QoderWork as an example to show how to connect to PolarDB Agentic Database by completing the two-phase verification flow (OAuth identity authentication followed by instance provisioning). After the connection is established, your AI agent can call SQL tools through the MCP protocol to operate the Database directly. The entire process requires no manual configuration of Database addresses, accounts, or passwords.

Note

PolarDB Agentic Database is in public preview. To request access or report feedback on the current functionality, search for the following DingTalk group ID and join the discussion: 28000021116.

Background information

PolarDB Agentic Database MCP uses a two-phase verification mechanism to ensure that the user identity is trustworthy and the Database instance is under control. Both phases run end-to-end in a single browser session. You do not need to switch back and forth between pages.

Phase	Purpose	Output
Phase 1: OAuth identity authentication	Verifies your Alibaba Cloud identity.	User identity (aliuid).
Phase 2: Instance provisioning	Creates or assigns a PolarDB Agentic Database instance for you.	MCP token (used to call tools such as `run_sql`).

After both phases are complete, MCP clients such as QoderWork, Cursor, and Claude Desktop can use the MCP token to call SQL tools directly. Neither the AI agent nor you ever touch the Database address, account, or password during the process.

Applicable scope

An Alibaba Cloud account is registered and real-name verified.
The Alibaba Cloud account (root or RAM user) has the AliyunRAMFullAccess permission.
The latest version of the QoderWork client is downloaded and installed.
The MCP service for PolarDB Agentic Database is currently available only in the China (Hangzhou) region.

Step 1: Add an MCP Server

Method 1 (recommended): One-click quick access. The QoderWork client has already published a dedicated PolarDB Agentic Database connector in the official connector marketplace. Go to Connectors > Data & Storage and click PolarDB to complete OAuth identity authentication.
Note
If you cannot find the relevant option in the QoderWork client, upgrade to the latest version of the QoderWork client first.
Method 2: Connect through MCP. In any AI application client, manually fill in the Server type and Server address to add the MCP Server. When the client connects to the MCP Server for the first time, it has no token yet, so the server returns 401 Unauthorized together with the OAuth metadata endpoint, and the client automatically triggers a standard OAuth flow. No manual action is required from you. The following example uses the QoderWork client:
1. Open the Connectors module in QoderWork. In the upper-right corner, click Add and select Fill in Config Manually.
2. Set Server Type to Streamable HTTP, and specify the Server Name based on your business scenario.
3. In the Server URL field, enter the MCP Server URL of PolarDB Agentic Database: https://mcp-polardb.cn-hangzhou.aliyuncs.com/mcp/.
4. Click Add.

Step 2: Complete OAuth authentication

After you add the MCP Server, the QoderWork client opens your default browser and redirects you to the Alibaba Cloud sign-in page.

Note

Security note: PolarDB Agentic Database requests only the three OAuth scopes openid, aliuid, and profile. These scopes return only the unique identifier and basic profile of the Alibaba Cloud account. No permission to operate any cloud resource is requested.

Log on to Alibaba Cloud as the root account or as a RAM user with the AliyunRAMFullAccess permission.
On the authorization page, click Authorize.

After you log on, the MCP Server retrieves your identity information (UID) from Alibaba Cloud and completes Phase 1. The browser then automatically redirects to the Phase 2 instance provisioning page.

Step 3: Activate a PolarDB Agentic Database instance

After OAuth authentication is complete, the browser automatically opens the PolarDB Agentic Database activation page. The page displays your Alibaba Cloud Account UID and two instance options.

Edition	Use case	Billing	Data protection	Lifespan
Free trial	Explore the capabilities of PolarDB Agentic Database and perform functional verification.	Free.	Data security is not guaranteed. Do not store important data.	3 days, automatically renewed on activity.
Dedicated edition (coming soon)	Production workloads and formal business scenarios.	Charged at the PolarDB Agentic Database instance pricing.	Dedicated instance with full data isolation.	No expiration.

Free trial

On the activation page, click Enable for Free. The system performs the following actions:

Allocates a dedicated PolarDB Agentic Database instance to you from the pre-built free instance pool.
Automatically redirects you back to the QoderWork client after the allocation succeeds.
Makes the instance ready for use within approximately 10 seconds.

Dedicated edition

Note

The dedicated edition is currently unavailable. Use the free trial edition first.

On the activation page, click Enable Dedicated Edition. The system performs the following actions:

Creates a dedicated PolarDB Agentic Database instance under your Alibaba Cloud account.
Completes the Database setup, including account creation, Database creation, and network configuration.
Takes approximately 1 minute to finish.
Automatically redirects the browser back to the QoderWork client after the instance is created.

Note

Billing notice: A dedicated edition instance is a billable resource. Once activated, it is charged at the PolarDB Agentic Database instance pricing.

Activation complete

Regardless of which edition you choose, after activation the browser automatically redirects to the local port that the QoderWork client listens on, indicating a successful sign-in. The client receives the MCP token and shows a connected state. The two-phase verification is complete.

Step 4: Start using the service

After the two-phase verification is complete, the MCP Server has established a trusted channel to your PolarDB Agentic Database instance. You can now issue tasks in natural language directly from the chat window in QoderWork (or any AI client that supports MCP). The AI agent plans the steps, creates tables, and writes data on its own. You do not need to write any DDL or DML by hand.

Example: Research mainstream AI agent frameworks and save the comparison

In the QoderWork chat window, enter the following prompt:

Research mainstream AI agent development frameworks, including LangGraph, AutoGen, and CrewAI. Compile a comparison table and save it to the database with the following columns: framework name, publishing team, and key highlights.

The AI agent automatically completes the following steps without any intervention:
- Plans the table schema: Generates a CREATE TABLE statement based on the required columns, for example, agent_frameworks(name VARCHAR(64), team VARCHAR(64), highlight TEXT).
- Calls the run_sql tool: Runs the CREATE TABLE statement to create the table.
- Calls the run_sql tool again: Inserts the comparison data for the three frameworks row by row.
- Returns an execution summary: Reports that the table has been created, the number of rows written, and suggested follow-up queries.
Verify that the data was written to the database. You can ask the agent to run a query, for example:
```
Query all rows from the agent_frameworks table.
```
Or tell the agent to run the following SQL through the run_sql tool:
```
SELECT * FROM agent_frameworks;
```

More use cases

You can apply the same pattern ("issue a natural language task, and let the AI agent build the table and write the data") to any scenario that benefits from structured data capture, for example:

Technology selection research (compare the core features of multiple open source products).
Reading notes or paper summaries (record key takeaways by topic).
Lightweight business data, such as daily to-do lists, weekly report entries, and meeting minutes.

The core idea is to describe in natural language what data to save and which columns to include. The agent then creates the table, writes the data, and returns the results. All data stays in your PolarDB Agentic Database instance and can be queried again at any time through SQL or the AI agent.

Note

The prompts and queries shown above are examples only. The exact SQL statements, table schema, and execution order that the AI agent generates may vary by client and model version. Rely on the results returned by the agent as the source of truth.

Daily use

After two-phase verification is complete, the QoderWork client holds a valid MCP token. No further verification is required for subsequent use.

Security mechanisms

PolarDB Agentic Database provides multiple layers of built-in security:

Credential isolation: The Database address, account, and password are managed by the MCP Server with encryption. No connection information ever appears in the AI agent context.
Access control: Each user can operate only the instance bound to them and cannot access instances under other accounts.

Token management

Automatic refresh: When the MCP token expires, the client automatically refreshes it by using the refresh token. No user action is required.
Refresh failure: If the refresh token has also expired (the default validity period is 30 days), the client returns to the disconnected state. You must redo the two-phase verification.
Free trial renewal: The lease of a free trial instance is automatically extended by 3 days every time you run a SQL operation.

FAQ

Q: How long does the two-phase verification take?
A: The entire process for the free trial usually completes within 30 seconds. Most of the time is spent on the Alibaba Cloud sign-in page. The dedicated edition requires about 1 minute extra to create the dedicated instance.
Q: Can I skip the console provisioning page?
A: No. The provisioning page is a required step in the two-phase verification flow. You must explicitly select an instance edition and accept the billing terms.
Q: How is multi-user or multi-RAM-user access handled?
A: Each Alibaba Cloud RAM user must complete the two-phase verification independently and obtains a dedicated instance. RAM users under the same root account do not interfere with each other.
Q: Do I need to redo the full flow when a token expires?
A: Not necessarily. If the refresh token is still valid (the default validity period is 30 days), the client refreshes the token automatically. You need to redo the two-phase verification only when the refresh token has also expired.
Q: Can the data be recovered after a free trial instance is recycled?
A: No. Once a free trial instance is recycled, the Database and all its data are permanently deleted. Use the dedicated edition if you need to keep your data.

Troubleshooting

Symptom	Possible cause	Solution
The browser does not open automatically.	The client blocked the browser redirect.	Check the QoderWork client log, then copy the authorization URL and open it in a browser manually.
The Alibaba Cloud sign-in page reports an error.	An issue with the OAuth application configuration.	Contact your administrator to check the RAM OAuth application configuration, or report feedback through the DingTalk group (28000021116).
The provisioning page reports Free Quota Exhausted.	The free instance pool has insufficient resources.	Try again later, or choose the dedicated edition.
The client still shows as disconnected after activation.	The redirect callback failed.	Close the QoderWork client, reopen it, and try to connect again.
`run_sql` returns "Instance is being prepared".	The instance is being created (about 1 minute for the dedicated edition).	Wait a moment and try again.
`run_sql` returns "Not activated".	You have not completed Phase 2 instance provisioning.	Reconnect from the QoderWork client and complete the provisioning flow.