Por que um proxy MCP serverless importa em produção
Quando agentes de IA se conectam a ferramentas por meio do Protocolo de Contexto de Modelo (MCP), eles ganham acesso a capacidades que vão de consultas a bancos de dados e chamadas de API até operações em arquivos e integrações com serviços de terceiros. Em produção, essas interações precisam de governança adequada, controles e observabilidade alinhados às políticas de segurança da organização.
Isso inclui sanitizar entradas de ferramentas antes que cheguem aos sistemas de backend, gerar trilhas de auditoria em formatos específicos ou redigir dados sensíveis na camada de protocolo. Esses requisitos são moldados por padrões internos de governança, regulamentações do setor e as especificidades de cada ambiente de produção.
A AWS publicou um guia mostrando como implantar um proxy MCP serverless no Amazon Bedrock AgentCore Runtime que fornece exatamente essa camada programável.
O contexto: Gateway, interceptores Lambda e quando o proxy faz mais sentido
O Amazon Bedrock AgentCore Gateway já oferece governança centralizada para integração entre agentes e ferramentas, incluindo descoberta semântica de ferramentas, credenciais gerenciadas e aplicação de políticas. Para organizações que precisam embutir lógica personalizada no caminho de requisição do Gateway, o serviço suporta interceptores Lambda — que permitem executar código de validação, transformação ou filtragem como funções AWS Lambda em cada invocação de ferramenta.
Porém, algumas organizações já investiram em lógica de filtragem MCP personalizada fortemente acoplada a bibliotecas internas ou sistemas de conformidade on-premises. Elas querem reutilizar essa lógica no AgentCore Runtime sem refatorá-la em funções Lambda. Outras operam em ambientes híbridos onde executar controles como um servidor MCP independente oferece mais portabilidade. Nesses casos, um proxy MCP serverless rodando no AgentCore Runtime é um padrão complementar e mais adequado.
O que é o AgentCore Runtime e por que ele serve de base para o proxy
O AgentCore Runtime é um ambiente de computação totalmente gerenciado para implantar agentes de IA e servidores MCP. Ele oferece infraestrutura serverless com escalonamento automático, observabilidade integrada via Amazon CloudWatch e OpenTelemetry, além do AgentCore Identity para autenticação e autorização.
Como o Runtime suporta nativamente o protocolo MCP, ele permite hospedar servidores MCP — incluindo proxies MCP que adicionam controles personalizados ao tráfego. O proxy apresentado no guia é stateless, roda como uma carga de trabalho serverless no Runtime, descobre ferramentas de um servidor MCP upstream na inicialização, re-expõe essas ferramentas com sua lógica personalizada aplicada e encaminha requisições de forma transparente.
Visão geral da arquitetura
A solução envolve três camadas lógicas que trabalham juntas via MCP: o cliente MCP, o proxy MCP no AgentCore Runtime e o servidor MCP upstream. O fluxo de requisições percorre essas camadas em sequência: o cliente envia requisições MCP ao proxy, o proxy aplica a lógica personalizada e encaminha a requisição ao servidor MCP upstream, e o servidor upstream processa a requisição e retorna a resposta pelo mesmo caminho.
O servidor MCP upstream pode ser hospedado em qualquer lugar — no próprio AgentCore Runtime, na infraestrutura da organização ou como serviço de terceiros. No guia publicado pela AWS, o AgentCore Gateway é usado como servidor upstream porque já fornece um endpoint compatível com MCP com alvos registrados, permitindo seguir o passo a passo sem precisar configurar um servidor MCP separado.
Como o proxy MCP funciona internamente
A implementação usa o FastMCP para descobrir ferramentas do servidor MCP upstream na inicialização e encaminhar cada requisição do cliente em tempo de execução. O proxy não define ferramentas próprias e não tem conhecimento prévio do que o servidor upstream expõe.
Quando o processo do proxy inicia, ele envia uma requisição padrão tools/list ao servidor upstream. O servidor retorna o catálogo completo de ferramentas disponíveis. Para cada ferramenta, o proxy registra dinamicamente uma ferramenta FastMCP local com o mesmo nome e descrição. Cada ferramenta é suportada por uma função handler que encaminha requisições tools/call ao servidor upstream e retorna a resposta.
Clientes MCP que se conectam ao proxy veem o mesmo catálogo de ferramentas e obtêm os mesmos resultados como se estivessem se conectando diretamente ao servidor upstream. Como o proxy é um servidor MCP Python padrão que você possui e implanta, é possível inserir lógica personalizada antes de encaminhar uma chamada de ferramenta ou após receber a resposta.
Autorização entre os componentes
A autorização é aplicada de forma independente em cada camada da arquitetura, criando fronteiras de confiança distintas ao longo do fluxo.
Do agente ao proxy MCP
Quando um agente se conecta ao proxy MCP, ele usa o AgentCore Identity para autenticação e autorização. O proxy utiliza as capacidades que o AgentCore Identity oferece, incluindo gerenciamento centralizado de identidades de agentes e armazenamento seguro de credenciais.
Do proxy ao servidor MCP upstream
O proxy precisa se autenticar no servidor MCP upstream ao qual se conecta. O método de autenticação depende dos requisitos do servidor upstream. O AgentCore Identity oferece autorização de entrada para cargas de trabalho hospedadas no AgentCore Runtime por meio de Gerenciamento de Identidade e Acesso da AWS (IAM) usando AWS Signature Version 4 (SigV4) e autorização baseada em Token Web JSON (JWT) usando credenciais de cliente OAuth 2.0.
Para autorização baseada em IAM, o proxy assina requisições usando SigV4 com a função de execução IAM que herda do AgentCore Runtime. O script de implantação concede a essa função permissões bedrock-agentcore:InvokeGateway, com o campo Resource com escopo para o Gateway. O proxy usa a sessão boto3 do runtime para assinar requisições automaticamente.
Para autorização OAuth, o proxy substitui a assinatura SigV4 por um token bearer obtido via concessão de credenciais de cliente OAuth 2.0. O token é armazenado em cache na memória e atualizado automaticamente quando se aproxima da expiração. Cada requisição de saída ao servidor MCP upstream inclui o token como cabeçalho Authorization: Bearer. O projeto no GitHub usa autorização baseada em IAM como método padrão, mas o script de implantação também suporta autorização baseada em JWT.
Do servidor upstream para as ferramentas
O servidor MCP upstream se autentica nas ferramentas downstream usando provedores de credenciais do AgentCore Identity, que gerenciam tokens OAuth 2.0, chaves de API e rotação de credenciais de forma transparente. A autorização de saída opera da mesma forma independentemente de as requisições se originarem do proxy ou de um cliente direto.
Pré-requisitos para a implantação
- Ambiente de desenvolvimento Linux ou macOS com Python 3.12 ou posterior instalado
- Interface de Linha de Comando da AWS (AWS CLI) instalada e configurada com credenciais para um principal AWS IAM com permissões para criar funções IAM, interagir com o Amazon Elastic Container Registry (Amazon ECR) e invocar APIs do Amazon Bedrock AgentCore
- O AgentCore starter toolkit instalado — consulte como começar com o Amazon Bedrock AgentCore starter toolkit em Python
- Docker instalado — a CLI do AgentCore usa Docker para construir a imagem de contêiner
- Um endpoint de servidor MCP upstream — o guia usa um Amazon Bedrock AgentCore Gateway com pelo menos um alvo registrado
- (Opcional, para OAuth) Um pool de usuários do Amazon Cognito com domínio configurado e um cliente de aplicativo que usa concessão de credenciais de cliente com segredo de cliente
Implantando a solução
O processo começa clonando o repositório do GitHub e revisando a estrutura do projeto. Em seguida, o arquivo deploy_config.json deve ser configurado com os valores do ambiente: o endpoint do servidor MCP upstream em gateway_endpoint, a região AWS em region, e opcionalmente o Nome de Recurso Amazon (ARN) do Gateway em gateway_api_id para restringir as permissões IAM a esse recurso específico.
O campo auth_mode determina como o proxy se autentica no servidor upstream — o padrão é "iam" para autenticação baseada em IAM. Para autenticação OAuth, define-se auth_mode como "jwt" e configuram-se os campos do Cognito.
O script automatizado setup_and_deploy.py executa o fluxo completo de implantação em sequência:
- Valida pré-requisitos — verifica se AWS CLI, Python e Docker estão disponíveis e se as credenciais AWS estão configuradas
- Cria uma função de execução IAM com política de confiança que permite ao
bedrock-agentcore.amazonaws.comassumir a função, incluindo permissões para invocar o Gateway, gravar no Amazon CloudWatch Logs e extrair imagens do Amazon ECR - Configura o agente com a CLI do AgentCore executando
agentcore configurecom o protocolo MCP, apontando para o entrypoint do proxy emmcp_proxy/main.py - Lança o agente no AgentCore Runtime via
agentcore launch, passando o endpoint do servidor upstream como variável de ambiente (GATEWAY_ENDPOINT)
Após a implantação, o status do agente proxy MCP pode ser verificado com agentcore status --agent mcp_proxy. O ARN do agente exibido na saída é usado no cliente de teste para invocar o proxy.
Oportunidades de personalização
Tokenização de dados sensíveis
Argumentos de chamadas de ferramentas podem conter Informações de Identificação Pessoal (PII) que não devem chegar aos sistemas de backend em texto claro. O fluxo de encaminhamento do proxy oferece um ponto de interceptação natural para adicionar tokenização. O código relevante fica na função _make_tool_handler em main.py:
def _make_tool_handler(tool_name: str):
"""Create a tool handler function that forwards calls to the gateway."""
def handler(**kwargs) -> str:
# --- Tokenize: scan kwargs for PII and replace with tokens ---
result = _send_gateway_request(
"tools/call",
{"name": tool_name, "arguments": kwargs}
)
content = result.get("content", [])
# --- Detokenize: reverse tokens in content before returning ---
if content and isinstance(content, list):
texts = [c.get("text", str(c)) for c in content if isinstance(c, dict)]
return "\n".join(texts) if texts else json.dumps(result)
return json.dumps(result)
return handlerA tokenização pode ser adicionada em dois pontos dentro do closure do handler: antes da chamada a _send_gateway_request, para escanear os valores de kwargs em busca de padrões de PII e substituí-los por tokens reversíveis (consulte o Guia de Tokenização para Melhorar a Segurança de Dados e Reduzir o Escopo de Auditoria na AWS); e após o retorno de _send_gateway_request, para reverter os tokens no conteúdo da resposta antes de devolvê-la ao cliente.
Controle de acesso por ferramenta
É possível restringir quais ferramentas um determinado chamador pode invocar, mesmo que o servidor upstream exponha o catálogo completo. Isso é implementado adicionando uma verificação de política no início da função handler criada por _make_tool_handler. Antes de encaminhar a requisição tools/call ao servidor upstream, o handler avalia a identidade do chamador em relação a uma política de acesso. Se o chamador não estiver autorizado para aquela ferramenta, o handler retorna uma resposta de erro sem contatar o servidor upstream. Também é possível filtrar a resposta de tools/list na função register_gateway_tools para expor apenas as ferramentas que correspondem a uma determinada política.
Limpeza dos recursos
Para evitar cobranças recorrentes, os recursos criados devem ser removidos após os testes. A CLI do AgentCore fornece um comando destroy que remove o agente e seus recursos associados:
agentcore destroy --agent <agent-name> --delete-ecr-repo --forceEm seguida, a política IAM inline e a função de execução devem ser removidas:
aws iam delete-role-policy --role-name <your-MCPProxy-Server-Role> --policy-name <your-Gateway-Access-Policy>
aws iam delete-role --role-name <your-MCPProxy-Server-Role>Se um AgentCore Gateway foi criado especificamente para este exercício e não é mais necessário, ele também deve ser removido:
agentcore gateway delete-mcp-gateway --name <your-Gateway> --forceConclusão
O padrão de proxy MCP serverless no AgentCore Runtime oferece uma camada programável onde é possível aplicar lógica personalizada como validação de entrada, logging, limitação de taxa ou enriquecimento de resposta. O proxy é stateless, roda como um contêiner padrão no Runtime e pode ser conectado a qualquer servidor MCP upstream compatível, encadeando múltiplos endpoints ou adicionando lógica de middleware específica para a carga de trabalho.
O código-fonte completo, scripts de implantação e agente de teste estão disponíveis no GitHub. Para saber mais sobre como construir e implantar agentes no AgentCore e usar o framework Strands Agents, a AWS disponibiliza a documentação do Amazon Bedrock AgentCore e o SDK do Strands Agents.
Fonte
Run custom MCP proxies serverless on Amazon Bedrock AgentCore Runtime (https://aws.amazon.com/blogs/machine-learning/run-custom-mcp-proxies-serverless-on-amazon-bedrock-agentcore-runtime/)
Leave a Reply