MaxCompute MCP

Core capabilities

• Catalog metadata browsing and search: Browse projects, schemas, tables, fields, and partitions hierarchically. Supports natural language search.

• Table management and metadata maintenance: Create tables (with options for lifecycle, primary key, and partial column updates), insert small amounts of data, and update table comments, tags, or column descriptions.

• Identity and permission checks: Check the current account's identity and use MaxCompute authorization information to troubleshoot access issues.

• Authentication and authorization:

  • Remote MCP uses Alibaba Cloud OAuth for authorization.

  • Local MCP supports AccessKey/SecretKey, Security Token Service, Credentials URI, ECS RAM Role, and the default Alibaba Cloud credential chain.

• Read-only SQL analysis: Cost estimation, asynchronous execution, instance status queries, and result retrieval. The server protects the read-only query path. Write and metadata modification capabilities are listed separately and require user confirmation.

• Information Schema operations and governance analysis:

  • Remote MCP includes a built-in Information Schema semantic pack.

  • Local MCP requires the corresponding Skill to be installed separately.

Architecture overview

MCMCP uses a layered architecture, from top to bottom:

• User Agent ecosystem: Supports multiple Agent clients including OpenClaw, DataWorks Agent, Qwen Code, QoderWork, and MaxAgent.

• MaxCompute Skills collection: A universal skill package for Agents, containing semantic packs, common commands, development templates, and usage limits. Extends Agent capabilities via MaxCompute OpenAPI, InfraAgent, and CatalogAI.

• MCMCP service: Wraps MaxCompute OpenAPI, StorageAPI, and CatalogAPI into structured tools directly callable by Agents.

• MaxCompute core capabilities:

  • Metadata:

    Catalog / Schema / Table / Partition. Features include authorization, auditing, data discovery, data exporting, masking, row-level permissions, and data sharing.

  • Compute Engines:

    MaxCompute SQL, MaxFrame, MC Spark. Compute types include heterogeneous CU/GU, AI functions, and models.

  • Storage:

    Table (Append / PK Delta Table); data types include BLOB, JSON, ARRAY, MAP, STRUCT. Features include automatic storage tiering, multi-replica, multi-AZ disaster recovery, recycle bin/Time Travel, data snapshots, and storage encryption.

Key use cases include:

• Storage pressure diagnosis

  • Capability: Identify top storage-consuming tables, detect partition bloat risks, and spot data freshness issues.

  • Prompt example: "Analyze the top 10 tables by storage usage in my tenant" or "Check which tables have partition bloat risks."

• Cost pressure diagnosis

  • Capability: Break down job costs by owner, project, or type; track CU-hour consumption and identify high-resource jobs.

  • Prompt example: "What were the most expensive jobs in the last week?" or "Rank users by resource consumption."

• Job failure surge analysis

  • Capability: Monitor failure rate trends and drill down by type, owner, or project to identify root causes.

  • Prompt example: "List failed jobs in the last 24 hours" or "Show failure rates by job type."

• Permission exposure audit

  • Capability: Audit table-level grants, identify high-risk admin accounts, and detect excessive permission risks.

  • Prompt example: "Which users have admin permissions?" or "Count tables granted to each user."

• Hot table monitoring

  • Capability: Identify hot tables based on access frequency and automatically discover zombie tables based on their last access time.

  • Prompt example: "Which tables are accessed most often?" or "Find zombie tables not accessed in the last 90 days."

• Metadata governance gap analysis

  • Capability: Measure table and column comment coverage to identify metadata gaps and governance weak points related to data freshness.

  • Prompt example: "What is the column comment coverage rate?" or "List tables without table comments."

• Job performance analysis

  • Capability: Analyze average and P99 job execution durations to identify long-tail slow jobs and abnormal queuing delays.

  • Prompt example: "Show the slowest P99 jobs" or "What was the average job duration last week?"

• Tunnel Audit

  • Capability: Track Tunnel upload and download volumes, trace download IP addresses from the public network and detect abnormal data transfer.

  • Prompt example: "Show Tunnel data volume in the last 24 hours" or "Audit public network download source IPs."

• User role audit

  • Capability: Review user-to-role mappings, audit the assignment of administrative roles, and identify inactive high-privilege accounts.

  • Prompt example: "List all admin and super_administrator users" or "Show user role assignments."

• Partition lifecycle analysis

  • Capability: Monitor partition count growth trends, verify lifecycle policy enforcement and check the cleanup status of expired partitions.

  • Prompt example: "Which tables have more than 500 partitions?" or "Find partitioned tables without lifecycle enabled."

