Como a AWS construiu uma ponte MCP para conectar agentes de IA na nuvem a ferramentas locais

O problema: agente na nuvem, arquivos no laptop

Existe um desafio bastante concreto no uso de agentes de IA hospedados na nuvem: e quando as ferramentas que o agente precisa usar estão na máquina local do usuário? Planilhas Excel, repositórios Git, arquivos de configuração — tudo isso vive no computador de quem trabalha, não em um servidor remoto.

Foi exatamente esse problema que a equipe da AWS se propôs a resolver. Em um post técnico detalhado, a AWS descreve como construiu uma ponte entre um agente hospedado no Amazon Bedrock AgentCore e servidores MCP (Model Context Protocol) rodando localmente na máquina do usuário final.

O resultado prático? Um assistente de IA para finanças que, segundo a AWS, acumulou mais de 41.000 conversas em um ano desde o lançamento interno — lendo planilhas diretamente do computador do analista, sem expor credenciais ao navegador.

O que é o MCP e qual é a lacuna que a ponte resolve

O Model Context Protocol (MCP) é um padrão aberto lançado pela Anthropic em novembro de 2024 para padronizar como modelos de IA se conectam a dados externos e ferramentas. Ele segue uma arquitetura cliente-servidor: o host MCP (uma aplicação de IA, como o Amazon Quick ou o Claude Code) estabelece conexões com um ou mais servidores MCP.

O protocolo suporta dois mecanismos de transporte: stdio (para comunicação entre processos na mesma máquina) e HTTP com streaming (para comunicação entre cliente remoto e servidor remoto). O que faltava era justamente o cenário inverso: servidor MCP local, cliente MCP remoto. A ponte MCP da AWS resolve exatamente essa lacuna.

Esse padrão é o mesmo que alimenta produtos como o Claude Cowork — um agente na nuvem chamando ferramentas locais via MCP — mas, neste caso, totalmente auto-hospedado na AWS com modelo e servidores de ferramentas próprios.

Arquitetura da solução: quatro componentes em conjunto

A arquitetura descrita pela AWS tem quatro componentes principais que trabalham em conjunto:

• AgentCore Runtime: hospeda o agente Strands na nuvem. O agente atua como cliente MCP, emitindo requisições de descoberta e invocação de ferramentas.
• Extensão de navegador: fornece a interface de chat e age como retransmissora bidirecional, encaminhando mensagens MCP entre o AgentCore Runtime (via WebSocket) e a MCP Bridge (via native messaging).
• MCP Bridge: um proxy FastMCP rodando na máquina local do usuário, iniciado pelo navegador através do registro de host de native messaging. Ele traduz entre o formato de envelope do native messaging e o JSON-RPC bruto do MCP.
• Servidor MCP: um servidor MCP padrão rodando localmente. Como a bridge está co-localizada, a comunicação usa transporte stdio.

O fluxo completo funciona assim: o usuário envia uma mensagem pela extensão, que se conecta ao AgentCore Runtime via WebSocket pré-assinado. Quando o agente Strands precisa chamar uma ferramenta, ele envia uma requisição JSON-RPC MCP encapsulada em um envelope JSON de volta pela WebSocket para a extensão. A extensão repassa a mensagem para a bridge via native messaging. A bridge desencapsula o envelope, extrai o conteúdo JSON-RPC e o encaminha para o servidor MCP via stdio. A resposta percorre o caminho inverso.

A tabela abaixo mostra como uma única chamada de ferramenta percorre os saltos entre o agente e o servidor MCP, com cada salto removendo uma camada de encapsulamento:

Salto 1 — Agente → Extensão (WebSocket):
{"type": "mcpbridge", "content": {"type": "mcp", "payload": ""}, "session_id": "session_123"}

Salto 2 — Extensão → Bridge (Native Messaging):
{"type": "mcp", "payload": ""}

Salto 3 — Bridge → Servidor MCP (stdio):
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_sheet", "arguments": {"file_path": "budget.xlsx"}}}

Como o agente Strands funciona no AgentCore Runtime

Conexão WebSocket

A extensão de navegador se conecta ao AgentCore Runtime via uma URL WebSocket pré-assinada. Na inicialização, o painel lateral envia uma requisição de pré-assinatura pelo script de background para a bridge nativa, que usa as credenciais AWS locais do usuário e o SDK do bedrock-agentcore para gerar uma URL wss:// assinada com SigV4, com escopo para o ARN do runtime implantado (válida por 5 minutos). Nenhuma credencial sai da máquina do usuário ou entra no navegador.

Inicialização MCP e descoberta de ferramentas

Antes de descobrir ferramentas, o agente realiza o handshake de inicialização MCP padrão: envia uma requisição initialize com a versão do protocolo, aguarda a resposta de capacidades do servidor e envia a notificação notifications/initialized. Somente após esse handshake o servidor aceita requisições tools/list e tools/call.

A cada mensagem do usuário, o agente chama tools/list e recebe um array de esquemas de ferramentas. Ele encapsula cada esquema em um Strands AgentTool cujo método stream() envia uma requisição tools/call pela bridge. Ferramentas adicionadas ao servidor MCP ficam automaticamente disponíveis na próxima requisição, sem nenhuma alteração no código do agente.

Correlação de requisição e resposta

Cada requisição JSON-RPC de saída do agente recebe um ID único e é registrada em um asyncio.Future indexado por (session_id, jsonrpc_id). Quando a resposta chega de volta pela WebSocket, ela é associada ao Future correspondente e resolvida. Isso permite que múltiplas chamadas de ferramentas estejam em andamento simultaneamente sem ambiguidade.

Como funciona o native messaging

Para que a extensão se comunique com um processo local de longa duração sem permissões de rede ou prompts por mensagem, a solução usa o native messaging — suportado tanto pelo Chrome quanto pelo Firefox. O navegador procura um arquivo de manifesto em um local conhecido na máquina do usuário que especifica qual binário iniciar.

O arquivo de manifesto do native messaging para Chrome no macOS tem o seguinte formato:

# Stored at ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.example.mcp_bridge.json
{
  "name": "com.example.mcp_bridge",
  "description": "MCP Bridge - Routes MCP messages to local servers",
  "path": "/path/to/mcp-bridge-demo/bridge/run_bridge.sh",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension:///"
  ]
}

Na inicialização da extensão, o script de background chama chrome.runtime.connectNative("com.example.mcp_bridge") para iniciar o aplicativo nativo localmente. O script run_bridge.sh referenciado no manifesto ativa o ambiente Python e inicia a bridge:

#!/bin/bash
cd "/path/to/mcp-bridge-demo/bridge"
source .venv/bin/activate
exec python3 bridge.py

Cada mensagem é serializada como JSON, codificada em UTF-8 e precedida por um comprimento de mensagem de 32 bits em ordem little-endian. O tamanho máximo de uma mensagem do host de native messaging é 1 MB; o tamanho máximo de uma mensagem enviada ao host é 64 MiB.

Como a MCP Bridge funciona internamente

A MCP Bridge age como tradutora de protocolo entre dois mundos: o protocolo de native messaging do Chrome de um lado, e o padrão MCP (JSON-RPC 2.0 sobre stdio) do outro.

No caminho de entrada, ela remove o cabeçalho de 4 bytes do stdin, analisa o corpo JSON e desencapsula o envelope para extrair a mensagem JSON-RPC bruta. No caminho de saída, faz o inverso: encapsula a resposta JSON-RPC em um envelope e a escreve de volta com o cabeçalho de comprimento.

Internamente, a bridge executa dois loops concorrentes conectados por um proxy FastMCP. O loop principal lê mensagens do navegador, as desencapsula e coloca o conteúdo JSON-RPC em uma fila de entrada. O proxy FastMCP, iniciado uma vez e mantido ativo pelo tempo de vida da bridge, pega mensagens dessa fila, as encaminha para o subprocesso do servidor MCP via stdin e coloca as respostas do stdout do servidor em uma fila de saída. Um segundo loop em background lê da fila de saída, encapsula cada resposta de volta em um envelope e a escreve no stdout para o navegador receber.

O servidor MCP em si é um processo filho iniciado pela bridge na inicialização, configurado por um arquivo mcp.json. Adicionar um novo servidor MCP é uma mudança de uma linha nesse arquivo:

# mcp.json
{
  "mcpServers": {
    "excel": {
      "command": "python3",
      "args": ["excel_server.py"]
    }
  }
}

Pré-requisitos e implantação

Para implantar e testar a solução, são necessários:

• Conta AWS com acesso ao modelo Bedrock habilitado (o código usa Claude Opus 4.7). Disponibilidade do modelo varia por região — consulte a documentação de disponibilidade de modelos do Amazon Bedrock.
• Permissões de Gerenciamento de Identidade e Acesso (IAM) para Bedrock AgentCore (bedrock-agentcore:*), AWS CloudFormation, criação de roles IAM e S3.
• Interface de Linha de Comando da AWS (AWS CLI) configurada com credenciais.
• Kit de Desenvolvimento em Nuvem da AWS (AWS CDK) inicializado na região alvo.
• Python 3.10+, Node.js 20+, Google Chrome e Git.

O processo de implantação consiste em clonar o repositório, instalar dependências Python, criar e implantar o agente no AgentCore via CLI, configurar o arquivo bridge_config.json com o ARN do runtime, carregar a extensão no Chrome e registrar a bridge de native messaging. O código completo está disponível no GitHub.

git clone https://github.com/aws-samples/sample-mcp-bridge-agentcore.git
cd mcp-bridge-demo

chmod +x scripts/setup.sh manifests/install.sh
./scripts/setup.sh

npm install -g @aws/agentcore
cd agent
agentcore create --name McpBridgeAgent --defaults
cd McpBridgeAgent
cp ../agent.py app/McpBridgeAgent/main.py
cp ../mcp_bridge_transport.py app/McpBridgeAgent/
agentcore deploy

{
  "runtime_arn": "arn:aws:bedrock-agentcore:::runtime/",
  "region": "us-east-1",
  "presign_expires": 300
}

./manifests/install.sh 

Considerações de segurança

A AWS destaca que a solução demonstrada prioriza a funcionalidade da bridge MCP e, portanto, inclui apenas medidas básicas de segurança: restrição de origem do native messaging (o Chrome verifica o ID da extensão contra a lista allowed_origins), expiração de URL pré-assinada (URLs WebSocket são assinadas com SigV4 e expiram em 5 minutos) e isolamento de processos.

A principal superfície de exposição única dessa arquitetura é a própria bridge: ela aceita instruções de um agente hospedado na nuvem e as executa localmente com as permissões do sistema de arquivos do usuário. Para um sistema em produção, além de implementar o Amazon Bedrock Guardrails para filtragem de conteúdo, a AWS recomenda medidas adicionais:

• Autenticação: exigir um handshake com Token Web JSON (JWT) como primeiro frame WebSocket, verificado via Amazon Cognito ou segredo HMAC no AWS Systems Manager.
• Assinatura de payload: assinar cada mensagem MCP com Ed25519 (chave privada no agente, chave pública na bridge) para garantir que mensagens não foram modificadas em trânsito.
• Escopo do sistema de arquivos: configurar uma lista explícita de diretórios que o servidor MCP pode acessar, rejeitando caminhos fora do limite — prevenindo que uma injeção de prompt engane o agente para ler arquivos sensíveis.
• Registro de auditoria: registrar cada invocação de ferramenta (nome, argumentos, timestamp, status do resultado) em um arquivo local para rastreabilidade.

O que vem a seguir: extensões da arquitetura

A AWS aponta que a arquitetura atual pode ser estendida para suportar mais casos de uso:

• Ações no navegador: a extensão pode implementar suas próprias ferramentas de navegador modeladas nas definições de ferramentas do Playwright MCP e expô-las ao agente para realizar ações como clicar em elementos, preencher formulários, navegar em páginas e tirar screenshots.
• Automação de ferramentas locais: a bridge fala JSON-RPC MCP padrão sobre stdio, então servidores MCP compatíveis com transporte stdio funcionam sem modificação. Exemplos incluem acesso ao sistema de arquivos para leitura/escrita em sandbox, Git para operações em repositórios e memory para grafos de conhecimento local persistentes. O diretório awesome-mcp-servers lista servidores disponíveis.
• Empacotamento como binário standalone: para distribuição em produção, a AWS usa o PyInstaller para empacotar a bridge em um binário standalone que inclui o runtime Python, dependências e configuração em um único executável.

Conclusão

A solução descrita pela AWS demonstra como é possível manter um agente de IA centralmente implantado e gerenciado enquanto se dá a ele acesso a ferramentas que precisam rodar localmente — planilhas Excel, repositórios Git ou outros servidores MCP locais. O padrão usa uma extensão de navegador como camada de retransmissão e o native messaging do Chrome como transporte local, tunelando mensagens JSON-RPC MCP padrão entre a nuvem e o sistema de arquivos do usuário sem expor credenciais ao navegador ou modificar o próprio protocolo MCP.

Para explorar a solução, o repositório de exemplo está disponível para implantação e experimentação com servidores MCP próprios. Para aprofundamento, a AWS disponibiliza a documentação do Amazon Bedrock AgentCore, o SDK do Strands Agents e a especificação do Model Context Protocol.

Fonte

How we built an MCP bridge to give our AgentCore-hosted AI agent access to local MCP tools (https://aws.amazon.com/blogs/machine-learning/how-we-built-an-mcp-bridge-to-give-our-agentcore-hosted-ai-agent-access-to-local-mcp-tools/)