MaxCompute:MaxCompute MCP service

Core capabilities

• Catalog metadata browsing and search: Browse projects, schemas, tables, fields, and partitions hierarchically. Natural language search is supported.

• 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:

  • Remote MCP uses Alibaba Cloud OAuth for authorization.

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

• Server-side client registration (Client ID Metadata Documents, CIMD):

  In environments where this feature is enabled, server-side or self-hosted clients can use an HTTPS metadata document URL as the client_id to bypass Dynamic Client Registration (DCR). However, explicit consent is still required on the authorization confirmation page after you log in. For more information, see Configure server-side clients (Client ID Metadata Documents).

• SQL analysis and execution:

  Supports statement validation, estimation of scanned data volume and Compute Unit (CU) usage, execution of read-only or write SQL queries, instance status queries, and result retrieval. Write SQL queries and metadata changes require user confirmation.

• Intelligent analysis:

  Generates read-only SQL drafts from natural language, diagnoses job issues, and analyzes compute quota usage. The results indicate the scope of evidence and provide recommended actions.

• Table metadata analysis:

  Checks table structures and partition metadata without scanning table data.

• SemanticSpec management:

  Create and maintain SemanticSpec drafts that describe data semantics, view published versions, and use DataScan to generate and apply recommendations based on semantic discovery.

• Knowledge base search and Q&A:

  Remote MCP includes 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: Remote MCP includes built-in MCP Skill resources. Clients can use tools/list to discover and read Skill content for scenarios such as Information Schema semantic analysis and feedback guidance.

• Information Schema O&M and governance analysis:

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

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

• Multilingual tool information: Remote MCP provides tool titles and descriptions in Simplified Chinese, Traditional Chinese, and English in the tools/list output, and indicates whether a tool depends on a model.

Architecture overview

MCMCP has a layered architecture with the following layers from top to bottom:

• User agent ecosystem: Supports connections from MCP clients such as Claude Code, Codex, Qwen Code, Cursor, and Qoder.

• MaxCompute Skills collection: agents can complete more complex tasks by using a combination of semantic packages, common commands, development templates, and usage limits.

• MCMCP service: Wraps capabilities such as MaxCompute OpenAPI, StorageAPI, and CatalogAPI into MCP tools.

• Underlying MaxCompute capabilities: Covers product capabilities such as metadata, Compute Engines, and storage.

Tool list display information

• Multilingual tool display information

  Remote MCP provides multilingual display information for each tool object in the tools/list response. Clients that support this extension can read _meta["com.aliyun.maxcompute/display"] and show the title and description in Simplified Chinese (zh-CN), Traditional Chinese (zh-TW), or English (en) based on the interface language.

  Clients should rely on the tool set returned by each tools/list call and not maintain a separate tool catalog. If the selected language is missing or the extension version is unsupported, fall back to the standard title, name, and description fields. To indicate a model dependency, mark a tool as MaxAgent-backed only when _meta["com.aliyun.maxcompute/model_backed"] is true. The display information is for UI presentation only and must not be used for permission, billing, or security decisions.

• Intelligent analysis capabilities

  Natural language SQL, job diagnosis, and quota analysis are the three intelligent analysis tools of Remote MCP. All are read-only. They do not automatically execute the generated SQL, rerun or cancel jobs, or modify quota capacity and scheduling configurations.

  Model analysis may consume MaxAgent Credits, and a single tool call may trigger multiple model calls. When model capabilities or required evidence are unavailable, the tool may return a partial result. Use the warnings and missing_evidence fields to assess what conclusions you can trust.

Prerequisites for intelligent analysis

• The MCP client is connected to Remote MCP through browser-based OAuth or the local launcher.

• The current authenticated identity has the required permissions for the target MaxCompute project, job, or quota.

• The region in the request matches the region where the target resources are located.

• When you use MaxAgent model capabilities, the current identity has a valid MaxAgent quota and sufficient MaxAgent Credits in the selected region.