• Quota resource monitoring

  • Capability: Monitor CPU and memory quota usage in real time, alerting on resource bottlenecks and imbalanced allocation.

  • Prompt example: "Show CPU usage for all Quotas" or "Which Quotas exceed their usage threshold?"

Browse projects and tables

Example:

List MaxCompute projects I can access, then show schemas in my_project
Show fields, partition keys, and table comments for user_info in my_project's default schema

Run SQL queries securely

Estimate cost before execution:

First show the structure of the orders table, then estimate the cost of this SQL:
SELECT COUNT(*) FROM orders WHERE dt='2026-05-01'

Run a read-only query:

Run this read-only query in my_project:
SELECT * FROM default.orders WHERE dt='2026-05-01' LIMIT 100

For large queries, use asynchronous execution:

Run this query asynchronously. After returning the instanceId, poll its status and read the first 100 rows when done

Export large results

Inline results are capped by row limits. For full results, use output_uri:

Run this query synchronously and write the full result to file:///tmp/maxcompute-result/orders.jsonl;
Only show me a preview and the final outputPath in the response

Check identity and permissions

Show the MaxCompute identity used by MCP and list my permissions in my_project

Search metadata

Search the Catalog for tables with names containing 'orders', limited to my_project

Governance and O&M analysis with Information Schema

Analyze the top 10 tables that consume the most storage in the current tenant.
What were the most computationally expensive jobs in the last week? Summarize by owner and project.

The Remote MCP has a built-in Information Schema semantic skill, so you can use these types of queries directly. For the Local MCP, you must first install the corresponding Skill in your client or agent environment to enable these scenarios.

Maintain business metadata

First read the current schema of default.orders, then update the table comment to 'Order fact table'
and change the buyer_id column comment to 'Buyer ID'

update_table supports these changes:

• Table comment: description

• Tags: labels

• Lifecycle: expiration.days, expiration.partitionDays

• Column comments: columns.setComments

• Change top-level columns from non-nullable to nullable: columns.setNullable

• Add new columns: columns.add

MaxCompute does not support deleting columns, changing column types, reordering columns, inserting columns in the middle, changing nullable columns to non-nullable, or modifying nullability of nested columns via this tool.

Create tables and insert small data sets

Create a test table demo_user in my_project.default
with fields id BIGINT, name STRING, and dt STRING as a partition key, with a 7-day lifecycle

Insert two test rows into demo_user with dt partition value 2026-05-18

These operations modify MaxCompute resources. Grant permissions only for test or controlled projects.

Remote vs. local MCP server

Use the Remote MCP Server by default. Use the Local MCP Server only for self-hosting, stdio integration, local development, or when you need direct control over credentials.

MCP client does not show tools

Check the following:

1. Is command set to uv? Does args include --directory pointing to the absolute path of the repo?

2. If the client cannot find uv, replace command with the absolute path returned by which uv.

3. Have you run uv sync in the repo?

4. Does MAXCOMPUTE_CATALOG_CONFIG point to the correct config.json?

5. Did you restart Cursor, Claude Code, or your MCP client?

6. Does manually running uv run alibabacloud-maxcompute-mcp-server --help in the repo directory succeed?

Authentication or connection failures

Check the following:

1. Does MAXCOMPUTE_ENDPOINT or maxcompute_endpoint match your project’s region?

2. Are your AK/SK or STS token valid and not expired?

3. If using a credentials service, can ALIBABA_CLOUD_CREDENTIALS_URI be accessed from the MCP server machine?

4. Has the current identity been granted access to the target project?

5. First verify your identity with check_access, then troubleshoot specific tools.

search_meta_data returns an error

Common causes:

• namespaceId or MAXCOMPUTE_NAMESPACE_ID is not configured.

• The query lacks type=TABLE, type=RESOURCE, or type=SCHEMA.

• The query uses incompatible project and region conditions.

SQL table name resolution fails

First call get_table_schema and have the Agent use the returned sqlTableRef.

• Three-layer model tables commonly use schema.table or project.schema.table;

• Two-layer model tables commonly use table or project.table.

SQL execution times out or results are truncated

• We recommend asynchronous execution by default. After obtaining the instanceId, use get_instance_status and

  get_instance to retrieve the results.

• For synchronous execution, set a timeout. If it times out, you can still use the returned instanceId to continue querying.

• For large results, use output_uri=file:///path/to/result.jsonl to write to a local file on the server.

• Before execution, call cost_sql, then use maxCU to limit resource consumption.

Other common errors

If the client displays the raw tool results, a failed response usually includes a request_id and an error code. Common handling methods are as follows: