Integración del Protocolo de contexto modelo (MCP)

Un punto final de servidor MCP con el acceso adecuado.

Credenciales de autenticación para el servidor MCP, si son necesarias. Para obtener más información, consulte Prepare la configuración y la autenticación del servidor MCP.

Una suscripción a Amazon Quick Enterprise.

Si se conecta a un servidor MCP privado, una conexión Amazon Quick VPC activa que tenga acceso de red al servidor MCP. Para obtener más información, consulte Configuración de conexiones de VPC en Amazon Quick Sight.

El conector no se detecta, pero se produce un error al publicarlo Creation failed: este error suele indicar que una o más definiciones de herramientas de la tools/list respuesta del servidor MCP contienen una no válidainputSchema. Amazon Quick valida cada herramienta con JSON inputSchema Schema Draft 7 o una versión posterior durante la fase de publicación.

La causa más común es la obsoleta sintaxis del Borrador 3, donde required hay un booleano dentro de la definición de una propiedad (por ejemplo,). "required": true En el borrador 7 del esquema de JSON y versiones posteriores, required debe haber una matriz de nombres de propiedades en la raíz del esquema, similar a una de ellas. properties

Actualice las definiciones de las herramientas para utilizar el formato correcto y vuelva a implementar el servidor MCP. Tras volver a desplegarlo, elimine el conector defectuoso y cree uno nuevo para volver a activar la detección y la publicación.

En el siguiente ejemplo, se muestra una sintaxis de Draft 3 incorrecta:

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number",
      "required": true
    }
  }
}

El siguiente ejemplo muestra la sintaxis correcta del Borrador 7:

{
  "type": "object",
  "properties": {
    "logNumber": {
      "type": "string",
      "description": "The permit log number"
    }
  },
  "required": ["logNumber"]
}

Algunas bibliotecas de marcos y generadores de código de MCP emiten la sintaxis del Borrador 3 de forma predeterminada. Consulte la documentación de su marco para ver la opción que selecciona la versión de salida del esquema JSON. También puede validar sus esquemas con cualquier validador de JSON Schema Draft 7 antes de implementarlos. Para obtener más información sobre inputSchema los requisitos, consulte las herramientas de la especificación del protocolo Model Context.

También puede observar que la creación del conector se bloquea de dos a cinco minutos antes de que se produzca un error. El tiempo transcurrido refleja los reintentos internos durante la fase de publicación, no el tiempo de espera de la red. La solución es la misma: compruebe si las inputSchema definiciones de las herramientas cumplen con el borrador 7 del esquema JSON.

La conexión de VPC no aparece en el menú desplegable Tipo de conexión o se produce un error al crear el MCP inmediatamente después de seleccionarlo. Es posible que la conexión de VPC aparezca en el menú desplegable antes de que se complete el aprovisionamiento. Espere a que la conexión de VPC aparezca como disponible en la página de administración de Amazon Quick antes de crear una integración de MCP con ella. Para obtener más información, consulte Configuración de conexiones de VPC en Amazon Quick Sight.

Se produce un error en la creación del MCP porque no se puede resolver el nombre de host del servidor MCP. Amazon Quick no utiliza el solucionador de DNS de VPC predeterminado para las integraciones de MCP. Debe rellenar el campo de puntos finales de la resolución de DNS de la conexión de VPC con las direcciones IP de los puntos de conexión entrantes de Route 53 Resolver que puedan resolver el nombre de host del servidor MCP. Este requisito se aplica tanto a los nombres de host privados como a los nombres de host públicos que desee resolver en una dirección privada desde la VPC, como los puntos de enlace ubicados frente a una zona alojada privada de AWS PrivateLink Route 53 o una zona alojada privada. Sin estos puntos finales de resolución, el nombre de host del servidor MCP no se puede resolver y se produce un error al crear la integración. Para obtener más información, consulte Configuración de conexiones de VPC en Amazon Quick Sight.