• To query tenant metadata or historical jobs by using the Generate SQL tool, the current identity must meet the Information Schema requirements.

• If you need historical quota capacity utilization or job consumption data, the corresponding historical observation capabilities must be available in the target service region.

Typically, you just need to state your goal in the conversation, and the Agent selects the tool and populates its parameters. You can also call the MCP tool directly by using the JSON examples in this topic.

Intelligent analysis results

All three tools return structured MCP results. Pay close attention to the following fields:

• ok: Indicates whether the tool call protocol completed successfully. ok=true does not guarantee that the evidence is complete.

• data: Contains business data, such as SQL drafts, diagnostic results, or quota observations.

• meta.outcome or metadata.outcome: The status of the business result.

• warnings: Describes non-fatal limitations, degradations, or fallback behaviors.

• missing_evidence: Lists any evidence that could not be obtained and the reasons why.

• usage: Shows the number of model calls and the token usage reported by the model.

Common outcome values:

Do not treat a partial outcome as a failed API call. Use the missing_evidence field to determine what questions the current conclusions can answer and whether you need to supplement permissions, scope, or perform deeper diagnosis. When troubleshooting, do not copy authentication information or full backend responses.

Generate SQL

In sales_dw.dwd in the China (Shanghai) region, generate an SQL query to count the number of paid orders and the total payment amount for each channel over the last 30 days, sorted by payment amount in descending order. Only generate and validate the SQL, do not execute it yet.

{
  "question": "Count the number of paid orders and the total payment amount for each channel over the last 30 days, sorted by payment amount in descending order",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "sales_dw",
      "schema": "dwd"
    }
  ],
  "analysis_context": {
    "project": "sales_dw",
    "schema": "dwd"
  }
}

{
  "question": "Find the team with the highest points in each race and calculate their cumulative season points",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "analytics",
      "schema": "formula_1",
      "tables": ["constructors", "constructorresults", "races"]
    }
  ]
}

{
  "question": "Query the 20 jobs with the highest CU consumption in the last 7 days. Return the instance ID, project, submitter, and CU hours",
  "region": "cn-shanghai",
  "analysis_context": {
    "project": "<A project where the current identity can create query instances in this region>"
  }
}

Job diagnosis

{
  "instance_id": "<INSTANCE_ID>",
  "project": "sales_dw",
  "region": "cn-shanghai",
  "depth": "standard"
}

Diagnose job <INSTANCE_ID> in sales_dw. First, identify the failed stage and the most likely cause. 
Provide actionable recommendations for a fix. Do not rerun or cancel the job.

Perform a deep dive on this job. The initial analysis did not explain the root cause. 
Check the available logs from failed workers and stage evidence. 
Distinguish between confirmed facts, inferences, and missing evidence.

Quota analysis

{
  "region": "cn-shanghai",
  "quota_nickname": "team_etl_quota",
  "question": "Analyze the 10 jobs with the highest CPU usage in the last 7 days and describe any verifiable abnormal signals"
}

Analyze team_etl_quota in cn-shanghai. Find the jobs with the highest CPU consumption in the last 7 days. Attribute a job as abnormal only if there are direct abnormal signals for the job. Otherwise, state that the cause is unknown. Provide only recommendations. Do not modify quotas or jobs.

{
  "region": "cn-shanghai",
  "question": "Compare compute quotas with active jobs in the last 7 days, sorted by job CPU usage. List capacity utilization separately for Subscription quotas, but do not calculate capacity percentages for Pay-As-You-Go and Spot quotas"
}

Compare my compute quotas in cn-shanghai that had active jobs in the last 7 days, including Subscription, Pay-As-You-Go, and Spot.
Sort them by job CPU usage and list high-consumption jobs. Add capacity utilization only for Subscription quotas.

Information Schema requirements

Generate SQL can use tenant-level Information Schema views. Quota analysis for capacity utilization and job evidence does not use Information Schema. Generate SQL only allows views that are on the server-side allowlist, such as:

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS_HISTORY

