As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Alvos de 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 um 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 destinos 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 alvos do servidor MCP.

Sincronização implícita

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

Sincronização explícita

Os catálogos de recursos para Targets 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 alvo, em que o Gateway descobre e indexa imediatamente 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 do 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 PADRÃO, use a SynchronizeGatewayTargets API depois que ferramentas, solicitações ou recursos forem adicionados, removidos ou modificados. Como o Gateway pré-calcula 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

Os seguintes tipos de estratégia de autorização são suportados.

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

O seguinte deve ser configurado.

On-behalf-of considerações sobre troca de tokens

As limitações a seguir se aplicam quando você usa a troca de tokens (o tipo de TOKEN_EXCHANGE concessão) como autorização de saída para um alvo de servidor MCP:

Protegendo o estado da solicitação para elicitação e amostragem (versão 2026-07-28 e posterior)

Na versão 2026-07-28 e posterior, a elicitação e a amostragem usam o padrão de várias solicitações de ida e volta (MRTR). Seu alvo de servidor MCP gera o requestState valor em um input_required resultado; o gateway trata esse valor como opaco. O gateway não armazena requestState o. Ele mantém o valor na memória somente enquanto o encaminha inalterado entre o cliente e o destino do servidor MCP e o descarta quando a solicitação é concluída.

AgentCore O gateway e seu servidor MCP de destino compartilham a responsabilidade de proteger o estado da solicitação:

Para proteger o estado da solicitação, siga as orientações na especificação do MCP. Criptografe ou assine o estado (por exemplo, com AES-GCM ou com um JWT assinado) para garantir confidencialidade e integridade. Vincule o estado específico do usuário ao usuário de origem, expire o estado e trate quaisquer valores de estado de texto sem formatação como entrada não confiável. Para obter mais informações, consulte Várias solicitações de ida e volta no site do Model Context Protocol.

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 etapas) 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 CreateGatewayTargetUpdateGatewayTarget, ou SynchronizeGatewayTargets operações usando o URL de autorização retornado na resposta. Isso permite que o Amazon Bedrock AgentCore Gateway descubra e armazene em cache as ferramentas do servidor MCP com antecedência.

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á-los dinamicamente do 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 de sessão do 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 CompleteResourceTokenAuth API, 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 alvo (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 destinos 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/*"
        }
    ]
}