Destinos de servidores MCP

Los servidores MCP proporcionan herramientas locales, acceso a datos o funciones personalizadas para sus interacciones con los modelos y agentes de Bedrock. AgentCore En Bedrock AgentCore, puede definir un servidor MCP preconfigurado como destino al crear una puerta de enlace.

Los servidores MCP alojan herramientas, mensajes y recursos que los agentes pueden descubrir y utilizar. En Bedrock AgentCore, se utiliza una puerta de enlace para asociar los objetivos con estas capacidades y conectarlos al entorno de ejecución de su agente. Te conectas con servidores MCP externos a través de la SynchronizeGatewayTargets API que realiza protocolos e indexa las capacidades disponibles. Para obtener más información sobre la instalación y el uso de servidores MCP, consulte Amazon Bedrock AgentCore MCP Server: Vibe codificando con su asistente de codificación.

Consideraciones y limitaciones clave

Modo de listado

ListingMode se puede configurar como DYNAMIC o DEFAULT para los destinos del servidor MCP.

Sincronización implícita

Para los objetivos en modo DEFAULT, CreateGatewayTarget y UpdateGatewayTarget las operaciones activan automáticamente la detección y la indexación de capacidades. Cuando se ejecuta cualquiera de las dos operaciones, Gateway busca las herramientas disponibles utilizando la tools/list capacidad de MCP, solicita el usoprompts/list, los recursos resources/list yresources/templates/list, y agrega las capacidades devueltas al catálogo unificado.

Sincronización explícita

Los catálogos de capacidades de los objetivos en el modo DEFAULT se pueden actualizar manualmente llamando a la SynchronizeGatewayTargets API. Cuando se llama, actualiza la lista de capacidades disponibles de Gateway. Debe llamar a la API cada vez que cambien las definiciones de recursos, herramientas o avisos de un servidor MCP.

La sincronización es un mecanismo fundamental para mantener catálogos de capacidades precisos al integrar los servidores MCP. La sincronización implícita se produce automáticamente durante la creación y las actualizaciones del destino, por lo que Gateway descubre e indexa inmediatamente las herramientas, las solicitudes y los recursos del servidor MCP para garantizar que estén disponibles las capacidades de búsqueda semántica y listado unificado. La sincronización explícita se realiza bajo demanda a través de la SynchronizeGatewayTargets API, lo que permite descubrir el catálogo de capacidades del MCP cuando los servidores MCP modifican sus capacidades de forma independiente.

¿Cuándo llamar SynchronizeGatewayTargets

Siempre que el destino de un servidor MCP tenga su modo de listado establecido en DEFAULT, utilice la SynchronizeGatewayTargets API después de agregar, eliminar o modificar herramientas, solicitudes o recursos. Dado que Gateway calcula previamente las incrustaciones vectoriales para la búsqueda semántica y mantiene los catálogos de capacidades normalizados, la sincronización es necesaria para garantizar que los usuarios puedan descubrir e invocar las últimas herramientas, indicaciones y recursos disponibles.

¿Cómo llamar a la API

Realiza una solicitud PUT a /gateways/ {GatewayIdentifier} /sincronízala con el ID de destino en el cuerpo de la solicitud. La API devuelve una respuesta 202 de forma inmediata y procesa la sincronización de forma asíncrona. Supervise el estado del objetivo GetGatewayTarget para realizar un seguimiento del progreso de la sincronización, ya que la operación puede tardar varios minutos en el caso de conjuntos de gran capacidad.

Estrategia de autorización

Se admiten los siguientes tipos de estrategia de autorización.

Consideraciones de configuración para los destinos del servidor MCP

Debe configurarse lo siguiente.

Conexión a un servidor OAuth-protected MCP mediante el flujo de códigos de autorización

Para admitir el tipo de concesión del código de autorización (OAuth de tres fases) con los destinos de los servidores MCP, Amazon Bedrock AgentCore Gateway proporciona dos métodos para la creación de objetivos.

Sincronización implícita durante la creación del destino del servidor MCP

Con este método, el usuario administrador completa el flujo de códigos de autorización durante CreateGatewayTarget SynchronizeGatewayTargets las operaciones o las operaciones utilizando la URL de autorización que se muestra en la respuesta. UpdateGatewayTarget Esto permite a Amazon Bedrock AgentCore Gateway detectar y almacenar en caché las herramientas del servidor MCP por adelantado.

Proporcione el esquema por adelantado durante la creación del destino del servidor MCP

Con este método, los usuarios administradores proporcionan el esquema de la herramienta directamente durante UpdateGatewayTarget las operaciones CreateGatewayTarget o mediante el mcpToolSchema campo, en lugar de que Amazon Bedrock AgentCore Gateway los obtenga dinámicamente desde el servidor MCP. Amazon Bedrock AgentCore Gateway analiza el esquema proporcionado y guarda en caché las definiciones de las herramientas.

Enlace de sesión URL

El enlace de sesión con la URL de autorización de OAuth 2.0 verifica que el usuario que inició la solicitud de autorización de OAuth sea el mismo usuario que otorgó el consentimiento. Una vez que el usuario dé su consentimiento, el navegador lo redirige de nuevo a una URL de retorno configurada en el destino con una URI de sesión única. A continuación, la aplicación se encarga de llamar a la CompleteResourceTokenAuthAPI y presenta tanto la identidad del usuario como el URI de la sesión. Amazon Bedrock AgentCore Identity valida que el usuario que inició el flujo es el mismo usuario que lo completó antes de intercambiar el código de autorización por un token de acceso.

Esto evita que un usuario comparta accidentalmente la URL de autorización y otra persona dé su consentimiento, lo que daría los tokens de acceso a la parte equivocada. La URL de autorización y el URI de la sesión solo son válidos durante 10 minutos, lo que limita aún más el período de uso indebido. El enlace de sesión se aplica durante la creación del destino (sincronización implícita) y durante la invocación de la herramienta.

Configurar los permisos

La función de IAM que se utiliza para crear, actualizar o sincronizar los destinos de los servidores MCP debe tener los permisos que se muestran en el siguiente ejemplo.

{
"Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:CreateGateway",
                "bedrock-agentcore:GetGateway",
                "bedrock-agentcore:CreateGatewayTarget",
                "bedrock-agentcore:GetGatewayTarget",
                "bedrock-agentcore:SynchronizeGatewayTargets",
                "bedrock-agentcore:UpdateGatewayTarget"
            ],
            "Resource": "arn:aws:bedrock-agentcore:*:*:*gateway*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:CreateWorkloadIdentity",
                "bedrock-agentcore:GetWorkloadAccessToken",
                "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
                "bedrock-agentcore:GetResourceOauth2Token",
                "bedrock-agentcore:GetResourceApiKey",
                "bedrock-agentcore:CompleteResourceTokenAuth",
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:EnableKeyRotation",
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:GenerateDataKey*",
                "kms:ReEncrypt*",
                "kms:CreateAlias",
                "kms:DisableKey",
                "kms:*"
            ],
            "Resource": "arn:aws:kms:*:123456789012:key/*"
        }
    ]
}