When Generate SQL uses these views, it must meet the following conditions:

1. The current authenticated identity must have read permissions for the tenant-level Information Schema. Root accounts usually have this access by default. Access for RAM users or RAM roles depends on the configuration set by the tenant administrator.

2. The current identity must have at least one visible MaxCompute project in the target region. This project is used to submit read-only Information Schema SQL queries. The identity must also have the permissions required to create query instances.

3. The target region must provide the tenant-level views mentioned above and their backend dependencies.

Security and scope limitations:

• Generate SQL reads tenant-level views recorded by built-in Skills, but it cannot query unknown system views or mix queries with physical tables.

• Before the model selects a system view, Generate SQL loads the root Skill of the Information Schema. It uses the view's data granularity, timeliness, and columns to determine the required source of facts. After a view is selected, Generate SQL loads the complete column documentation for that view.

• System view drafts for Generate SQL must include a time range and a LIMIT clause.

• Queries are always read-only. They do not modify quotas, scheduling configurations, or jobs.

Use cases for intelligent analysis tools

1. Use maxcompute_generate_sql to generate and validate the SQL for channel revenue over the last 30 days.
2. After reviewing and confirming the SQL, use maxcompute_sql_execute to run execute_args.
3. If the job fails or slows down significantly, use maxcompute_diagnose_job to analyze the instance.

1. Omit quota_nickname and use maxcompute_analyze_quota_usage to find compute quotas that have had jobs in the last 7 days.
2. Find high-consumption jobs based on actual job consumption. Check capacity utilization only for Subscription quotas.
3. Call maxcompute_diagnose_job for instances with abnormal signals.
4. Optimize the SQL or scheduling based on job evidence. Do not automatically scale up based only on historical consumption.

Analyze the owner distribution and CPU consumption of failed jobs for team_etl_quota over the last 7 days.
Investigate the cause for the failed instance with the highest CPU consumption.

Recommendations for using the intelligent analysis tool

• Provide only the scope fields supported by the current tool. For SQL generation, use region, sources, and the optional analysis_context. For job diagnostics, use the project and Instance ID or a Logview URL. For quota analysis, use region and the exact quota nickname. Do not include context fields from other tools in the current call.

• To generate SQL for a known data scope, provide sources. This avoids a broad discovery process that might yield zero candidates or multiple ambiguous datasets.

• For job diagnostics, use standard first. Use deep only when the results are inconclusive or when further investigation is required.

• For quota analysis, first compare the returned job consumption data. Then, investigate a few high-demand quotas and instances in detail. Do not treat partial results as a complete list.

• Always distinguish between confirmed facts, model judgments, and missing_evidence.

• Users must separately confirm any scaling, scheduling, migration, SQL execution, rerun, or cancellation operations.

General calling rules

• Tools can access only the MaxCompute resources that the current identity is authorized to access. Do not equate tool visibility with resource authorization.

• After discovering candidate tables, read the accurate table structure before generating or executing SQL. Do not guess columns, partitions, or the schema based on the table name.

• The client must obtain explicit user confirmation before performing write operations. These operations include writing SQL, creating tables, inserting data, updating metadata, and modifying SemanticSpec. The gateway does not perform interactive secondary confirmation for the client.

• For large result sets, use pagination, narrow the query scope, or read from an asynchronous instance. Local MCP can also write to a file using the local file://output_uri. This path refers to the machine where Local MCP is located, not the MCP client machine.

• The execution_mode for maxcompute_sql_execute defaults to wlm. When using MaxQA (MCQA v2), explicitly pass execution_mode=maxqa and the interactive quota_name. Do not pass settings.odps.task.wlm.quota at the same time. For subsequent status, result, or cancellation calls, pass only the project and instance_id. Do not pass or save the server-side MaxQA connection or cookie.

MCP client cannot find tools

• For direct browser-based OAuth connections, ensure that the Remote MCP service endpoint includes /mcp and that the same client configuration does not mix public network and VPC endpoints.

