Obiettivi dei server MCP

I server MCP forniscono strumenti locali, accesso ai dati o funzioni personalizzate per le interazioni con modelli e agenti in Bedrock. AgentCore In Bedrock AgentCore, è possibile definire un server MCP preconfigurato come destinazione durante la creazione di un gateway.

I server MCP ospitano strumenti, prompt e risorse che gli agenti possono scoprire e utilizzare. In Bedrock AgentCore, si utilizza un gateway per associare gli obiettivi a queste funzionalità e collegarli al runtime dell'agente. Ci si connette a server MCP esterni tramite l'SynchronizeGatewayTargetsAPI che esegue gli handshake del protocollo e indicizza le funzionalità disponibili. Per ulteriori informazioni sull'installazione e l'utilizzo dei server MCP, consulta Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant.

Considerazioni e limitazioni principali

Modalità di quotazione

ListingMode può essere impostata come DYNAMIC o DEFAULT per le destinazioni del server MCP.

Sincronizzazione implicita

Per le destinazioni in modalità DEFAULT, UpdateGatewayTarget le operazioni attivano automaticamente l'individuazione CreateGatewayTarget e l'indicizzazione delle funzionalità. Quando viene richiamata una delle due operazioni, Gateway recupera gli strumenti disponibili utilizzando le tools/list funzionalità di MCP, richiede l'utilizzo prompts/list delle risorse resources/list e resources/templates/list aggiunge le funzionalità restituite al catalogo unificato.

Sincronizzazione esplicita

I cataloghi di funzionalità per Targets in modalità DEFAULT possono essere aggiornati manualmente chiamando l'API. SynchronizeGatewayTargets Quando viene chiamato, aggiorna l'elenco delle funzionalità disponibili del Gateway. È necessario chiamare l'API ogni volta che le definizioni degli strumenti, dei prompt e delle risorse di un server MCP cambiano.

La sincronizzazione è un meccanismo fondamentale per mantenere cataloghi di funzionalità accurati durante l'integrazione dei server MCP. La sincronizzazione implicita avviene automaticamente durante la creazione e gli aggiornamenti degli obiettivi, in cui Gateway rileva e indicizza immediatamente gli strumenti, i prompt e le risorse del server MCP per garantire la disponibilità di funzionalità per la ricerca semantica e l'elenco unificato. La sincronizzazione esplicita viene eseguita su richiesta tramite l'SynchronizeGatewayTargetsAPI, consentendo l'individuazione del catalogo delle funzionalità MCP quando i server MCP modificano in modo indipendente le proprie funzionalità.

Quando chiamare SynchronizeGatewayTargets

Ogni volta che la modalità di elenco di una destinazione del server MCP è impostata su DEFAULT, utilizzate l'SynchronizeGatewayTargetsAPI dopo aver aggiunto, rimosso o modificato strumenti, istruzioni o risorse. Poiché Gateway precalcola gli incorporamenti vettoriali per la ricerca semantica e mantiene cataloghi di funzionalità normalizzati, la sincronizzazione è necessaria per garantire che gli utenti possano scoprire e richiamare gli strumenti, i prompt e le risorse più recenti disponibili.

Come chiamare l'API

Effettua una richiesta PUT su /gateways/ {gatewayIdentifier} /sincronizza con l'ID di destinazione nel corpo della richiesta. L'API restituisce immediatamente una risposta 202 ed elabora la sincronizzazione in modo asincrono. Monitora lo stato dell'obiettivo GetGatewayTarget per tenere traccia dell'avanzamento della sincronizzazione, poiché l'operazione può richiedere diversi minuti per set di funzionalità di grandi dimensioni.

Strategia di autorizzazione

Sono supportati i seguenti tipi di strategia di autorizzazione.

Considerazioni sulla configurazione per le destinazioni dei server MCP

È necessario configurare quanto segue.

Connessione a un server OAuth-protected MCP tramite il flusso del codice di autorizzazione

Per supportare il tipo di concessione del codice di autorizzazione (OAuth a tre gambe) con destinazioni server MCP, Amazon Bedrock AgentCore Gateway offre due metodi per la creazione di obiettivi.

Sincronizzazione implicita durante la creazione degli obiettivi del server MCP

Con questo metodo, l'utente amministratore completa il flusso del codice di autorizzazione durante CreateGatewayTarget o SynchronizeGatewayTargets le operazioni utilizzando l'URL di autorizzazione restituito nella risposta. UpdateGatewayTarget Ciò consente ad Amazon Bedrock AgentCore Gateway di rilevare e memorizzare nella cache gli strumenti del server MCP in anticipo.

Fornisci lo schema in anticipo durante la creazione del target del server MCP

Con questo metodo, gli utenti amministratori forniscono lo schema dello strumento direttamente durante CreateGatewayTarget o durante UpdateGatewayTarget le operazioni mcpToolSchema sul campo, anziché che Amazon Bedrock AgentCore Gateway li recuperi dinamicamente dal server MCP. Amazon Bedrock AgentCore Gateway analizza lo schema fornito e memorizza nella cache le definizioni degli strumenti.

Associazione di sessioni URL

L'associazione della sessione con l'URL di autorizzazione OAuth 2.0 verifica che l'utente che ha avviato la richiesta di autorizzazione OAuth sia lo stesso utente che ha concesso il consenso. Dopo che l'utente ha completato il consenso, il browser reindirizza nuovamente a un URL di ritorno configurato sulla destinazione con un URI di sessione univoco. L'applicazione è quindi responsabile della chiamata all'CompleteResourceTokenAuthAPI, presentando sia l'identità dell'utente che l'URI della sessione. Amazon Bedrock AgentCore Identity verifica che l'utente che ha avviato il flusso sia lo stesso utente che lo ha completato prima di scambiare il codice di autorizzazione con un token di accesso.

In questo modo si evita uno scenario in cui un utente condivida accidentalmente l'URL di autorizzazione e qualcun altro fornisca il consenso, il che concederebbe i token di accesso alla parte sbagliata. L'URL di autorizzazione e l'URI della sessione sono validi solo per 10 minuti, limitando ulteriormente la finestra di utilizzo improprio. L'associazione della sessione si applica durante la creazione del target (sincronizzazione implicita) e durante la chiamata dello strumento.

Configurazione delle autorizzazioni

Il ruolo IAM utilizzato per creare, aggiornare o sincronizzare gli obiettivi dei server MCP deve avere le autorizzazioni mostrate nell'esempio seguente.

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