Set up the remote MCMCP Server

Supported regions

Choose an endpoint based on your client's network environment.

Use the same endpoint domain for the initial connection, OAuth authorization, and all subsequent calls. Do not mix public and VPC domains during the authorization process.

Prerequisites

• Access to the endpoint domains listed above.

• An MCP client that supports MCP Streamable HTTP and browser-based OAuth authorization.

• An Alibaba Cloud account with access permissions for MaxCompute.

Limitations

• Permission scope: The projects, schemas, tables, and instances you can access are determined by your MaxCompute and RAM permissions.

• IP whitelist: The Remote MCP Server does not support connections to MaxCompute projects that have an IP whitelist configured. Tool calls to such projects may fail.

• Write operation confirmation: Users must explicitly confirm write operations in the client. The gateway does not offer a secondary confirmation prompt.

Client configuration

Although configuration fields differ between MCP clients, the principle is the same: set the MCP server URL to your chosen endpoint address. The example below uses a public endpoint. For a VPC environment, replace the URL with the corresponding VPC service address from the Supported regions table.

The general configuration format is as follows.

{
  "mcpServers": {
    "maxcompute-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp"
    }
  }
}

If your client uses field names like endpoint, server_url, or transport, follow your client's documentation. The URL should still be the service address from the table above, ending in /mcp.

claude mcp add --transport http --scope user maxcompute-mcp \
  https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp

claude mcp list
claude mcp login maxcompute-mcp

codex mcp add maxcompute-mcp \
  --url https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp

codex mcp list
codex mcp login maxcompute-mcp

[mcp_servers."maxcompute-mcp"]
url = "https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp"

qwen mcp add --transport http --scope user maxcompute-mcp \
  https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp

{
  "mcpServers": {
    "maxcompute-mcp": {
      "httpUrl": "https://mcp.cn-hangzhou.maxcompute.aliyun.com/mcp"
    }
  }
}

Initial connection and OAuth authorization

When you first connect, the MCP client automatically starts the OAuth authorization process and opens the Alibaba Cloud authorization page in your browser.

Verify connectivity

After authorization, verify the connection by following these steps.

1. First, list the available tools in your client:

   tools/list

2. Call the health check tool:

   {
     "name": "maxcompute_health_ping",
     "arguments": {}
   }

3. On success, the returned structuredContent should contain:

   {
     "ok": true,
     "data": {
       "pong": true
     }
   }

4. Next, list the MaxCompute projects visible to the current account:

   {
     "name": "maxcompute_schema_list_projects",
     "arguments": {
       "limit": 10
     }
   }

   If this step returns an empty list or a permission error, verify that your Alibaba Cloud account has the necessary permissions for the target MaxCompute project.

Tool capability list

You typically do not need to fill in tool parameters manually. Instead, you can describe your goal in natural language.

The following table lists the MaxCompute tools to illustrate the scope of capabilities. However, the definitive list of tools available to your client is returned by tools/list.

For 2-tier MaxCompute projects, you can typically omit the schema. For 3-tier models, you must pass the appropriate schema based on the target object or SQL execution context.

Common prompt examples

You can start with prompts like the ones below. The agent selects the appropriate MCP tool based on your intent.

• "Check if the MaxCompute MCP login was successful."

• "List the MaxCompute projects my current account can access."

• "Show the tables in the cn-shanghai region's project <project>, prioritizing tables with orders in their names."

• "Describe the columns, partitions, and comments for the table <project>.<table>."

• "Get the table creation DDL for <project>.<table>."

• "Help me validate if this SQL is a read-only query and estimate its execution cost: SELECT ...."

• "Execute this read-only SQL in the <project> project and return only the first 100 rows: SELECT ... LIMIT 100."

• "Check the running status of the SQL instance <instance_id>."

• "Read the results of the SQL instance <instance_id>, paginated by 100 rows."

• "Get the Logview for the SQL instance <instance_id>."

• "Cancel the SQL instance <instance_id>."

• "Check my identity and permissions for the <project> project, without expanding all authorization details."

Have the agent validate your SQL or explain the plan before you run queries that may consume significant resources.

Response format

Tool call results are returned in the structuredContent field. A successful result typically looks like this:

{
  "ok": true,
  "data": {},
  "error": null,
  "request_id": "...",
  "warnings": [],
  "citations": [],
  "metadata": {},
  "next_cursor": null
}

Troubleshooting

A failed operation typically returns ok: false with an error object. Common issues and solutions are listed below.

When troubleshooting, record the request_id, tool name, timestamp, and a sanitized error code. Do not record or share tokens, authorization codes, sensitive business data in SQL queries, sensitive account information, or any Logview content.

Security precautions

• Use a trusted client

  Configure and access production endpoints only through a trusted MCP client. Do not initiate MCP requests from untrusted pages.

• Complete OAuth authorization yourself

  You must complete the OAuth confirmation yourself.

• Use an account with the minimum required permissions

  Use an account that has only the permissions you need, as MCP access to MaxCompute resources is determined by account permissions.

• Do not disclose sensitive credentials

  Do not disclose access tokens, refresh tokens, authorization codes, secret keys, or callback URLs in chats, support tickets, documents, or screenshots.

• Explicitly confirm write operations

  Before execution, verify the target project, table, SQL, or a summary of the changes displayed in the client. Proceed only after confirming the details are correct.