• Ensure that the client used for the browser OAuth direct connection supports Streamable HTTP, OAuth, and tools/list.

• Whether the command of the local launcher points to the installed alibabacloud-maxcompute-mcp-server, and whether alibabacloud-maxcompute-mcp-server --help runs successfully in the same runtime environment.

• Whether MAXCOMPUTE_CATALOG_CONFIG points to a readable configuration file, or MAXCOMPUTE_REGION and MAXCOMPUTE_NETWORK are both set.

• Check whether default selected local because the Remote MCP is unavailable. If local dependencies are missing, install alibabacloud-maxcompute-mcp-server[local] as prompted by the error message.

• Check whether the list of available tools includes the target tool. Remote MCP uses maxcompute_* tool names, while the local mode uses the original SDK tool names. The two are not directly interchangeable.

• After modifying the configuration, restart Cursor, Claude Code, or the corresponding MCP client.

Authentication, connection, or permission failures

• For browser-based OAuth direct connections, verify that the user has completed the Alibaba Cloud OAuth authorization. If the OAuth page does not open, check whether the client supports MCP OAuth and if the local browser or callback port is blocked.

• If you receive a 401 error with a browser-based OAuth direct connection, re-authorize and verify that the client's saved access token is valid.

• Verify that the local launcher has obtained a valid AccessKey, STS temporary credential, credential URI, or a credential from the default credential chain. Ensure that the STS security token has not expired. The local launcher does not require browser-based OAuth.

• Verify that the region and network are consistent with the target MaxCompute environment and that the FE and CatalogAPI service addresses in the original configuration point to the same region and network type.

• Verify that your VPC environment can access the CatalogAPI VPC endpoint and the MCP VPC endpoint in the same region. A VPC configuration cannot be used to connect to a public network MCP endpoint.

• The remote mode returns an error when the Remote MCP is unavailable. The default mode attempts to use the local SDK tool.

• If a 403 error occurs, ensure the current Alibaba Cloud account has MaxCompute and RAM permissions for the target project.

• Verify that the target region ID in the conversation or tool parameters is correct. If not explicitly specified, the service uses the default region of the current entry point.

• When you use a credential URI, make sure that the machine that runs the launcher can access ALIBABA_CLOUD_CREDENTIALS_URI.

• Use Remote MCP's maxcompute_access_check or local mode's check_access to verify your current identity before you troubleshoot the specific tool.

Metadata search failures

The maxcompute_schema_search_metadata for Remote MCP and the search_meta_data for the local mode use the same Catalog query syntax. Common causes of errors include:

• You are using search_meta_data in local mode, but namespaceId or MAXCOMPUTE_NAMESPACE_ID is not configured. Remote MCP does not require this configuration.

• The query statement is missing type=TABLE, type=RESOURCE, or type=SCHEMA.

• Using incompatible project and region conditions in the same query.

SQL parsing, execution, or result fetching failures

If SQL table name resolution fails, first use Remote MCP's maxcompute_schema_describe_table or Local MCP's get_table_schema to read the table schema, so the agent can use the accurate table reference that is returned. The common table name formats are schema.table or project.schema.table for a 3-layer model, and table or project.table for a 2-layer model.

If Remote MCP rejects an SQL statement as a write operation, confirm that the user intends to perform the write, and explicitly use mode=write after you receive confirmation. Do not modify the mode to bypass the read-only check.

If an SQL execution times out or the result is truncated:

• Prioritize asynchronous execution.

  • Remote MCP uses maxcompute_sql_get_status and maxcompute_sql_fetch_result to continue querying.

  • Local MCP performs follow-up queries by using get_instance_status and get_instance.

• Remote MCP uses limit and cursor to paginate and narrow the query scope. Local MCP can also use output_uri=file:///path/to/result.jsonl to write to the machine where Local MCP is located.

• Before you run the operation, call the corresponding resource usage estimation tool and limit resource consumption based on the parameter definitions in tools/list.