No se puede acceder al servidor MCP desde la conexión de VPC: el tráfico de Amazon Quick a su servidor MCP se origina en las subredes que seleccionó durante la configuración de la conexión de VPC. Confirme que las tablas de enrutamiento, las ACL de red y los grupos de seguridad permiten el tráfico entre esas subredes y el punto final del servidor MCP. Para obtener instrucciones generales sobre redes de VPC, consulte. Configuración de conexiones de VPC en Amazon Quick Sight

La autenticación falla cuando usa un servidor MCP privado: cuando se conecta a un servidor MCP privado a través de una conexión de VPC, los puntos finales de OAuth utilizados por el servidor MCP deben seguir siendo accesibles a través de la Internet pública. Esto se aplica tanto a la autenticación de usuarios (puntos finales de autorización y token) como a la autenticación de servicios (punto final simbólico). No se admiten los proveedores de OAuth privados. Confirme que las direcciones URL de OAuth que su servidor MCP devuelve en sus metadatos de recursos protegidos se resuelven a través de la Internet pública.

AADSTS9010010— el punto final de la versión 2.0 rechaza el parámetro de recurso: Amazon Quick envía un resource parámetro en las solicitudes de OAuth según lo exige la especificación MCP (RFC 8707). El punto de conexión Entra ID v2.0 rechaza las solicitudes que incluyen tanto un parámetro como valores. resource scope Para resolver este error, configura el registro de la aplicación para que utilice los puntos finales de OAuth Entra ID v1.0 y accessTokenAcceptedVersion establézcalos en el manifiesto de la aplicación. 2

AADSTS90009— la aplicación solicita un token para sí misma: cuando utilizas la autenticación de usuario (flujo de códigos de autorización) y el cliente OAuth y el recurso MCP se resuelven en la misma aplicación de Entra ID, Entra ID bloquea la solicitud. Cree dos registros de aplicaciones independientes: una aplicación cliente para Amazon Quick y una aplicación de recursos para el servidor MCP. Este problema no afecta a la autenticación del servicio (flujo de credenciales del cliente), donde funciona el registro de una sola aplicación.

Las operaciones de MCP tienen un tiempo de espera fijo de 60 segundos. Las operaciones que superan este límite fallan automáticamente y se produce un error HTTP 424.

En el caso de los servidores MCP a los que se accede a través de una conexión de VPC, se debe poder acceder a los puntos finales de OAuth utilizados por el servidor MCP a través de la Internet pública. Esto se aplica tanto a la autenticación de usuarios como a la autenticación de servicios. No se admiten los proveedores de OAuth privados.

Los encabezados HTTP personalizados no se admiten en las operaciones de MCP. Solo se transmiten los encabezados del sistema estándar.

Las listas de herramientas permanecen estáticas después del registro inicial. Para detectar los cambios en las herramientas del servidor, debe eliminar la integración y volver a crearla.

Es posible que se produzca un error en la creación del conector si el URI de devolución de llamada de Amazon Quick no figura en la lista de permitidos de proveedores externos.

Los problemas de conectividad del servidor provocan un fallo inmediato sin necesidad de volver a intentarlo.

Step-up no se admite la autorización. Si un servidor MCP requiere ámbitos adicionales después de la autorización inicial (HTTP 403 coninsufficient_scope), debe volver a autorizar toda la conexión. Las actualizaciones incrementales de permisos no están disponibles.

El manejo del alcance tiene las siguientes limitaciones:

Solo se admite el registro dinámico de clientes (DCR) para el registro automático de clientes. No se admiten los documentos de metadatos de ID de cliente.

Well-known La detección de URI utiliza únicamente la ruta raíz del servidor. Path-specific no se admiten las ubicaciones de metadatos (detección de inserciones de rutas). Esta limitación puede impedir que se descubran servidores que solo sirvan metadatos en URI de rutas específicas.