Alvos dos servidores MCP

Os servidores MCP fornecem ferramentas locais, acesso a dados ou funções personalizadas para suas interações com modelos e agentes no Bedrock AgentCore. No Bedrock AgentCore, você pode definir um servidor MCP pré-configurado como destino ao criar um gateway.

Os servidores MCP hospedam ferramentas, solicitações e recursos que os agentes podem descobrir e usar. No Bedrock AgentCore, você usa um gateway para associar alvos a esses recursos e conectá-los ao tempo de execução do seu agente. Você se conecta a servidores MCP externos por meio da SynchronizeGatewayTargets API que executa handshakes de protocolo e indexa os recursos disponíveis. Para obter mais informações sobre como instalar e usar servidores MCP, consulte Amazon Bedrock AgentCore MCP Server: codificação Vibe com seu assistente de codificação.

Principais considerações e limitações

Modo de listagem

ListingMode pode ser definido como DYNAMIC ou DEFAULT para destinos do servidor MCP.

Sincronização implícita

Para alvos no modo DEFAULT, CreateGatewayTarget UpdateGatewayTarget as operações acionam automaticamente a descoberta e a indexação de capacidades. Quando qualquer operação é chamada, o Gateway busca as ferramentas disponíveis usando o tools/list recurso do MCP, solicita o usoprompts/list, os recursos usando e. resources/list e resources/templates/list adiciona os recursos retornados ao catálogo unificado.

Sincronização explícita

Os catálogos de recursos para destinos no modo DEFAULT podem ser atualizados manualmente chamando a API. SynchronizeGatewayTargets Quando chamado, ele atualiza a lista de recursos disponíveis do Gateway. Você deve chamar a API sempre que a ferramenta, o prompt e as definições de recursos de um servidor MCP mudarem.

A sincronização é um mecanismo essencial para manter catálogos de recursos precisos ao integrar servidores MCP. A sincronização implícita ocorre automaticamente durante a criação e as atualizações do destino, em que o Gateway imediatamente descobre e indexa ferramentas, solicitações e recursos do servidor MCP para garantir que os recursos estejam disponíveis para pesquisa semântica e listagem unificada. A sincronização explícita é realizada sob demanda por meio da SynchronizeGatewayTargets API, permitindo a descoberta do catálogo de recursos MCP quando os servidores MCP modificam seus recursos de forma independente.

Quando ligar SynchronizeGatewayTargets

Sempre que um destino de servidor MCP tiver seu Modo de Listagem definido como DEFAULT, use a SynchronizeGatewayTargets API depois que ferramentas, solicitações ou recursos forem adicionados, removidos ou modificados. Como o Gateway pré-computa incorporações vetoriais para pesquisa semântica e mantém catálogos de recursos normalizados, a sincronização é necessária para garantir que seus usuários possam descobrir e invocar as ferramentas, solicitações e recursos mais recentes disponíveis.

Como chamar a API

Faça uma solicitação PUT para /gateways/ {gatewayIdentifier} /sincronize com o ID de destino no corpo da solicitação. A API retorna uma resposta 202 imediatamente e processa a sincronização de forma assíncrona. Monitore o status do alvo GetGatewayTarget para acompanhar o progresso da sincronização, pois a operação pode levar vários minutos para grandes conjuntos de recursos.

Estratégia de autorização

Há suporte para os seguintes tipos de estratégia de autorização.

Considerações de configuração para destinos do servidor MCP

O seguinte deve ser configurado.

Conectando-se a um servidor OAuth-protected MCP usando o fluxo do Código de Autorização

Para oferecer suporte ao tipo de concessão do Código de Autorização (OAuth de três pernas) com destinos de servidor MCP, o Amazon Bedrock AgentCore Gateway fornece dois métodos para a criação de destinos.

Sincronização implícita durante a criação do alvo do servidor MCP

Com esse método, o usuário administrador conclui o fluxo do código de autorização durante CreateGatewayTarget SynchronizeGatewayTargets as operações ou usando a URL de autorização retornada na resposta. UpdateGatewayTarget Isso permite que o Amazon Bedrock AgentCore Gateway descubra e armazene em cache as ferramentas do servidor MCP antecipadamente.

Forneça o esquema antecipadamente durante a criação do alvo do servidor MCP

Com esse método, os usuários administradores fornecem o esquema da ferramenta diretamente durante CreateGatewayTarget nossas UpdateGatewayTarget operações usando o mcpToolSchema campo, em vez de o Amazon Bedrock AgentCore Gateway buscá-las dinamicamente no servidor MCP. O Amazon Bedrock AgentCore Gateway analisa o esquema fornecido e armazena em cache as definições da ferramenta.

Vinculação de sessão de URL

A vinculação da sessão de URL de autorização do OAuth 2.0 verifica se o usuário que iniciou a solicitação de autorização do OAuth é o mesmo usuário que concedeu o consentimento. Depois que o usuário conclui o consentimento, o navegador redireciona de volta para um URL de retorno configurado no destino com um URI de sessão exclusivo. O aplicativo é então responsável por chamar a CompleteResourceTokenAuthAPI, apresentando a identidade do usuário e o URI da sessão. O Amazon Bedrock AgentCore Identity valida que o usuário que iniciou o fluxo é o mesmo usuário que o concluiu antes de trocar o código de autorização por um token de acesso.

Isso evita um cenário em que um usuário acidentalmente compartilhe o URL de autorização e outra pessoa conclua o consentimento, o que concederia tokens de acesso à parte errada. O URL de autorização e o URI da sessão são válidos apenas por 10 minutos, limitando ainda mais a janela para uso indevido. A vinculação de sessão se aplica durante a criação do destino (sincronização implícita) e durante a invocação da ferramenta.

Configurar permissões do

A função do IAM que você usa para criar, atualizar ou sincronizar alvos de servidores MCP deve ter as permissões mostradas no exemplo a seguir.

{
"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/*"
        }
    ]
}