View a markdown version of this page

Contrato de protocolo MCP - Amazon Bedrock AgentCore
Requisitos de implementação do protocoloRequisitos de contêinerRequisitos de caminhoRespostas de autenticação OAuth

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 de código, consulte Implantar servidores MCP no AgentCore Runtime.

Requisitos de implementação do protocolo

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

  • Transporte: o Streamable-http transporte é necessário. Por padrão, use o modo stateless (stateless_http=True) para compatibilidade com o gerenciamento AWS de sessões e o balanceamento de carga.

  • Gerenciamento de sessão: a plataforma adiciona automaticamente o Mcp-Session-Id cabeçalho para isolamento da sessão. No modo sem estado, os servidores devem suportar a operação sem estado para não rejeitar o cabeçalho gerado pela Mcp-Session-Id plataforma.

dica

O Amazon Bedrock AgentCore também oferece suporte a servidores MCP com estado (stateless_http=False) que permitem recursos como elicitação (interações com o usuário em vários turnos) e amostragem (conteúdo). LLM-generated O modo com estado é necessário quando o servidor MCP precisa manter o contexto da sessão em várias solicitações na mesma invocação de ferramenta. Para obter mais informações e exemplos, consulte Recursos do servidor Stateful MCP.

Gerenciamento de sessões 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 as solicitações. Para a especificação MCP, consulte MCP Streamable HTTP Transport.

MicroVM Stickiness: 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 a inícios a frio.

MCP apátrida ()stateless_http=True:

  • A plataforma gera o Mcp-Session-Id e o inclui na solicitação ao seu servidor MCP.

  • Seu servidor MCP deve aceitar o ID de sessão fornecido pela plataforma (não o rejeite).

  • A plataforma retorna o mesmo Mcp-Session-Id para o cliente na resposta.

  • O cliente deve incluir esse ID de sessão em todas as solicitações subsequentes de afinidade com microVM.

MCP com estado ()stateless_http=False:

  • O cliente envia a solicitação de inicialização sem um Mcp-Session-Id cabeçalho.

  • A plataforma retorna Mcp-Session-Id na resposta.

  • O cliente deve incluir isso Mcp-Session-Id em todas as solicitações subsequentes, tanto para o estado da sessão quanto para a afinidade da microVM.

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

nota

Em ambos os modos, o Amazon Bedrock AgentCore sempre retorna um Mcp-Session-Id cabeçalho para os clientes. Sempre capture e reutilize esse cabeçalho para obter um desempenho ideal.

Requisitos de contêiner

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

  • Host: 0.0.0.0

  • Porta: 8000 - Porta padrão para comunicação com o servidor MCP (diferente do protocolo HTTP)

  • Plataforma: contêiner ARM64 - necessário para compatibilidade com o ambiente de execução AWS Amazon Bedrock AgentCore

Requisitos de caminho

/mcp - CORREIO

Finalidade

Recebe mensagens MCP RPC e as processa por meio dos recursos da ferramenta de seu agente, passagem completa da carga útil da InvokeAgentRuntimeAPI com mensagens MCP RPC 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:

  • Invocação e gerenciamento de ferramentas

  • Descoberta da capacidade do agente

  • Acesso e manipulação de recursos

  • Multi-step fluxos de trabalho do agente

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}"
nota

SigV4-configured os agentes retornam HTTP 403 com um ACCESS_DENIED erro e não incluem WWW-Authenticate cabeçalhos.