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á.

Contrato de protocolo MCP

Entenda os requisitos para implementar o Model Context Protocol (MCP) para que os agentes possam chamar ferramentas e servidores de agentes.

Por exemplo, código, consulte Implantar servidores MCP em AgentCore tempo de execução.

Requisitos de implementação do protocolo

Seu servidor MCP deve implementar esses requisitos de protocolo específicos:

Gerenciamento de sessões de MCP e aderência de microVM

O Model Context Protocol (MCP) usa o Mcp-Session-Id cabeçalho para gerenciar o estado da sessão e rotear solicitações. Para a especificação MCP, consulte MCP Streamable HTTP Transport.

Stickiness da microVM: o Amazon Bedrock AgentCore usa o Mcp-Session-Id cabeçalho para rotear solicitações para a mesma instância de microVM. Os clientes devem capturar o Mcp-Session-Id retornado na resposta e incluí-lo em todas as solicitações subsequentes para garantir a afinidade da sessão. Sem um ID de sessão consistente, cada solicitação pode ser roteada para uma nova microVM, o que pode resultar em latência adicional devido às partidas a frio.

MCP apátrida ()stateless_http=True:

MCP com estado ()stateless_http=False:

Para obter mais detalhes sobre o gerenciamento de sessões MCP com estado, consulte a especificação de gerenciamento de sessões MCP.

Requisitos de container

Seu servidor MCP deve ser implantado como um aplicativo em contêiner que atenda às seguintes especificações:

Requisitos de caminho

/mcp - PUBLICAR

Finalidade

Recebe mensagens MCP RPC e as processa por meio dos recursos da ferramenta do seu agente, passagem completa da carga útil da InvokeAgentRuntime API com mensagens RPC MCP padrão

Formato de resposta

JSON-RPC request/response formato baseado, suportando ambos application/json e text/event-stream como tipos de conteúdo de resposta

Casos de uso

O /mcp endpoint serve a vários propósitos principais:

Tratamento de erros

Os servidores MCP retornam erros como respostas de erro padrão JSON-RPC 2.0. A maioria dos erros é transmitida no JSON-RPC error objeto com um código de status HTTP 200, conforme exigido pela especificação MCP. Somente erros de autenticação, autorização e solicitação em nível de protocolo usam códigos de status HTTP diferentes de 200. A tabela a seguir mapeia cada exceção de tempo de execução para seu código de JSON-RPC erro, código de status HTTP e mensagem. Algumas exceções compartilham um código de JSON-RPC erro, mas retornam mensagens diferentes, então elas são listadas como linhas separadas.

ConflictExceptione RetryableConflictException ambos usam código JSON-RPC de erro -32005 (HTTP 200), mas são diferenciados por sua mensagem. O serviço retorna RetryableConflictException (Session operation in progress, please retry) quando uma segunda operação tem como alvo uma sessão enquanto o serviço está provisionando ou desativando essa sessão. Como o MCP retorna HTTP 200 com o erro no JSON-RPC corpo, o chamador deve inspecionar o corpo da resposta e tentar novamente com um pequeno recuo exponencial — os clientes MCP não tentam novamente automaticamente.

Exemplo de resposta de erro:

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

Respostas de autenticação OAuth

OAuth-configured os agentes seguem os padrões de autenticação RFC 6749 (OAuth 2.0). Quando a autenticação está ausente, o serviço retorna uma resposta 401 não autorizada com um WWW-Authenticate cabeçalho (de acordo com a RFC 7235), permitindo que os clientes descubram os endpoints do servidor de autorização por meio da API. GetRuntimeProtectedResourceMetadata

401 Não autorizado

Retornado quando o cabeçalho de autorização está ausente ou vazio.

A resposta inclui WWW-Authenticate cabeçalho:

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