Todos los productos
Search

Este producto

    OpenAPI Explorer:OpenAPI MCP Server User Guide

    Centro de documentos

    OpenAPI Explorer:OpenAPI MCP Server User Guide

    Última actualización: Sep 04, 2026

    Model Context Protocol (MCP) es un protocolo estandarizado que permite a un modelo de lenguaje grande (LLM) interactuar con herramientas externas y fuentes de datos. El servidor MCP de OpenAPI de Alibaba Cloud le permite invocar las API de Alibaba Cloud y gestionar sus recursos en la nube mediante lenguaje natural.

    Seleccione una opción de uso

    Seleccione una edición

    El servidor MCP de OpenAPI de Alibaba Cloud está disponible en las siguientes dos ediciones:

    Elemento

    Edición Core

    Edición Custom

    Velocidad de configuración

    Rápida. Obtenga el endpoint inmediatamente después de iniciar sesión en la consola.

    Media. Debe crear un servidor y seleccionar las API.

    Cobertura de API

    Cubre todas las OpenAPI de Alibaba Cloud.

    Cubre únicamente las API seleccionadas.

    Método de coincidencia de API

    El LLM utiliza búsqueda semántica para encontrar e invocar API automáticamente. Es posible que se requieran instrucciones más específicas cuando varias API tienen funciones similares.

    Las API seleccionadas se exponen directamente como herramientas, lo que permite al LLM invocarlas sin necesidad de búsqueda.

    Capacidad de ajuste

    No compatible.

    Compatible. Puede modificar descripciones y parámetros de las API.

    Número de servidores

    Uno por cuenta.

    Se pueden crear varios servidores para diferentes escenarios.

    Casos de uso

    Inicio rápido, operaciones exploratorias y flujos de trabajo entre productos.

    Procesos empresariales fijos, requisitos claros de API y escenarios que requieren ajuste fino.

    • Utilice la Edición Core para un inicio rápido o para operaciones que abarcan múltiples productos en la nube.

    • Utilice la Edición Custom si tiene API específicas en mente y desea que el LLM las invoque directamente sin realizar búsquedas.

    Seleccione un método de autenticación

    Después de seleccionar una edición, también debe elegir un método de autenticación. El servidor MCP de OpenAPI admite los siguientes dos métodos de autenticación:

    • Autenticación OAuth (autenticación interactiva): Redirige automáticamente a un navegador para iniciar sesión. Deberá volver a iniciar sesión cuando expire el token.

    • Autenticación con credenciales estáticas: Se conecta mediante credenciales estáticas tras una verificación previa única, sin necesidad de utilizar un navegador.

    Elemento

    Autenticación OAuth

    Autenticación con AccessKey

    Casos de uso

    Clientes de escritorio con interacción mediante navegador, desarrollo diario y operaciones exploratorias.

    Servidores headless, canalizaciones de CI/CD e integraciones de agentes de IA desatendidas.

    Método de autorización

    Redirección del navegador para el inicio de sesión y la autorización del usuario.

    La AccessKey se transmite mediante una variable de entorno. No se requiere redirección del navegador.

    Identidad de permisos

    Identidad del usuario que otorga la autorización.

    Identidad del usuario de RAM asociado a la AccessKey.

    Seguridad

    Los tokens de corta duración ofrecen mayor seguridad.

    Las credenciales estáticas de larga duración requieren una gestión cuidadosa de riesgos.

    Requisitos previos

    Antes de utilizar el servidor MCP de OpenAPI, complete las siguientes preparaciones según el método de autenticación seleccionado.

    Autenticación OAuth

    Este método es adecuado para clientes de escritorio que admiten interacción mediante navegador. Los permisos están vinculados al usuario, los tokens son de corta duración y la seguridad es mayor.

    1. Debe contar con una cuenta de Alibaba Cloud. Si utiliza un usuario de RAM, otórguele los permisos necesarios. Para obtener más información, consulte Grant a RAM user permissions to operate an MCP server.

    2. Utilice una cuenta de administrador para ir a la página RAM console > OAuth Applications > Third-party Applications y, a continuación, instale y asigne la aplicación oficial del servidor MCP de OpenAPI. De lo contrario, la autorización OAuth para el servicio MCP fallará. Para obtener más información, consulte Install and authorize a third-party application.

    Autenticación con credenciales estáticas

    Este método es adecuado para escenarios sin interacción mediante navegador, como canalizaciones de CI/CD, entornos de CLI e integraciones de agentes de IA. Admite la transmisión de credenciales de AccessKey (AK) mediante variables de entorno. Si ya ha iniciado sesión en Alibaba Cloud CLI localmente, el proxy de MCP reutiliza automáticamente las credenciales existentes y no se requiere configuración adicional.

    1. Python (>= 3.13) y uv instalados.

    2. Ha registrado una cuenta de Alibaba Cloud y ha creado una AccessKey. El usuario de RAM o el rol de RAM asociado a la AccessKey tiene adjunta la directiva del sistema AliyunOpenAPIMCPServerStaticCredentialAccess. Puede ir a la RAM console para adjuntar esta directiva a un usuario de RAM.

    3. Antes del primer uso, debe ejecutar un comando de verificación previa para confirmar que su cuenta ha sido autorizada. Esta verificación única se aplica a toda su cuenta de Alibaba Cloud y puede realizarse desde cualquier dispositivo con navegador, no solo desde la máquina que ejecuta el servidor MCP. uvx alibabacloud.mcp-proxy@latest --server-url <MCP connection URL> pre-check --site-type INTL

    Endpoint del servidor MCP

    El proceso de configuración del cliente es el mismo para las ediciones Core y Custom. La única diferencia radica en cómo se obtiene el endpoint del servidor MCP.

    Edición Core

    Después de iniciar sesión, el sistema asigna automáticamente un endpoint de servidor MCP para la Edición Core, que cubre todas las OpenAPI de Alibaba Cloud mediante una combinación integrada de herramientas.

    1. Inicie sesión en la consola del servicio MCP de OpenAPI de Alibaba Cloud.

    2. En el panel de navegación izquierdo, haga clic en la pestaña Core. La página muestra el Streamable HTTP endpoint y el SSE endpoint.

    3. Para modificar OAuth o configuraciones avanzadas, haga clic en el botón Modify correspondiente:

      • Multi-account MCP: Gestione los servidores MCP de forma centralizada en escenarios de cuentas múltiples. Para obtener más información, consulte Use OpenAPI MCP Server in a multi-account scenario.

      • Public access: Tras habilitar el acceso público, se puede acceder al servicio MCP a través de la red pública. Esto es adecuado para desarrollo y depuración locales, colaboración entre regiones o integración con sistemas externos.

      • Custom VPC allowlist: Adecuado para escenarios con requisitos estrictos de seguridad de red.

    Edición Custom

    Para la Edición Custom, primero debe crear un servidor MCP y seleccionar las API necesarias. Cada API seleccionada se expone directamente al LLM como una herramienta, lo que le permite invocarla directamente sin búsqueda semántica.

    1. Inicie sesión en la consola del servicio MCP de OpenAPI de Alibaba Cloud.

    2. En el panel de navegación izquierdo, haga clic en Custom > Create para abrir la página de configuración de MCP.

      Introduzca la siguiente información:

      • Name: El nombre debe tener entre 3 y 16 caracteres y solo puede contener letras minúsculas, dígitos, guiones bajos (_) y guiones (-). Por ejemplo, mcp-demo.

      • Document Language: Seleccione el idioma para las descripciones de las API en las herramientas.

      • OAuth Configuration:

        • Alibaba Cloud Official OAuth: Adecuado para clientes locales, como TONGYI Lingma, Cherry Studio y Cursor.

        • Custom OAuth: Adecuado para plataformas propias o servicios de terceros, como Dify auto-desplegado, AgentScope y Claude Web/Mobile.

      • Multi-account MCP: Gestione los servidores MCP de forma centralizada en escenarios de cuentas múltiples. Para obtener más información, consulte Use OpenAPI MCP Server in a multi-account scenario.

      • Cloud Product and API List: Configure las herramientas de API para el servicio MCP.

      • Terraform Tools: Defina herramientas MCP mediante código HCL de Terraform. Terraform Tools solo admite la creación de recursos, no su modificación. Para obtener más información, consulte Use Terraform Tools in OpenAPI MCP Server.

      • System Tools: Herramientas oficiales preconfiguradas que se integran automáticamente en el servicio MCP al seleccionarlas.

      • MCP Instructions: Una instrucción que indica al LLM cómo utilizar este MCP. El cliente debe ser compatible con el campo Instructions del protocolo estándar MCP.

      • Remarks: Agregue información descriptiva para el servicio MCP.

    3. Haga clic en Create y confirme la advertencia de riesgo. Una vez creado el servidor, la página mostrará el Streamable HTTP endpoint y el SSE endpoint.

    Nota

    Se recomienda seleccionar no más de 30 API para un solo servidor MCP. Si necesita utilizar más API, cree varios servidores MCP.

    Si utiliza MCP en un entorno de VPC, use el endpoint de VPC que se muestra en la página.

    Configuración del cliente

    Una vez obtenido el endpoint del servidor, configure la conexión en su cliente. Esta configuración aplica tanto para la edición Core como para la Custom. La consola del servicio MCP de OpenAPI de Alibaba Cloud proporciona plantillas de configuración integradas para clientes comunes como Cherry Studio, TONGYI Lingma/Cursor/Windsurf/VSCode, Claude Code y Codex. MCP es ampliamente compatible, por lo que otros clientes o programas que admitan el protocolo también pueden configurarse en consecuencia.

    Se admiten dos métodos de autenticación:

    • Autenticación OAuth (autenticación interactiva): Redirige automáticamente a un navegador para la autorización.

    • Autenticación con credenciales estáticas: Utiliza una AccessKey transmitida mediante una variable de entorno o credenciales de Alibaba Cloud CLI.

    Importante

    Una AccessKey es una credencial estática de largo plazo. Si se filtra, puede ser explotada de manera persistente. Al utilizar una AccessKey, debe seguir estas prácticas de seguridad. Para obtener más información, consulte Create an AccessKey.

    • No utilice la AccessKey de su cuenta de Alibaba Cloud. En su lugar, use la AccessKey de un usuario de RAM con únicamente los permisos mínimos necesarios.

    • No codifique la AccessKey directamente en archivos bajo control de versiones, como mcp.json. Se recomienda inyectarla mediante variables de entorno o un servicio de gestión de claves.

    • Se recomienda rotar su AccessKey periódicamente para reducir el riesgo de filtración de credenciales.

    Autenticación OAuth (predeterminada)

    Este método abre el navegador local para guiar al usuario a través de la autorización, lo que lo hace ideal para clientes de escritorio con interfaz gráfica y para tareas diarias de desarrollo o exploración.

    Inicie sesión en la consola del servicio MCP de OpenAPI de Alibaba Cloud y vaya a la página del endpoint del servicio MCP para la edición Core o Custom. Haga clic en One-click Configuration y seleccione OAuth authentication (default). Luego, seleccione la pestaña del cliente correspondiente y siga la plantilla de configuración para completar el proceso. Si durante el proceso se muestra una página de autorización de usuario en el navegador, haga clic en Authorize.

    Cherry Studio

    Requisitos previos: Ha instalado Cherry Studio.

    Puede completar la configuración de una de las siguientes maneras:

    • Configuración con un clic: En la página de plantilla de configuración de la consola, haga clic en One-click Configuration for Cherry Studio y siga las indicaciones.

    • Configuración manual: En Cherry Studio, vaya a Settings > MCP Servers, seleccione Add > Quick Create, introduzca un nombre, seleccione Streamable HTTP como tipo e introduzca la dirección del Streamable HTTP endpoint en el campo URL. Alternativamente, puede seleccionar Import from JSON y pegar el JSON de configuración desde la página.

    Después de guardar la configuración, su navegador redirigirá automáticamente a la página de autorización OAuth de Alibaba Cloud. Una vez otorgada la autorización, el servicio MCP se iniciará.

    TONGYI Lingma/Cursor/Windsurf/VSCode

    Requisitos previos: Ha instalado Node.js y npm.

    Puede completar la configuración de una de las siguientes maneras:

    • Configuración con un clic (Solo compatible con Cursor): En la página de plantilla de configuración de la consola, haga clic en One-click Configuration for Cursor y siga las indicaciones.

    • Configuración manual: Pegue el JSON de configuración de la página de la consola en el archivo de configuración MCP de su cliente.

    Método de configuración para cada cliente:

    • TONGYI Lingma: Abra el complemento de TONGYI Lingma, haga clic en MCP tools en la página de introducción y haga clic en + en la esquina superior derecha de la ventana emergente para agregar una herramienta manualmente. Introduzca un nombre personalizado, seleccione STDIO como Type, introduzca npx en Command e introduzca mcp-remote-alibaba-cloud "<Streamable HTTP endpoint>" en Arguments.

    • Cursor: En la barra de menú, elija File > Preferences > Cursor Settings > Tools & Integrations, haga clic en Add Custom MCP, pegue el JSON en el archivo mcp.json y guárdelo. El archivo de configuración generalmente se encuentra en ~/.cursor/mcp.json o .cursor/mcp.json en el directorio raíz de su proyecto.

    • Windsurf: Pegue el JSON en ~/.windsurf/mcp.json o .windsurf/mcp.json en el directorio raíz de su proyecto.

    • VSCode: Busque MCP en Settings y agregue la configuración según las indicaciones.

    Después de guardar la configuración, debe completar la autorización OAuth a través de un navegador la primera vez que lo utilice. Si el navegador no se abre automáticamente, reinicie la aplicación.

    Claude Code

    Requisitos previos: Ha instalado Claude Code.

    Ejecute el siguiente comando en su terminal para agregar el servidor MCP. Asegúrese de reemplazar <Streamable HTTP endpoint> con la dirección real obtenida de la consola:

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

    Ejecute el siguiente comando para consultar el servidor MCP agregado:

    claude mcp list

    Si aparece una página de autorización de usuario en su navegador durante la configuración o el uso, haga clic en Authorize.

    Codex

    Requisitos previos: Ha instalado la CLI de Codex.

    Ejecute el siguiente comando en su terminal para agregar el servidor MCP. Asegúrese de reemplazar <Streamable HTTP endpoint> con la dirección real obtenida de la consola:

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

    Ejecute el siguiente comando para consultar el servidor MCP agregado:

    codex mcp list

    Si aparece una página de autorización de usuario en su navegador durante la configuración o el uso, haga clic en Authorize.

    Autenticación con credenciales estáticas

    La autenticación con credenciales estáticas se completa a través del proxy local alibabacloud.mcp-proxy sin redirección del navegador. Este método es adecuado para escenarios como canalizaciones automatizadas, entornos de línea de comandos puros y agentes de IA desatendidos.

    Inicie sesión en la consola del servicio MCP de OpenAPI de Alibaba Cloud, vaya a la página del endpoint del servicio MCP de la edición Core o Custom, haga clic en One-click Configuration y seleccione Static Credential Authentication. Luego, seleccione la pestaña del cliente correspondiente y complete la configuración según la plantilla proporcionada.

    Nota

    Si ha iniciado sesión en Alibaba Cloud CLI localmente (aliyun configure), el proxy leerá automáticamente las credenciales de la CLI. No es necesario configurar la variable de entorno env en la configuración.

    Cherry Studio

    Requisitos previos:

    1. Ha instalado Cherry Studio, Python (>= 3.13) y uv.

    2. Su AccessKey tiene adjunta la directiva del sistema AliyunOpenAPIMCPServerStaticCredentialAccess.

    3. Antes del primer uso, debe ejecutar el comando de verificación previa desde la consola para verificar el estado de autorización de su cuenta. Este comando puede ejecutarse en cualquier dispositivo con navegador y no necesita ser la misma máquina que ejecuta el proxy.

    Puede completar la configuración de la siguiente manera:

    En Cherry Studio, vaya a Settings > MCP Servers > Add > Import from JSON y pegue la configuración. Asegúrese de reemplazar AccessKey ID/Secret con sus claves reales. Si ya ha configurado Alibaba Cloud CLI, puede eliminar el campo env para reutilizar las credenciales locales.

    Después de completar la configuración, reinicie Cherry Studio y envíe una solicitud de prueba, como consultar la lista de instancias ECS en una región. Si la API se invoca según lo esperado, la autenticación con credenciales estáticas habrá sido exitosa.

    TONGYI Lingma/Cursor/Windsurf/VSCode

    Requisitos previos:

    1. Ha instalado TONGYI Lingma/Cursor/Windsurf/VSCode, Python (>= 3.13) y uv.

    2. Su AccessKey tiene adjunta la directiva del sistema AliyunOpenAPIMCPServerStaticCredentialAccess.

    3. Antes del primer uso, debe ejecutar el comando de verificación previa desde la consola para verificar el estado de autorización de su cuenta. Este comando puede ejecutarse en cualquier dispositivo con navegador y no necesita ser la misma máquina que ejecuta el proxy.

    Método de configuración para cada cliente:

    • TONGYI Lingma: En la página de herramientas MCP del complemento, agregue una herramienta manualmente. Seleccione STDIO como Type, introduzca uvx en Command e introduzca alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP endpoint>" --site-type INTL en Arguments. Luego, agregue ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET en las variables de entorno.

    • Cursor: Pegue el JSON en ~/.cursor/mcp.json o .cursor/mcp.json en el directorio raíz del proyecto. Reemplace el ID y el secreto de la AccessKey.

    • Windsurf: Pegue el JSON en ~/.windsurf/mcp.json o .windsurf/mcp.json en el directorio raíz del proyecto. Reemplace el ID y el secreto de la AccessKey.

    • VSCode: Busque MCP en Settings y agregue la configuración según las indicaciones.

    Si ya ha configurado Alibaba Cloud CLI, puede eliminar la configuración de variables de entorno para reutilizar las credenciales locales.

    Después de completar la configuración, guarde los ajustes y reinicie el cliente. Envíe una solicitud de prueba para confirmar que la API se invoca según lo esperado. Esto indica que la autenticación con credenciales estáticas fue exitosa.

    Claude Code

    Requisitos previos:

    1. Ha instalado Claude Code, Python (>= 3.13) y uv.

    2. Su AccessKey tiene adjunta la directiva del sistema AliyunOpenAPIMCPServerStaticCredentialAccess.

    3. Antes del primer uso, debe ejecutar el comando de verificación previa desde la consola para verificar el estado de autorización de su cuenta. Este comando puede ejecutarse en cualquier dispositivo con navegador y no necesita ser la misma máquina que ejecuta el proxy.

    Puede completar la configuración de la siguiente manera:

    Ejecute el siguiente comando en su terminal para agregar el servidor MCP. Asegúrese de reemplazar <Access Key ID>, <Access Key Secret> y <Streamable HTTP endpoint> con sus valores reales.

    Si ya ha configurado Alibaba Cloud CLI, puede eliminar la configuración de variables de entorno para reutilizar las credenciales locales.

    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

    Ejecute el siguiente comando para consultar el servidor MCP agregado:

    claude mcp list

    Codex

    Requisitos previos:

    1. Ha instalado Codex, Python (>= 3.13) y uv.

    2. Su AccessKey tiene adjunta la directiva del sistema AliyunOpenAPIMCPServerStaticCredentialAccess.

    3. Antes del primer uso, debe ejecutar el comando de verificación previa desde la consola para verificar el estado de autorización de su cuenta. Este comando puede ejecutarse en cualquier dispositivo con navegador y no necesita ser la misma máquina que ejecuta el proxy.

    Puede completar la configuración de la siguiente manera:

    Ejecute el siguiente comando en su terminal para agregar el servidor MCP. Asegúrese de reemplazar <Access Key ID>, <Access Key Secret> y <Streamable HTTP endpoint> con sus valores reales.

    Si ya ha configurado Alibaba Cloud CLI, puede eliminar la configuración de variables de entorno para reutilizar las credenciales locales.

    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

    Ejecute el siguiente comando para consultar el servidor MCP agregado:

    codex mcp list

    Uso del servidor MCP

    Después de la configuración, puede utilizar lenguaje natural en su cliente para gestionar recursos en la nube. Para conocer más métodos de integración, consulte More ways to integrate MCP.

    • Edición Core: Describa sus necesidades directamente en lenguaje natural. El LLM encuentra automáticamente las API coincidentes, obtiene sus definiciones de parámetros y ejecuta las llamadas a la API sin que usted tenga que especificar nombres de API o parámetros. Por ejemplo, si introduce "Ayúdame a consultar las instancias ECS en la región China (Hangzhou)", el LLM encontrará e invocará automáticamente la API DescribeInstances.

    • Edición Custom: Las API que configure se exponen directamente como herramientas al LLM, lo que acorta la ruta de llamada al eliminar la necesidad de búsqueda y coincidencia. Cuando varias API tienen funciones similares, la Edición Custom garantiza que el LLM invoque la API específica que usted pretendía.

    Cherry Studio

    1. Desde el menú en el cuadro de entrada de texto, seleccione su servidor MCP.

      Seleccione el servidor openapi-mcp-core y confirme que aparece una marca de verificación verde a la derecha de la entrada, lo cual indica que está habilitado.

    2. Pruebe la funcionalidad de MCP. Por ejemplo, consulte las instancias ECS en una región específica:

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

      Si la selección de la API o la configuración de parámetros son incorrectas, intente optimizar su instrucción. Para la Edición Custom, también puede utilizar el ajuste de MCP para resolver el problema.

    Cursor

    1. Seleccione un modelo y una clave de API. Dado que Cursor tiene requisitos para los proveedores de LLM (consulte Supported providers), debe consultar su documentación al seleccionar un modelo y una clave de API. Este ejemplo utiliza los valores predeterminados.

    2. En el cuadro de diálogo de Cursor, haga clic en Add Context y seleccione su servidor MCP.

    3. En el cuadro de diálogo, introduzca una consulta en lenguaje natural para probar la funcionalidad de MCP, como "Ayúdame a consultar el número de instancias ECS en la región China (Chengdu) y muestra solo el recuento de instancias". Después de presionar Enter, haga clic en Run tool según se le indique para continuar.

    4. Consulte el resultado de la ejecución de MCP. Si la selección de la API o la configuración de parámetros son incorrectas, intente optimizar su instrucción. Para la Edición Custom, también puede utilizar el ajuste de MCP para resolver el problema.

    TONGYI Lingma

    1. En TONGYI Lingma, seleccione un agent e introduzca su instrucción. Por ejemplo, puede consultar la lista de instancias ECS en la región China (Chengdu) y establecer x_mcp_region_id.

    2. Siga las indicaciones en TONGYI Lingma para ejecutar la herramienta MCP.

    3. Consulte el resultado. Si la selección de la API o la configuración de parámetros son incorrectas, intente optimizar su instrucción. Para la Edición Custom, también puede utilizar el ajuste de MCP para resolver el problema.

    Cline

    1. En la ventana de diálogo de Cline, introduzca una consulta en lenguaje natural para probar la funcionalidad de MCP, como "Ayúdame a consultar el número de instancias ECS en la región China (Chengdu)".

      Cline selecciona automáticamente la herramienta DescribeInstances del servidor MCP configurado y extrae el valor para el parámetro RegionId de su entrada.

    2. Consulte el resultado de la ejecución de MCP. Si la selección de la API o la configuración de parámetros son incorrectas, intente optimizar su instrucción. Para la Edición Custom, también puede utilizar el ajuste de MCP para resolver el problema.

    Ajuste de MCP (solo Custom Edition)

    La Core Edition utiliza herramientas integradas para gestionar automáticamente las búsquedas y llamadas a API. No admite ajustes.

    Es posible que el modelo de lenguaje grande (LLM) seleccione una API incorrecta o pase parámetros erróneos. Si esto ocurre, modifique la descripción general, la descripción y las descripciones de los parámetros de solicitud de la API en el servidor. Esto ayuda al LLM a comprender e invocar la API con mayor precisión.

    Ejemplo 1: Errores o datos inexactos al operar con recursos fuera de la región cn-hangzhou

    Internamente, MCP utiliza x_mcp_region_id para cambiar el Endpoint. Si el LLM no identifica en la entrada que debe pasar x_mcp_region_id, operará sobre los recursos de la región cn-hangzhou de forma predeterminada.

    Resuelva este problema mediante uno de los dos métodos siguientes:

    • Indique explícitamente al LLM que establezca x_mcp_region_id en la consulta.

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

    • Ajuste la descripción general de la API o la descripción del parámetro de solicitud RegionId en el servidor MCP.

      Por ejemplo, agregue "Pase la región especificada por el usuario a x_mcp_region_id" a la descripción general de la API. O bien, agregue "Si existe el parámetro RegionId, páselo junto con x_mcp_region_id" a la descripción de RegionId.

      Pasos:

      1. Vaya a Custom API MCP SERVER y haga clic en Edit en la columna Actions del servicio MCP objetivo.

      2. Seleccione la API que desea ajustar y haga clic en Edit en su columna Actions.

      3. Modifique la descripción general, la descripción de la solicitud de la API o las descripciones de los parámetros de la API.

      4. Guarde los cambios. A continuación, desconéctese y vuelva a conectarse al servicio MCP desde el cliente para aplicarlos.

    Ejemplo 2: Eliminación de parámetros opcionales de la API

    Algunos parámetros opcionales no se utilizan en escenarios específicos. Elimine estos parámetros en el servidor MCP. Una vez eliminados, el LLM los ignorará al generar parámetros. Esto reduce la tasa de errores y disminuye el consumo de tokens.

    Control de acceso a MCP

    image

    Una vez que un agente de IA se integra con el servidor MCP de OpenAPI, el agente no tiene permiso para acceder a los recursos en la nube. Un usuario debe autorizar al agente para que opere en su nombre. Por ejemplo, un cliente puede iniciar un proceso OAuth. El agente obtiene acceso temporal solo después de que el usuario concede la autorización. Todas las operaciones requieren autorización del usuario. El agente solo puede realizar las tareas que estén dentro de los permisos del usuario. Esto implementa el principio de privilegio mínimo. Además, ActionTrail registra la identidad del usuario que realmente realiza las operaciones.

    Escenarios: Agentes de cliente como CherryStudio, TONGYI Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope y LangGraph, o escenarios donde un agente necesita actuar en nombre de un usuario.

    Más formas de integrar MCP

    • Configure una aplicación OAuth personalizada en Dify para integrarla con el servidor MCP de OpenAPI. Para más información, consulte Integrate OpenAPI MCP Server in Dify.

    • En un agente personalizado, utilice el SDK oficial de MCP para completar el proceso de autorización OAuth personalizado e integrar marcos de trabajo de agentes principales. Para más información, consulte Integrate OpenAPI MCP Server in an agent.

    Preguntas frecuentes

    ¿Se pueden invocar todas las API de Tools desde el cliente MCP?

    No necesariamente. El éxito de una llamada a API depende de los permisos del usuario de RAM. Este puede ser el usuario que inicia la autenticación OAuth o el usuario asociado a la AccessKey (AK) para la autenticación. Si un usuario de RAM carece de permiso para invocar una API, el modelo de lenguaje grande (LLM) tampoco podrá hacerlo.

    Solución: Otorgue los permisos de API necesarios al usuario de RAM. Para más información, consulte Manage RAM user permissions.

    Importante

    Para evitar que el LLM invoque API de eliminación de recursos debido a una mala interpretación, lo cual podría afectar sus servicios, no otorgue permisos de eliminación de recursos al usuario de RAM.

    Permiso denegado al crear un servidor MCP como usuario de RAM

    Solución:

    • Otorgue la directiva del sistema AliyunOpenAPIMCPServerFullAccess al usuario de RAM. Para más información, consulte Manage RAM user permissions.

    • Otorgue una directiva personalizada al usuario de RAM:

      1. Utilice una cuenta de administrador para crear una directiva personalizada en la consola de RAM. Para más información, consulte Create a custom policy.

        A continuación se muestra el contenido de la directiva:

        Haga clic para ver la directiva para operaciones del servidor MCP

        Esta directiva incluye permisos para crear, actualizar, consultar y eliminar servidores MCP, así como para consultar herramientas del sistema MCP.

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

      2. Utilice una cuenta de administrador para otorgar el permiso personalizado al usuario de RAM objetivo. Para más información, consulte Manage RAM user permissions.

    Si se expone un endpoint de conexión del servidor MCP, ¿pueden otros hacer un uso indebido?

    No. Cuando un cliente utiliza el endpoint, la autenticación OAuth inicia un proceso de autorización. Este proceso requiere que el usuario inicie sesión y conceda acceso. El sistema comprueba si la cuenta de Alibaba Cloud del usuario de RAM coincide con la cuenta de Alibaba Cloud del servidor MCP. El acceso se concede únicamente si coinciden. En el caso de la autenticación con credenciales estáticas, el acceso está restringido por los permisos del usuario de RAM asociado a la AK. Una parte no autorizada no puede exceder este alcance de permisos.

    ¿Cómo elegir entre autenticación con credenciales estáticas y autenticación OAuth?

    Elija el método de autenticación que se adapte a su caso de uso:

    • Autenticación OAuth: Adecuada para escenarios de clientes de escritorio que implican interacción con el navegador. Los permisos están vinculados al usuario y el token tiene una vida corta para mayor seguridad. Utilice OAuth para el desarrollo diario y operaciones exploratorias.

    • Autenticación con credenciales estáticas (AK): Adecuada para escenarios donde la redirección del navegador resulta inconveniente, como canalizaciones automatizadas, entornos exclusivos de línea de comandos (servidores sin interfaz gráfica de usuario (GUI)) e integraciones de agentes de IA desatendidas. Los permisos están vinculados a la identidad de RAM asociada a la AK. Debe gestionar la seguridad de las credenciales por su cuenta.

    ¿Qué debo hacer si se filtra un AccessKey Secret?

    1. Deshabilite o elimine inmediatamente la AccessKey en la consola de RAM.

    2. Cree una nueva AccessKey y actualice la configuración de su cliente.

    3. Revise los registros de ActionTrail correspondientes al periodo de la filtración para identificar cualquier llamada no autorizada.