MaxCompute:MaxCompute MCP service

Capacidades principais

• Navegação e pesquisa de metadados de catálogo: Navegue hierarquicamente por projetos, schemas, tabelas, campos e partições. Há suporte para pesquisa em linguagem natural.

• Gerenciamento de tabelas e manutenção de metadados: Crie tabelas (com opções de ciclo de vida, chave primária e atualizações parciais de colunas), insira pequenos volumes de dados e atualize comentários de tabelas, tags ou descrições de colunas.

• Verificações de identidade e permissão: Visualize a identidade da conta atual e use as informações de autorização do MaxCompute para solucionar problemas de acesso.

• Autenticação e autorização:

  • O Remote MCP usa OAuth da Alibaba Cloud para autorização.

  • O Local MCP suporta AccessKey/SecretKey (AK/SK), Security Token Service (STS), Credentials URI, ECS RAM Role e a cadeia de credenciais padrão da Alibaba Cloud.

• Registro de cliente no lado do servidor (Client ID Metadata Documents, CIMD):

  Em ambientes onde esse recurso está ativado, clientes no lado do servidor ou auto-hospedados podem usar uma URL de documento de metadados HTTPS como client_id para contornar o Dynamic Client Registration (DCR). No entanto, ainda é necessário consentimento explícito na página de confirmação de autorização após o login. Para mais informações, consulte Configurar clientes no lado do servidor (Client ID Metadata Documents).

• Análise e execução de SQL:

  Suporta validação de instruções, estimativa de volume de dados verificados e uso de Compute Unit (CU), execução de consultas SQL somente leitura ou de escrita, consultas de status de instância e recuperação de resultados. Consultas SQL de escrita e alterações de metadados exigem confirmação do usuário.

• Análise inteligente:

  Gera rascunhos SQL somente leitura a partir de linguagem natural, diagnostica problemas de jobs e analisa o uso de cotas de computação. Os resultados indicam o escopo das evidências e fornecem ações recomendadas.

• Análise de metadados de tabela:

  Verifica estruturas de tabelas e metadados de partição sem verificar os dados da tabela.

• Gerenciamento de SemanticSpec:

  Crie e mantenha rascunhos de SemanticSpec que descrevem a semântica dos dados, visualize versões publicadas e use o DataScan para gerar e aplicar recomendações descobertas a partir de metadados semânticos.

• Pesquisa e perguntas e respostas da base de conhecimento:

  O Remote MCP inclui uma base de conhecimento integrada da documentação do MaxCompute que suporta pesquisas por palavras-chave e perguntas e respostas em linguagem natural, retornando respostas com citações.

• Descoberta e leitura de Skills: O Remote MCP inclui recursos integrados de MCP Skill. Os clientes usam tools/list para descobrir ferramentas disponíveis, maxcompute_skill_list para recuperar o índice de Skills e maxcompute_skill_read para ler os arquivos de Skill necessários. Essa capacidade pode ser aplicada para análise semântica do Information Schema e orientação de feedback.

• Análise de O&M e governança do Information Schema:

  • O Remote MCP inclui um pacote semântico integrado do Information Schema.

  • O Local MCP requer a instalação separada da Skill correspondente.

• Informações de ferramentas multilíngues: O Remote MCP fornece títulos e descrições de ferramentas em chinês simplificado, chinês tradicional e inglês na saída de tools/list, e indica se uma ferramenta depende de um modelo.

Visão geral da arquitetura

O MCMCP possui uma arquitetura em camadas com as seguintes camadas, de cima para baixo:

• Ecossistema de agentes de usuário: Suporta conexões de clientes MCP como Claude Code, Codex, Qwen Code, Cursor e Qoder.

• Coleção de MaxCompute Skills: Os agentes podem concluir tarefas mais complexas combinando pacotes semânticos, comandos comuns, modelos de desenvolvimento e limites de uso.

• Serviço MCMCP: Encapsula capacidades como MaxCompute OpenAPI, StorageAPI e CatalogAPI em ferramentas MCP.

• Capacidades subjacentes do MaxCompute: Inclui capacidades do produto, como metadados, mecanismos de computação e armazenamento.

Informações de exibição da lista de ferramentas

