View a markdown version of this page

Contratto di protocollo MCP - Amazon Bedrock AgentCore
Requisiti di implementazione del protocolloRequisiti del contenitoreRequisiti del percorsoRisposte di autenticazione OAuth

Contratto di protocollo MCP

Comprendi i requisiti per l'implementazione del Model Context Protocol (MCP) in modo che gli agenti possano chiamare strumenti e server di agenti.

Per un esempio di codice, consulta Distribuire i server MCP in Runtime. AgentCore

Requisiti di implementazione del protocollo

Il server MCP deve implementare questi requisiti di protocollo specifici:

  • Trasporto: il Streamable-http trasporto è obbligatorio. Per impostazione predefinita, utilizza la modalità stateless (stateless_http=True) per la compatibilità con la gestione delle sessioni e il bilanciamento AWS del carico.

  • Gestione della sessione: la piattaforma aggiunge automaticamente l'Mcp-Session-Idintestazione per l'isolamento della sessione. In modalità stateless, i server devono supportare il funzionamento stateless in modo da non rifiutare l'header generato dalla piattaforma. Mcp-Session-Id

Suggerimento

Amazon Bedrock supporta AgentCore anche server MCP stateful (stateless_http=False) che abilitano funzionalità come l'elicitazione (interazioni utente a più turni) e il campionamento (contenuto). LLM-generated La modalità Stateful è necessaria quando il server MCP deve mantenere il contesto della sessione tra più richieste all'interno della stessa chiamata dello strumento. Per ulteriori informazioni ed esempi, vedete Funzionalità del server Stateful MCP.

Gestione delle sessioni MCP e aderenza microVM

Il Model Context Protocol (MCP) utilizza l'Mcp-Session-Idintestazione per gestire lo stato della sessione e instradare le richieste. Per le specifiche MCP, vedere MCP Streamable HTTP Transport.

Adesività MicroVM: Amazon Bedrock AgentCore utilizza l'Mcp-Session-Idintestazione per indirizzare le richieste alla stessa istanza MicroVM. I client devono acquisire i dati Mcp-Session-Id restituiti nella risposta e includerli in tutte le richieste successive per garantire l'affinità della sessione. Senza un ID di sessione coerente, ogni richiesta può essere indirizzata a una nuova microVM, il che può comportare una latenza aggiuntiva dovuta agli avvii a freddo.

MCP senza stato (): stateless_http=True

  • La piattaforma genera Mcp-Session-Id e lo include nella richiesta al server MCP.

  • Il server MCP deve accettare l'ID di sessione fornito dalla piattaforma (non rifiutarlo).

  • La piattaforma restituisce lo stesso Mcp-Session-Id al client nella risposta.

  • Il client deve includere questo ID di sessione in tutte le richieste successive di affinità microVM.

MCP con stato (): stateless_http=False

  • Il client invia la richiesta di inizializzazione senza un'intestazione. Mcp-Session-Id

  • La piattaforma ritorna Mcp-Session-Id nella risposta.

  • Il client deve includerlo Mcp-Session-Id in tutte le richieste successive sia per lo stato della sessione che per l'affinità microVM.

Per maggiori dettagli sulla gestione delle sessioni MCP con stato, consulta la specifica di gestione delle sessioni MCP.

Nota

In entrambe le modalità, Amazon Bedrock restituisce AgentCore sempre un'Mcp-Session-Idintestazione ai client. Cattura e riutilizza sempre questa intestazione per prestazioni ottimali.

Requisiti del contenitore

Il server MCP deve essere distribuito come applicazione containerizzata che soddisfi queste specifiche:

  • Host: 0.0.0.0

  • Porta: 8000 - Porta standard per la comunicazione con il server MCP (diversa dal protocollo HTTP)

  • Piattaforma: contenitore ARM64 - Richiesto per la compatibilità con l'ambiente di AWS runtime Amazon Bedrock AgentCore

Requisiti del percorso

/mcp - POST

Scopo

Riceve messaggi RPC MCP e li elabora tramite le funzionalità degli strumenti dell'agente, trasmissione completa del payload InvokeAgentRuntimeAPI con messaggi MCP RPC standard

Formato di risposta

JSON-RPC request/response formato basato, che supporta entrambi application/json e text/event-stream come tipi di contenuto di risposta

Casi d'uso

L'/mcpendpoint serve a diversi scopi chiave:

  • Richiamata e gestione degli strumenti

  • Scoperta delle capacità degli agenti

  • Accesso e manipolazione delle risorse

  • Multi-step flussi di lavoro degli agenti

Risposte di autenticazione OAuth

OAuth-configured gli agenti seguono gli standard di autenticazione RFC 6749 (OAuth 2.0). Quando manca l'autenticazione, il servizio restituisce una risposta 401 Unauthorized con un' WWW-Authenticate intestazione (secondo RFC 7235), che consente ai client di scoprire gli endpoint del server di autorizzazione tramite l'API. GetRuntimeProtectedResourceMetadata

401 - Autorizzazione negata

Restituito quando l'intestazione di autorizzazione è mancante o vuota.

La risposta include l' WWW-Authenticate intestazione:

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
Nota

SigV4-configured gli agenti restituiscono HTTP 403 con un ACCESS_DENIED errore e non includono WWW-Authenticate le intestazioni.