Todos os produtos
Search

Este produto

    OpenAPI Explorer:OpenAPI MCP Server User Guide

    Central de documentação

    OpenAPI Explorer:OpenAPI MCP Server User Guide

    Última atualização: Aug 20, 2026

    O Model Context Protocol (MCP) é um protocolo padronizado que permite a interação de um modelo de linguagem grande (LLM) com ferramentas externas e fontes de dados. O Alibaba Cloud OpenAPI MCP Server possibilita chamar APIs da Alibaba Cloud e gerenciar seus recursos de cloud usando linguagem natural.

    Selecione uma opção de uso

    Escolha uma edição

    O Alibaba Cloud OpenAPI MCP Server está disponível nas duas edições a seguir:

    Item

    Core edition

    Custom edition

    Velocidade de configuração

    Rápida. Obtenha o endpoint imediatamente após fazer login no console.

    Média. É necessário criar um servidor e selecionar as APIs.

    Cobertura de API

    Abrange todas as OpenAPIs da Alibaba Cloud.

    Abrange apenas as APIs selecionadas.

    Método de correspondência de API

    O LLM usa busca semântica para encontrar e chamar APIs automaticamente. Prompts mais específicos podem ser necessários quando várias APIs possuem funções semelhantes.

    As APIs selecionadas são expostas diretamente como ferramentas, permitindo que o LLM as chame sem necessidade de busca.

    Capacidade de ajuste

    Não suportada.

    Suportada. É possível modificar descrições e parâmetros da API.

    Quantidade de servidores

    Um por conta.

    Vários servidores podem ser criados para diferentes cenários.

    Casos de uso

    Início rápido, operações exploratórias e fluxos de trabalho entre produtos.

    Processos de negócios fixos, requisitos claros de API e cenários que exigem ajuste fino.

    • Use a Core Edition para começar rapidamente ou realizar operações que abrangem vários products de cloud.

    • Opte pela Custom Edition se você já sabe quais APIs específicas deseja usar e quer que o LLM as chame diretamente, sem buscas intermediárias.

    Selecione um método de autenticação

    Após escolher a edição, defina também o método de autenticação. O OpenAPI MCP Server suporta os dois métodos a seguir:

    • Autenticação OAuth (autenticação interativa): Redireciona automaticamente para o navegador para login. Será necessário autenticar-se novamente após a expiração do token.

    • Autenticação por credenciais estáticas: Conecta-se usando credenciais estáticas após uma verificação prévia única, sem necessidade de navegador.

    Item

    Autenticação OAuth

    Autenticação por AccessKey

    Casos de uso

    Clientes desktop com interação via navegador, desenvolvimento diário e operações exploratórias.

    Servidores headless, pipelines de CI/CD e integrações de agentes de IA não supervisionados.

    Método de autorização

    Redirecionamento pelo navegador para login e autorização do usuário.

    O AccessKey é fornecido por meio de variável de ambiente. Não há redirecionamento para navegador.

    Identidade de permissão

    Identidade do usuário que concede a autorização.

    Identidade do usuário RAM associada ao AccessKey.

    Segurança

    Tokens de curta duração oferecem maior segurança.

    Credenciais estáticas de longa duração exigem gerenciamento cuidadoso de riscos.

    Pré-requisitos

    Antes de usar o OpenAPI MCP Server, conclua as preparações abaixo conforme o método de autenticação escolhido.

    Autenticação OAuth

    Este método é ideal para clientes desktop com suporte a interação via navegador. As permissões estão vinculadas ao usuário, os tokens têm vida curta e a segurança é elevada.

    1. É necessário ter uma conta Alibaba Cloud. Caso use um usuário RAM, conceda-lhe as permissões necessárias. Para mais informações, consulte Grant a RAM user permissions to operate an MCP server.

    2. Com uma conta de administrador, acesse a página RAM console > OAuth Applications > Third-party Applications e instale e atribua o aplicativo oficial OpenAPI MCP Server. Caso contrário, a autorização OAuth para o service MCP falhará. Para mais detalhes, consulte Install and authorize a third-party application.

    Autenticação por credenciais estáticas

    Esta abordagem é recomendada para cenários sem interação via navegador, como pipelines de CI/CD, ambientes CLI e integrações de agentes de IA. Ela permite passar credenciais AccessKey (AK) por variáveis de ambiente. Se você já estiver autenticado no Alibaba Cloud CLI localmente, o proxy MCP reutiliza automaticamente as credenciais existentes, dispensando configurações adicionais.

    1. Python (>= 3,13) e uv instalados.

    2. Conta Alibaba Cloud registrada e AccessKey criado. O usuário RAM ou função RAM associada ao AccessKey deve ter a política de sistema AliyunOpenAPIMCPServerStaticCredentialAccess anexada. Acesse o RAM console para vincular essa política a um usuário RAM.

    3. Antes do primeiro uso, execute um comando de verificação prévia para confirmar a autorização da sua conta. Essa validação única aplica-se a toda a sua conta Alibaba Cloud e pode ser feita em qualquer dispositivo com navegador, não apenas na máquina que executa o servidor MCP. uvx alibabacloud.mcp-proxy@latest --server-url <MCP connection URL> pre-check --site-type INTL

    Endpoint do servidor MCP

    O processo de configuração do cliente é idêntico para as edições Core e Custom. A única diferença reside na forma de obtenção do endpoint do servidor MCP.

    Core edition

    Após o login, o sistema atribui automaticamente um endpoint de servidor MCP para a Core Edition, cobrindo todas as OpenAPIs da Alibaba Cloud por meio de uma combinação integrada de ferramentas.

    1. Faça login no console do Alibaba Cloud OpenAPI MCP service.

    2. No painel de navegação à esquerda, clique na aba Core. A página exibirá o Streamable HTTP endpoint e o SSE endpoint.

    3. Para alterar o OAuth ou configurações avançadas, clique no botão Modify correspondente:

      • Multi-account MCP: Gerencie servidores MCP centralizados em cenários de múltiplas contas. Para mais informações, consulte Use OpenAPI MCP Server in a multi-account scenario.

      • Public access: Ao ativar o acesso público, o service MCP torna-se acessível pela rede pública. Ideal para desenvolvimento e depuração locais, colaboração entre regiões ou integração com sistemas externos.

      • Custom VPC allowlist: Recomendado para cenários com requisitos rigorosos de segurança de rede.

    Custom edition

    Na Custom Edition, crie primeiro um servidor MCP e selecione as APIs desejadas. Cada API escolhida é exposta diretamente ao LLM como ferramenta, permitindo chamadas diretas sem busca semântica.

    1. Faça login no console do Alibaba Cloud OpenAPI MCP service.

    2. No painel de navegação à esquerda, clique em Custom > Create para abrir a página de configuração do MCP.

      Preencha as informações abaixo:

      • Name: O nome deve ter entre 3 e 16 caracteres, contendo apenas letras minúsculas, dígitos, sublinhados (_) e hífens (-). Exemplo: mcp-demo.

      • Document Language: Escolha o idioma das descrições de API nas ferramentas.

      • OAuth Configuration:

        • Alibaba Cloud Official OAuth: Adequado para clientes locais, como TONGYI Lingma, Cherry Studio e Cursor.

        • Custom OAuth: Indicado para plataformas próprias ou services de terceiros, como Dify auto-hospedado, AgentScope e Claude Web/Mobile.

      • Multi-account MCP: Gerencie servidores MCP centralizados em cenários de múltiplas contas. Para mais informações, consulte Use OpenAPI MCP Server in a multi-account scenario.

      • Cloud Product and API List: Configure as ferramentas de API para o service MCP.

      • Terraform Tools: Defina ferramentas MCP usando código Terraform HCL. O Terraform Tools suporta apenas criação de recursos, não modificações. Para mais detalhes, consulte Use Terraform Tools in OpenAPI MCP Server.

      • System Tools: Ferramentas oficiais pré-configuradas integradas automaticamente ao service MCP quando selecionadas.

      • MCP Instructions: Prompt que orienta o LLM sobre como usar este MCP. O cliente deve suportar o campo Instructions do protocolo padrão MCP.

      • Remarks: Adicione informações descritivas ao service MCP.

    3. Clique em Create e confirme o aviso de risco. Após a criação do servidor, a página exibirá o Streamable HTTP endpoint e o SSE endpoint.

    Nota

    Recomendamos selecionar no máximo 30 APIs por servidor MCP. Caso precise de mais APIs, crie múltiplos servidores MCP.

    Se usar o MCP em ambiente VPC, use o endpoint VPC exibido na página.

    Configuração do cliente

    Após obter o endpoint do servidor, configure a conexão no seu cliente. Esta configuração vale tanto para a Core quanto para a Custom Edition. O console do Alibaba Cloud OpenAPI MCP service oferece modelos de configuração integrados para clientes comuns como Cherry Studio, TONGYI Lingma/Cursor/Windsurf/VSCode, Claude Code e Codex. O MCP possui ampla compatibilidade, permitindo que outros clientes ou programas compatíveis com o protocolo também sejam configurados adequadamente.

    Dois métodos de autenticação são suportados:

    • Autenticação OAuth (autenticação interativa): Redireciona automaticamente para o navegador para autorização.

    • Autenticação por credenciais estáticas: Usa um AccessKey passado via variável de ambiente ou credenciais do Alibaba Cloud CLI.

    Importante

    O AccessKey é uma credencial estática de longo prazo. Se vazada, pode ser explorada persistentemente. Ao usar um AccessKey, siga estas práticas de segurança. Para mais informações, consulte Create an AccessKey.

    • Evite usar o AccessKey da sua conta Alibaba Cloud principal. Prefira o AccessKey de um usuário RAM com apenas as permissões mínimas necessárias.

    • Não codifique o AccessKey diretamente em arquivos versionados, como mcp.json. Recomendamos injetá-lo via variáveis de ambiente ou service de gerenciamento de chaves.

    • Recomendamos rotacionar seu AccessKey regularmente para reduzir o risco de vazamento de credenciais.

    Autenticação OAuth (padrão)

    Este método abre o navegador local para guiar o usuário na autorização, sendo ideal para clientes desktop com interface gráfica e para tarefas diárias de desenvolvimento ou exploração.

    Faça login no console do Alibaba Cloud OpenAPI MCP service e acesse a página de endpoint do service MCP da Core ou Custom Edition. Clique em One-click Configuration e selecione OAuth authentication (default). Em seguida, escolha a aba do cliente correspondente e siga o modelo de configuração para concluir o processo. Se uma página de autorização de usuário aparecer no navegador durante o processo, clique em Authorize.

    Cherry Studio

    Pré-requisitos: Ter o Cherry Studio instalado.

    A configuração pode ser concluída de uma das seguintes formas:

    • Configuração com um clique: Na página de modelo de configuração do console, clique em One-click Configuration for Cherry Studio e siga as instruções.

    • Configuração manual: No Cherry Studio, acesse Settings > MCP Servers, selecione Add > Quick Create, insira um nome, escolha Streamable HTTP como tipo e informe o endereço do Streamable HTTP endpoint no campo URL. Alternativamente, selecione Import from JSON e cole o JSON de configuração da página.

    Ao salvar a configuração, o navegador redirecionará automaticamente para a página de autorização OAuth da Alibaba Cloud. Após conceder a autorização, o service MCP será iniciado.

    TONGYI Lingma/Cursor/Windsurf/VSCode

    Pré-requisitos: Ter o Node.js e o npm instalados.

    A configuração pode ser concluída de uma das seguintes formas:

    • Configuração com um clique (Suportado apenas pelo Cursor): Na página de modelo de configuração do console, clique em One-click Configuration for Cursor e siga as instruções.

    • Configuração manual: Cole o JSON de configuração da página do console no arquivo de configuração MCP do seu cliente.

    Método de configuração para cada cliente:

    • TONGYI Lingma: Abra o plug-in TONGYI Lingma, clique em MCP tools na página introdutória e clique em + no canto superior direito da janela pop-up para adicionar uma ferramenta manualmente. Insira um nome personalizado, selecione STDIO para Type, insira npx para Command e insira mcp-remote-alibaba-cloud "<Streamable HTTP endpoint>" para Arguments.

    • Cursor: Na barra de menus, escolha File > Preferences > Cursor Settings > Tools & Integrations, clique em Add Custom MCP, cole o JSON no arquivo mcp.json e salve. O arquivo de configuração geralmente fica em ~/.cursor/mcp.json ou .cursor/mcp.json no diretório raiz do projeto.

    • Windsurf: Cole o JSON em ~/.windsurf/mcp.json ou .windsurf/mcp.json no diretório raiz do projeto.

    • VSCode: Pesquise por MCP em Settings e adicione a configuração conforme solicitado.

    Após salvar a configuração, complete a autorização OAuth pelo navegador na primeira utilização. Se o navegador não abrir automaticamente, reinicie o aplicativo.

    Claude Code

    Pré-requisitos: Ter o Claude Code instalado.

    Execute o comando abaixo no terminal para adicionar o servidor MCP. Certifique-se de substituir <Streamable HTTP endpoint> pelo endereço real obtido no console:

    claude mcp add openapi-mcp-core -- npx mcp-remote-alibaba-cloud "<Streamable HTTP endpoint>"

    Execute o seguinte comando para consultar o servidor MCP adicionado:

    claude mcp list

    Se uma página de autorização de usuário aparecer no navegador durante a configuração ou uso, clique em Authorize.

    Codex

    Pré-requisitos: Ter a CLI do Codex instalada.

    Execute o comando abaixo no terminal para adicionar o servidor MCP. Certifique-se de substituir <Streamable HTTP endpoint> pelo endereço real obtido no console:

    codex mcp add openapi-mcp-core -- npx mcp-remote-alibaba-cloud "<Streamable HTTP endpoint>"

    Execute o seguinte comando para consultar o servidor MCP adicionado:

    codex mcp list

    Se uma página de autorização de usuário aparecer no navegador durante a configuração ou uso, clique em Authorize.

    Autenticação por credenciais estáticas

    A autenticação por credenciais estáticas ocorre através do proxy local alibabacloud.mcp-proxy sem redirecionamento para navegador. Este método é adequado para cenários como pipelines automatizados, ambientes puramente de linha de comando e Agentes de IA não supervisionados.

    Faça login no console do Alibaba Cloud OpenAPI MCP service, acesse a página de endpoint do service MCP da Core ou Custom Edition, clique em One-click Configuration e selecione Static Credential Authentication. Em seguida, escolha a aba do cliente correspondente e conclua a configuração seguindo o modelo fornecido.

    Nota

    Se você já tiver feito login no Alibaba Cloud CLI localmente (aliyun configure), o proxy lerá automaticamente as credenciais da CLI. Não será necessário definir a variável de ambiente env na configuração.

    Cherry Studio

    Pré-requisitos:

    1. Ter o Cherry Studio, Python (>= 3,13) e uv instalados.

    2. Seu AccessKey deve ter a política de sistema AliyunOpenAPIMCPServerStaticCredentialAccess anexada.

    3. Antes do primeiro uso, execute o comando de verificação prévia no console para validar o status de autorização da sua conta. Esse comando pode ser executado em qualquer dispositivo com navegador, não precisando ser necessariamente a mesma máquina que roda o proxy.

    Conclua a configuração da seguinte maneira:

    No Cherry Studio, acesse Settings > MCP Servers > Add > Import from JSON e cole a configuração. Substitua AccessKey ID/Secret pelas suas chaves reais. Se já tiver configurado o Alibaba Cloud CLI, remova o campo env para reutilizar as credenciais locais.

    Após concluir a configuração, reinicie o Cherry Studio e envie uma solicitação de teste, como consultar a lista de instâncias ECS em uma região. Se a API for chamada conforme esperado, a autenticação por credenciais estáticas foi bem-sucedida.

    TONGYI Lingma/Cursor/Windsurf/VSCode

    Pré-requisitos:

    1. Ter o TONGYI Lingma/Cursor/Windsurf/VSCode, Python (>= 3,13) e uv instalados.

    2. Seu AccessKey deve ter a política de sistema AliyunOpenAPIMCPServerStaticCredentialAccess anexada.

    3. Antes do primeiro uso, execute o comando de verificação prévia no console para validar o status de autorização da sua conta. Esse comando pode ser executado em qualquer dispositivo com navegador, não precisando ser necessariamente a mesma máquina que roda o proxy.

    Método de configuração para cada cliente:

    • TONGYI Lingma: Na página de ferramentas MCP do plug-in, adicione uma ferramenta manualmente. Selecione STDIO para Type, insira uvx para Command e insira alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP endpoint>" --site-type INTL para Arguments. Em seguida, adicione ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET nas variáveis de ambiente.

    • Cursor: Cole o JSON em ~/.cursor/mcp.json ou .cursor/mcp.json no diretório raiz do projeto. Substitua o AccessKey ID e o secret.

    • Windsurf: Cole o JSON em ~/.windsurf/mcp.json ou .windsurf/mcp.json no diretório raiz do projeto. Substitua o AccessKey ID e o secret.

    • VSCode: Pesquise por MCP em Settings e adicione a configuração conforme solicitado.

    Se já tiver configurado o Alibaba Cloud CLI, remova a configuração de variáveis de ambiente para reutilizar as credenciais locais.

    Após concluir a configuração, salve as alterações e reinicie o cliente. Envie uma solicitação de teste para confirmar que a API é chamada conforme esperado. Isso indica que a autenticação por credenciais estáticas foi bem-sucedida.

    Claude Code

    Pré-requisitos:

    1. Ter o Claude Code, Python (>= 3,13) e uv instalados.

    2. Seu AccessKey deve ter a política de sistema AliyunOpenAPIMCPServerStaticCredentialAccess anexada.

    3. Antes do primeiro uso, execute o comando de verificação prévia no console para validar o status de autorização da sua conta. Esse comando pode ser executado em qualquer dispositivo com navegador, não precisando ser necessariamente a mesma máquina que roda o proxy.

    Conclua a configuração da seguinte maneira:

    Execute o comando abaixo no terminal para adicionar o servidor MCP. Certifique-se de substituir <Access Key ID>, <Access Key Secret> e <Streamable HTTP endpoint> pelos seus valores reais.

    Se já tiver configurado o Alibaba Cloud CLI, remova a configuração de variáveis de ambiente para reutilizar as credenciais locais.

    claude mcp add openapi-mcp-core --env ALIBABA_CLOUD_ACCESS_KEY_ID=<Access Key ID> --env ALIBABA_CLOUD_ACCESS_KEY_SECRET=<Access Key Secret> -- uvx alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP Endpoint>" --site-type INTL

    Execute o seguinte comando para consultar o servidor MCP adicionado:

    claude mcp list

    Codex

    Pré-requisitos:

    1. Ter o Codex, Python (>= 3,13) e uv instalados.

    2. Seu AccessKey deve ter a política de sistema AliyunOpenAPIMCPServerStaticCredentialAccess anexada.

    3. Antes do primeiro uso, execute o comando de verificação prévia no console para validar o status de autorização da sua conta. Esse comando pode ser executado em qualquer dispositivo com navegador, não precisando ser necessariamente a mesma máquina que roda o proxy.

    Conclua a configuração da seguinte maneira:

    Execute o comando abaixo no terminal para adicionar o servidor MCP. Certifique-se de substituir <Access Key ID>, <Access Key Secret> e <Streamable HTTP endpoint> pelos seus valores reais.

    Se já tiver configurado o Alibaba Cloud CLI, remova a configuração de variáveis de ambiente para reutilizar as credenciais locais.

    codex mcp add openapi-mcp-core --env ALIBABA_CLOUD_ACCESS_KEY_ID=<Access Key ID> --env ALIBABA_CLOUD_ACCESS_KEY_SECRET=<Access Key Secret> -- uvx alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP Endpoint>" --site-type INTL

    Execute o seguinte comando para consultar o servidor MCP adicionado:

    codex mcp list

    Uso do servidor MCP

    Após a configuração, use linguagem natural no seu cliente para gerenciar recursos de cloud. Para outros métodos de integração, consulte More ways to integrate MCP.

    • Core Edition: Descreva suas necessidades diretamente em linguagem natural. O LLM encontra automaticamente as APIs correspondentes, obtém suas definições de parâmetros e executa as chamadas de API sem que você precise especificar nomes de APIs ou parâmetros. Por exemplo, se você inserir "Ajude-me a consultar instâncias ECS na região China (Hangzhou)", o LLM encontrará e chamará automaticamente a API DescribeInstances.

    • Custom Edition: As APIs configuradas são expostas diretamente como ferramentas ao LLM, encurtando o caminho de chamada ao eliminar a necessidade de busca e correspondência. Quando várias APIs têm funções semelhantes, a Custom Edition garante que o LLM chame exatamente a API pretendida.

    Cherry Studio

    1. No menu da caixa de entrada de texto, selecione seu servidor MCP.

      Selecione o servidor openapi-mcp-core e confirme se aparece uma marca de verificação verde à direita da entrada, indicando que ele está ativado.

    2. Teste a funcionalidade do MCP. Por exemplo, consulte as instâncias ECS em uma região específica:

      Please help me query the list of ECS instances with regionId cn-chengdu and set x_mcp_region_id.
      Nota

      Se a seleção da API ou as configurações de parâmetros estiverem incorretas, tente otimizar seu prompt. Para a Custom Edition, também é possível usar o ajuste fino do MCP para resolver o problema.

    Cursor

    1. Selecione um modelo e uma chave de API. Como o Cursor tem requisitos específicos para provedores de LLM (consulte Supported providers), consulte a documentação dele ao escolher o modelo e a chave de API. Este exemplo usa os valores padrão.

    2. Na caixa de diálogo do Cursor, clique em Add Context e selecione seu servidor MCP.

    3. Na caixa de diálogo, insira uma consulta em linguagem natural para testar a funcionalidade do MCP, como "Ajude-me a consultar o número de instâncias ECS na região China (Chengdu) e exiba apenas a contagem de instâncias". Após pressionar Enter, clique em Run tool conforme solicitado para continuar.

    4. Visualize o resultado da execução do MCP. Se a seleção da API ou as configurações de parâmetros estiverem incorretas, tente otimizar seu prompt. Para a Custom Edition, também é possível usar o ajuste fino do MCP para resolver o problema.

    TONGYI Lingma

    1. No TONGYI Lingma, selecione um agent e insira seu prompt. Por exemplo, você pode consultar a lista de instâncias ECS na região China (Chengdu) e definir x_mcp_region_id.

    2. Siga as instruções no TONGYI Lingma para executar a ferramenta MCP.

    3. Visualize o resultado. Se a seleção da API ou as configurações de parâmetros estiverem incorretas, tente otimizar seu prompt. Para a Custom Edition, também é possível usar o ajuste fino do MCP para resolver o problema.

    Cline

    1. Na janela de diálogo do Cline, insira uma consulta em linguagem natural para testar a funcionalidade do MCP, como "Ajude-me a consultar o número de instâncias ECS na região China (Chengdu)".

      O Cline seleciona automaticamente a ferramenta DescribeInstances do servidor MCP configurado e extrai o valor do parâmetro RegionId da sua entrada.

    2. Visualize o resultado da execução do MCP. Se a seleção da API ou as configurações de parâmetros estiverem incorretas, tente otimizar seu prompt. Para a Custom Edition, também é possível usar o ajuste fino do MCP para resolver o problema.

    Ajuste fino do MCP (apenas Custom Edition)

    A Core Edition usa ferramentas integradas para lidar automaticamente com buscas e chamadas de API, não suportando ajustes finos.

    O modelo de linguagem grande (LLM) pode selecionar a API errada ou passar parâmetros incorretos. Se isso ocorrer, modifique a visão geral, a descrição e as descrições dos parâmetros de solicitação da API no servidor. Isso ajuda o LLM a entender e chamar a API com mais precisão.

    Exemplo 1: Erros ou dados imprecisos ao operar em recursos fora da região cn-hangzhou

    Internamente, o MCP usa x_mcp_region_id para alternar o Endpoint. Se o LLM não compreender a partir da entrada que precisa passar o x_mcp_region_id, ele operará nos recursos da região cn-hangzhou por padrão.

    Resolva esse problema usando um dos dois métodos a seguir:

    • Instrua explicitamente o LLM a definir o x_mcp_region_id na consulta.

      Find the list of ECS instances for regionId cn-qingdao, and set x_mcp_region_id.

    • Ajuste a visão geral da API ou a descrição do parâmetro de solicitação RegionId no servidor MCP.

      Por exemplo, adicione "Passe a região especificada pelo usuário para x_mcp_region_id" à visão geral da API. Ou adicione "Se o parâmetro RegionId existir, passe-o junto com x_mcp_region_id" à descrição do RegionId.

      Etapas:

      1. Acesse Custom API MCP SERVER e clique em Edit na coluna Actions do service MCP alvo.

      2. Selecione a API para ajustar e clique em Edit na coluna Actions correspondente.

      3. Modifique a visão geral, a descrição da solicitação da API ou as descrições dos parâmetros da API.

      4. Salve as alterações. Em seguida, desconecte-se e reconecte-se ao service MCP no cliente para aplicar as mudanças.

    Exemplo 2: Exclusão de parâmetros opcionais da API

    Alguns parâmetros opcionais não são usados em cenários específicos. Exclua esses parâmetros no servidor MCP. Após a exclusão, o LLM os ignorará ao gerar parâmetros. Isso reduz a taxa de erros e diminui o consumo de Tokens.

    Controle de acesso ao MCP

    image

    Após a integração de um agente de IA com o OpenAPI MCP Server, o agente não tem permissão para acessar recursos de cloud. Um usuário deve autorizar o agente a operar em seu nome. Por exemplo, um cliente pode iniciar um processo OAuth. O agente ganha acesso temporário somente após o usuário conceder autorização. Todas as operações exigem autorização do usuário. O agente só pode executar tarefas que estejam dentro das permissões do usuário. Isso implementa o princípio do menor privilégio. Além disso, o ActionTrail registra a identidade do usuário que realmente executa as operações.

    Cenários: Agentes de cliente como CherryStudio, TONGYI Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope e LangGraph, ou cenários onde um agente precisa agir em nome de um usuário.

    Mais formas de integrar o MCP

    • Configure um aplicativo OAuth personalizado no Dify para integrar com o OpenAPI MCP Server. Para mais informações, consulte Integrate OpenAPI MCP Server in Dify.

    • Em um agente personalizado, use o SDK oficial do MCP para concluir o processo de autorização OAuth personalizado e integrar frameworks de agentes populares. Para mais informações, consulte Integrate OpenAPI MCP Server in an agent.

    FAQ

    Todas as APIs em Tools podem ser chamadas pelo cliente MCP?

    Não necessariamente. O sucesso de uma chamada de API depende das permissões do usuário RAM. Pode ser o usuário que inicia a autenticação OAuth ou o usuário associado ao AccessKey (AK) para autenticação. Se um usuário RAM não tiver permissão para chamar uma API, o modelo de linguagem grande (LLM) também não poderá chamá-la.

    Solução: Conceda as permissões de API necessárias ao usuário RAM. Para mais informações, consulte Manage RAM user permissions.

    Importante

    Para evitar que o LLM chame APIs de exclusão de recursos devido a má interpretação, o que poderia afetar seus services, não conceda permissões de exclusão de recursos ao usuário RAM.

    Permissão negada ao criar um Servidor MCP como usuário RAM

    Solução:

    • Conceda a política de sistema AliyunOpenAPIMCPServerFullAccess ao usuário RAM. Para mais informações, consulte Manage RAM user permissions.

    • Conceda uma política personalizada ao usuário RAM:

      1. Use uma conta de administrador para criar uma política personalizada no RAM console. Para mais informações, consulte Create a custom policy.

        O conteúdo da política é o seguinte:

        Clique para visualizar a política para operações do Servidor MCP

        Esta política inclui permissões para criar, atualizar, consultar e excluir Servidores MCP, além de consultar ferramentas de sistema MCP.

        {
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

      2. Use uma conta de administrador para conceder a permissão personalizada ao usuário RAM alvo. Para mais informações, consulte Manage RAM user permissions.

    Se um endpoint de conexão do Servidor MCP for exposto, ele pode ser mal utilizado por outros?

    Não. Quando um cliente usa o endpoint, a autenticação OAuth inicia um processo de autorização. Este processo exige que o usuário faça login e conceda acesso. O sistema verifica se a conta Alibaba Cloud do usuário RAM corresponde à conta Alibaba Cloud do Servidor MCP. O acesso é concedido apenas se houver correspondência. Para autenticação por credenciais estáticas, o acesso é restrito pelas permissões do usuário RAM associado ao AK. Uma parte não autorizada não pode exceder esse escopo de permissões.

    Como escolher entre autenticação por credenciais estáticas e autenticação OAuth?

    Escolha o método de autenticação adequado ao seu caso de uso:

    • Autenticação OAuth: Adequada para cenários de clientes desktop que envolvem interação com navegador. As permissões estão vinculadas ao usuário e o token tem vida curta para maior segurança. Use OAuth para desenvolvimento diário e operações exploratórias.

    • Autenticação por credenciais estáticas (AK): Adequada para cenários onde o redirecionamento para navegador é inconveniente, como pipelines automatizados, ambientes apenas de linha de comando (servidores sem interface gráfica (GUI)) e integrações de Agentes de IA não supervisionados. As permissões estão vinculadas à identidade RAM associada ao AK. Você deve gerenciar a segurança das credenciais por conta própria.

    O que devo fazer se um AccessKey Secret vazar?

    1. Desative ou exclua imediatamente o AccessKey no RAM console.

    2. Crie um novo AccessKey e atualize a configuração do seu cliente.

    3. Verifique os logs do ActionTrail referentes ao período do vazamento para identificar quaisquer chamadas não autorizadas.