• Informações de exibição de ferramentas multilíngues

  O Remote MCP fornece informações de exibição multilíngues para cada objeto de ferramenta na resposta tools/list. Clientes que suportam esta extensão podem ler _meta["com.aliyun.maxcompute/display"] e exibir o título e a descrição em chinês simplificado (zh-CN), chinês tradicional (zh-TW) ou inglês (en), com base no idioma da interface.

  Os clientes devem confiar no conjunto de ferramentas retornado por cada chamada tools/list em vez de manter um catálogo de ferramentas separado. Se o idioma selecionado estiver ausente ou a versão da extensão não for suportada, recorra aos campos padrão title, name e description. Para indicar uma dependência de modelo, marque uma ferramenta como suportada por MaxAgent apenas quando _meta["com.aliyun.maxcompute/model_backed"] for true. As informações de exibição destinam-se apenas à apresentação da UI e não devem ser usadas para decisões de permissão, faturamento ou segurança.

• Capacidades de análise inteligente

  SQL em linguagem natural, diagnóstico de jobs e análise de cotas são as três ferramentas de análise inteligente do Remote MCP. Todas são somente leitura. Elas não executam automaticamente o SQL gerado, reexecutam ou cancelam jobs, ou modificam a capacidade da cota e configurações de agendamento.

  A análise do modelo pode consumir MaxAgent Credits, e uma única chamada de ferramenta pode acionar várias chamadas de modelo. Quando as capacidades do modelo ou evidências necessárias estiverem indisponíveis, a ferramenta poderá retornar um resultado partial. Use os campos warnings e missing_evidence para avaliar em quais conclusões você pode confiar.

Pré-requisitos para análise inteligente

• O cliente MCP está conectado ao Remote MCP por meio de OAuth baseado em navegador ou do iniciador local.

• A identidade autenticada atual tem as permissões necessárias para o projeto, job ou cota alvo do MaxCompute.

• A região na solicitação corresponde à região onde os recursos alvo estão localizados.

• Ao usar capacidades de modelo MaxAgent, a identidade atual possui uma cota válida do MaxAgent e MaxAgent Credits suficientes na região selecionada.

• Para consultar metadados do tenant ou jobs históricos usando a ferramenta Generate SQL, a identidade atual deve atender aos requisitos do Information Schema.

• Se você precisar de utilização histórica da capacidade da cota ou dados de consumo de jobs, as capacidades de observação histórica correspondentes devem estar disponíveis na região do serviço alvo.

Normalmente, você só precisa declarar seu objetivo na conversa, e o agente seleciona a ferramenta e preenche seus parâmetros. Você também pode chamar a ferramenta MCP diretamente usando os exemplos JSON neste tópico.

Resultados da análise inteligente

Todas as três ferramentas retornam resultados MCP estruturados. Preste atenção especial aos seguintes campos:

• ok: Indica se o protocolo de chamada da ferramenta foi concluído com sucesso. ok=true não garante que as evidências estejam completas.

• data: Contém dados de negócios, como rascunhos SQL, resultados de diagnóstico ou observações de cota.

• meta.outcome ou metadata.outcome: Indica o status do resultado de negócio.

• warnings: Descreve limitações não fatais, degradações ou comportamentos de fallback.

• missing_evidence: Lista quaisquer evidências que não puderam ser obtidas e os motivos.

• usage: Mostra o número de chamadas de modelo e o uso de tokens relatado pelo modelo.

Valores comuns de outcome incluem:

Não trate um resultado partial como uma chamada de API falha. Use o campo missing_evidence para determinar quais perguntas as conclusões atuais podem responder e se você precisa complementar permissões, escopo ou realizar um diagnóstico mais profundo. Ao solucionar problemas, não copie informações de autenticação ou respostas completas de backend.

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>"
  }
}

Diagnóstico de jobs

{
  "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.

Análise de cotas

{
  "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.

Requisitos do Information Schema

O Generate SQL pode usar visualizações do Information Schema no nível do tenant. A análise de cotas para utilização de capacidade e evidências de jobs não usa o Information Schema. O Generate SQL permite apenas visualizações que estão na lista de permissões do lado do servidor, como:

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS_HISTORY

Quando o Generate SQL usa essas visualizações, ele deve atender às seguintes condições:

1. A identidade autenticada atual deve ter permissões de leitura para o Information Schema no nível do tenant. Contas raiz geralmente têm esse acesso por padrão. O acesso para usuários RAM ou funções RAM depende da configuração definida pelo administrador do tenant.

2. A identidade atual deve ter pelo menos um projeto MaxCompute visível na região alvo. Este projeto é usado para enviar consultas SQL somente leitura do Information Schema. A identidade também deve ter as permissões necessárias para criar instâncias de consulta.

3. A região alvo deve fornecer as visualizações no nível do tenant mencionadas acima e suas dependências de backend.

Limitações de segurança e escopo:

• O Generate SQL lê visualizações no nível do tenant registradas por Skills integradas, mas não pode consultar visualizações de sistema desconhecidas ou misturar consultas com tabelas físicas.

• Antes que o modelo selecione uma visualização do sistema, o Generate SQL carrega a Skill raiz do Information Schema. Ele usa a granularidade de dados, a atualidade e as colunas da visualização para determinar a fonte de fatos necessária. Depois que uma visualização é selecionada, o Generate SQL carrega a documentação completa de colunas para essa visualização.

• Rascunhos de visualização do sistema para o Generate SQL devem incluir um intervalo de tempo e uma cláusula LIMIT.

• As consultas são sempre somente leitura. Elas não modificam cotas, configurações de agendamento ou jobs.

Casos de uso para ferramentas de análise inteligente

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.

Recomendações para usar a ferramenta de análise inteligente

• Forneça apenas os campos de escopo suportados pela ferramenta atual. Para geração de SQL, use region, sources e o opcional analysis_context. Para diagnóstico de jobs, use o projeto e Instance ID ou uma URL Logview. Para análise de cotas, use region e o apelido exato da cota. Não inclua campos de contexto de outras ferramentas na chamada atual.

• Para gerar SQL para um escopo de dados conhecido, forneça sources. Isso evita um processo amplo de descoberta que pode resultar em zero candidatos ou múltiplos conjuntos de dados ambíguos.

• Para diagnóstico de jobs, use standard primeiro. Use deep apenas quando os resultados forem inconclusivos ou quando for necessária uma investigação mais aprofundada.

• Para análise de cotas, compare primeiro os dados de consumo de jobs retornados. Em seguida, investigue detalhadamente algumas cotas e instâncias de alta demanda. Não trate resultados parciais como uma lista completa.

• Sempre distinga entre fatos confirmados, julgamentos do modelo e missing_evidence.

• Os usuários devem confirmar separadamente quaisquer operações de dimensionamento, agendamento, migração, execução SQL, reexecução ou cancelamento.

Regras gerais de chamada

• As ferramentas podem acessar apenas os recursos do MaxCompute que a identidade atual está autorizada a acessar. Não equipare a visibilidade da ferramenta com a autorização de recursos.

• Após descobrir tabelas candidatas, leia a estrutura precisa da tabela antes de gerar ou executar SQL. Não adivinhe colunas, partições ou o schema com base no nome da tabela.

• O cliente deve obter confirmação explícita do usuário antes de realizar operações de escrita. Essas operações incluem escrita de SQL, criação de tabelas, inserção de dados, atualização de metadados e modificação de SemanticSpec. O gateway não realiza confirmação secundária interativa para o cliente.

• Para grandes conjuntos de resultados, use paginação, restrinja o escopo da consulta ou leia de uma instância assíncrona. O Local MCP também pode gravar em um arquivo usando o file://output_uri local. Este caminho refere-se à máquina onde o Local MCP está localizado, não à máquina do cliente MCP.

• O execution_mode para maxcompute_sql_execute assume o padrão wlm. Ao usar MaxQA (MCQA v2), passe explicitamente execution_mode=maxqa e o quota_name interativo. Não passe settings.odps.task.wlm.quota ao mesmo tempo. Para chamadas subsequentes de status, resultado ou cancelamento, passe apenas o project e instance_id. Não passe ou salve a conexão ou cookie MaxQA do lado do servidor.

O cliente MCP não consegue encontrar ferramentas

• Para conexões diretas via OAuth baseado em navegador, certifique-se de que o endpoint do serviço Remote MCP inclui /mcp e que a mesma configuração de cliente não mistura endpoints de rede pública e VPC.

• Certifique-se de que o cliente usado para a conexão direta OAuth baseada em navegador suporta Streamable HTTP, OAuth e tools/list.

• Verifique se o command do iniciador local aponta para o executável instalado alibabacloud-maxcompute-mcp-server. No mesmo ambiente de tempo de execução, verifique se alibabacloud-maxcompute-mcp-server --help é executado com sucesso.

• Verifique se MAXCOMPUTE_CATALOG_CONFIG aponta para um arquivo de configuração legível, ou se tanto MAXCOMPUTE_REGION quanto MAXCOMPUTE_NETWORK estão definidos.

• Verifique se o modo default selecionou o modo local porque o Remote MCP está indisponível. Se as dependências locais estiverem ausentes, instale alibabacloud-maxcompute-mcp-server[local] conforme indicado pela mensagem de erro.

• Verifique se a lista de ferramentas disponíveis inclui a ferramenta alvo. O Remote MCP usa nomes de ferramentas maxcompute_*, enquanto o modo local usa os nomes originais das ferramentas do SDK. Os dois não são diretamente intercambiáveis.

• Após modificar a configuração, reinicie o Cursor, Claude Code ou o cliente MCP correspondente.

Falhas de autenticação, conexão ou permissão

• Para conexões diretas via OAuth baseado em navegador, verifique se o usuário concluiu a autorização OAuth da Alibaba Cloud. Se a página OAuth não abrir, verifique se o cliente suporta MCP OAuth e se o navegador local ou a porta de callback está bloqueada.

• Se você receber um erro 401 com uma conexão direta OAuth baseada em navegador, reautorize e verifique se o token de acesso salvo pelo cliente é válido.

• Verifique se o iniciador local obteve uma AccessKey válida, credencial temporária STS, credential URI ou uma credencial da cadeia de credenciais padrão. Certifique-se de que o token de segurança STS não expirou. O iniciador local não requer OAuth baseado em navegador.

• Verifique se a region e a network são consistentes com o ambiente alvo do MaxCompute e se os endereços de serviço FE e CatalogAPI na configuração original apontam para a mesma região e tipo de rede.

• Verifique se seu ambiente VPC pode acessar o endpoint VPC do CatalogAPI e o endpoint VPC do MCP na mesma região. Uma configuração VPC não pode ser usada para conectar-se a um endpoint MCP de rede pública.

• O modo remote retorna um erro quando o Remote MCP está indisponível. O modo default tenta usar a ferramenta local do SDK.

• Se ocorrer um erro 403, certifique-se de que a conta Alibaba Cloud atual tenha permissões MaxCompute e RAM para o projeto alvo.

• Verifique se o ID da região alvo na conversa ou nos parâmetros da ferramenta está correto. Se não for especificado explicitamente, o serviço usa a região padrão do ponto de entrada atual.

• Ao usar uma credentials URI, certifique-se de que a máquina que executa o iniciador possa acessar ALIBABA_CLOUD_CREDENTIALS_URI.

• Use maxcompute_access_check do Remote MCP ou check_access do modo local para verificar sua identidade atual antes de solucionar problemas da ferramenta específica.

Falhas na pesquisa de metadados

A ferramenta Remote MCP maxcompute_schema_search_metadata e a ferramenta Local MCP search_meta_data no modo local usam a mesma sintaxe de consulta Catalog. Causas comuns de erros incluem:

• Você está usando search_meta_data no modo local, mas namespaceId ou MAXCOMPUTE_NAMESPACE_ID não está configurado. O Remote MCP não requer esta configuração.

• A instrução de consulta está sem type=TABLE, type=RESOURCE ou type=SCHEMA.

• A consulta usa condições de projeto e região incompatíveis.

Falhas na análise, execução ou recuperação de resultados SQL

Se a resolução do nome da tabela SQL falhar, primeiro use maxcompute_schema_describe_table do Remote MCP ou get_table_schema do Local MCP para ler o schema da tabela, para que o agente possa usar a referência precisa da tabela retornada. Os formatos comuns de nome de tabela são schema.table ou project.schema.table para um modelo de 3 camadas, e table ou project.table para um modelo de 2 camadas.

Se o Remote MCP rejeitar uma instrução SQL como operação de escrita, confirme se o usuário pretende realizar a escrita e use explicitamente mode=write após receber a confirmação. Não modifique o modo para contornar a verificação somente leitura.

Se uma execução SQL atingir o tempo limite ou o resultado for truncado:

• Priorize a execução assíncrona.

  • O Remote MCP usa maxcompute_sql_get_status e maxcompute_sql_fetch_result para continuar consultando.

  • O Local MCP realiza consultas de acompanhamento usando get_instance_status e get_instance.

• O Remote MCP usa limit e cursor para paginar e restringir o escopo da consulta. O Local MCP também pode usar output_uri=file:///path/to/result.jsonl para gravar na máquina onde o Local MCP está localizado.

• Antes de executar a operação, chame a ferramenta de estimativa de uso de recursos correspondente e limite o consumo de recursos com base nas definições de parâmetros em tools/list.

Remote MCP

O MaxCompute Remote MCP suporta leitura e gerenciamento de pacotes semânticos (SemanticSpec). Um pacote semântico armazena termos de negócios, definições de métricas, relacionamentos de tabelas e exemplos de consultas, que um agente referencia para entender perguntas de negócios e gerar SQL.

O Remote MCP inclui um pacote semântico integrado do Information Schema. Após a conexão do Remote MCP, perguntas de governança e operações sobre armazenamento, custo, permissões e jobs podem ser feitas diretamente no agente, sem instalar Skills adicionais.

Proprietários de dados também podem gerar sugestões semânticas por meio de conversas, revisá-las e, em seguida, atualizar e publicar o pacote semântico.

• Pré-requisitos

  Antes de usar pacotes semânticos, ative o MaxAgent e, em seguida, conecte-se ao Remote MCP e conclua a autenticação conforme descrito em Guia do serviço MaxCompute MCP. Para as permissões necessárias para gerenciar pacotes semânticos e acessar dados, consulte visão geral do pacote semântico.

• Ferramentas de pacotes semânticos

  As seguintes ferramentas aplicam-se ao Remote MCP. O modo local do iniciador local não fornece essas ferramentas. As ferramentas disponíveis na conexão atual são determinadas pela lista de ferramentas (tools/list) que o cliente recupera.

  Na maioria dos casos, descrever o objetivo na conversa é suficiente. O agente seleciona as ferramentas.

  Ferramenta	Finalidade
  maxcompute_semanticspec_list	Encontra pacotes semânticos visíveis para a identidade atual
  maxcompute_semanticspec_get	Visualiza informações do pacote semântico e lê o rascunho, sugestões do sistema ou conteúdo atualmente publicado
  maxcompute_semanticspec_create	Cria um pacote semântico e especifica seu escopo de dados
  maxcompute_semanticspec_update	Atualiza informações do pacote semântico ou conteúdo do rascunho
  maxcompute_semanticspec_refresh_suggestions	Inicia uma varredura semântica para gerar ou atualizar sugestões do sistema
  maxcompute_datascan_get_latest_job_status	Verifica o status de um job de varredura semântica
  maxcompute_semanticspec_apply_suggestions	Aplica sugestões selecionadas do sistema ao rascunho
  maxcompute_semanticspec_publish	Publica conteúdo semântico revisado
  maxcompute_semanticspec_delete	Exclui um pacote semântico

• Exemplos

  • Para analisar dados com um pacote semântico publicado, insira um prompt como:

    List the semantic packages visible in <region_id> and find the order analysis semantic package of the <project_name> project.
    Read its published content, explain how "valid order count" is defined, and then generate SQL that summarizes the last 7 days by channel. Do not execute it yet.

    Verifique se o SQL gerado usa a definição de métrica esperada e, em seguida, execute a consulta de acordo com o fluxo de trabalho do cliente. Ler um pacote semântico não concede permissões de consulta em tabelas.

  • Para manter um pacote semântico, insira um prompt como:

    Prepare to refresh the system suggestions for <semantic_spec_name>. First show the data scope and the planned operations, and start the scan only after I confirm.
    When the scan is complete, show the suggestions for my review.

    Após a atualização das sugestões do sistema, revise o conteúdo antes de decidir se deve aplicá-lo ao rascunho e publicá-lo. A atualização não aplica ou publica sugestões automaticamente.

  Importante

  Uma varredura semântica pode enviar consultas MaxCompute e consumir recursos de computação. Atualizar um rascunho ou aplicar sugestões substitui toda a seção de conteúdo selecionada. Antes de atualizar ou aplicar, leia e retenha quaisquer definições manuais que ainda sejam necessárias e, em seguida, verifique o resultado. Execute operações de criação, modificação, varredura, publicação e exclusão somente após o alvo e o impacto serem confirmados no cliente.

Local MCP

O Local MCP fornece apenas ferramentas locais do MaxCompute MCP. Para usar os seguintes cenários semânticos com o Local MCP, instale a Information Schema Skill no ambiente do cliente ou agente: