Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

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 esempio di codice, vedi Distribuire i server MCP in Runtime. AgentCore

Requisiti di implementazione del protocollo

Il server MCP deve implementare questi requisiti di protocollo specifici:

Gestione delle sessioni MCP e persistenza delle microVM

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

MicroVM Stickiness: Amazon Bedrock AgentCore utilizza l'Mcp-Session-Idintestazione per indirizzare le richieste alla stessa istanza MicroVM. I clienti devono acquisire il risultato Mcp-Session-Id restituito nella risposta e includerlo 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 avviamenti a freddo.

MCP senza stato (): stateless_http=True

Stateful MCP (): stateless_http=False

Per maggiori dettagli sulla gestione delle sessioni MCP con stato, consulta le specifiche di gestione delle sessioni MCP. https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management

Requisiti del contenitore

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

Requisiti del percorso

/mcp - POST

Scopo

Riceve messaggi RPC MCP e li elabora tramite le funzionalità dello strumento dell'agente, trasmissione completa del payload delle InvokeAgentRuntime API con messaggi RPC MCP standard

Formato di risposta

JSON-RPC request/response formato basato, che supporta sia i tipi di contenuto application/json di risposta che text/event-stream quelli di risposta

Casi d'uso

L'/mcpendpoint serve a diversi scopi chiave:

Gestione degli errori

I server MCP restituiscono gli errori come risposte di errore standard JSON-RPC 2.0. La maggior parte degli errori viene registrata nell' JSON-RPC erroroggetto con un codice di stato HTTP 200, come richiesto dalla specifica MCP. Solo gli errori di autenticazione, autorizzazione e richiesta a livello di protocollo utilizzano codici di stato HTTP diversi da 200. La tabella seguente associa ogni eccezione di runtime al relativo codice JSON-RPC di errore, codice di stato HTTP e messaggio. Alcune eccezioni condividono un codice JSON-RPC di errore ma restituiscono messaggi diversi, quindi sono elencate come righe separate.

ConflictExceptioned RetryableConflictException entrambi utilizzano il codice di JSON-RPC errore -32005 (HTTP 200) ma si distinguono per il messaggio. Il servizio restituisce RetryableConflictException (Session operation in progress, please retry) quando una seconda operazione è indirizzata a una sessione mentre il servizio esegue il provisioning o la disattivazione di tale sessione. Poiché MCP restituisce HTTP 200 con l'errore nel JSON-RPC corpo, il chiamante deve ispezionare il corpo della risposta e riprovare con un breve backoff esponenziale: i client MCP non lo riprovano automaticamente.

Esempio di risposta all'errore:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32005,
    "message": "Session operation in progress, please retry"
  }
}

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 (per 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}"