MaxCompute:MaxCompute MCP Service documentation

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: View the current account identity and use MaxCompute authorization information to troubleshoot access issues.

• Authentication and authorization:

  • The Remote MCP Server uses Alibaba Cloud OAuth for authorization.

  • The local MCP Server supports AccessKey/SecretKey (AK/SK), Security Token Service (STS), Credentials URI, ECS RAM Role, and the default Alibaba Cloud credential chain.

• Read-only SQL analysis: Estimate costs, run asynchronous jobs, query instance statuses, and retrieve results. The read-only query path is protected on the server side. Write and metadata modification capabilities are listed separately and require user confirmation.

• Quota discovery: View the list and details of MaxCompute Quotas available to the current account.

• Knowledge base search and Q&A: The Remote MCP Server has a built-in MaxCompute documentation knowledge base that supports keyword searches and natural language Q&A, and returns answers with citations.

• Skill discovery and reading: The Remote MCP Server has built-in MCP Skill resources. Clients can discover and retrieve Skill content using tools/list for scenarios such as Information Schema semantic analysis and feedback guidance.

• Information Schema O&M and governance analysis:

  • The Remote MCP Server has a built-in Information Schema semantic package.

  • The local MCP Server requires you to install the corresponding Skill.

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.

The main application scenarios are as follows:

• 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 find 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 administrator accounts, and detect over-granting.

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

• Hot table monitoring

  • Capability: Identify frequently accessed tables and automatically detect "zombie tables" based on 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 find metadata gaps and stale data.

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

• Job performance analysis

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

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

• Data tunnel audit

  • Capability: Track Tunnel upload and download volumes, trace public network download IPs, and detect abnormal transfers.

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

• User role audit

  • Capability: Map user-role relationships, review admin role assignments, 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 growth trends, verify lifecycle policy enforcement, and check expired partition cleanup.

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

• Quota resource monitoring

  • Capability: Monitor real-time CPU and memory quota usage and alert on bottlenecks or imbalanced allocations.

  • 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

View Quotas

List the MaxCompute Quotas available to my current account, and show the details of the default Quota.

Knowledge base search and Q&A

How do I use dynamic partitions for inserts in MaxCompute? Please search the documentation and provide an answer with citations.

What is the difference between a clustered table and a standard table in ODPS? In what scenarios is it appropriate to use a clustered table?

Use Information Schema for governance and O&M analysis

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

The Remote MCP Server has a built-in Information Schema semantic package, so you can use these types of questions directly. For the local MCP Server, you must first install the corresponding Skill in the client or Agent environment before you use 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.

Unsure whether to use Remote or Local

Use the Remote MCP Server. Use the local MCP Server only if you need self-hosting, stdio, local development, or 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 result, a failed response usually includes a request_id and an error code. Common solutions are as follows: