User's blog

Como criar MCP Apps interativos com o Amazon Bedrock AgentCore

Written by

Make.com Service User

in

O problema que o MCP Apps resolve

À medida que os usuários passam a interagir com serviços digitais por meio de hosts de Inteligência Artificial (IA) como o ChatGPT e o Claude, as organizações enfrentam um desafio concreto: como tornar seus serviços acessíveis dentro dessas plataformas com interfaces ricas, e não apenas respostas em texto simples? E como fazer isso sem ficar preso a um único host?

É exatamente para isso que a AWS combina o MCP Apps com o Amazon Bedrock AgentCore. O MCP Apps é uma extensão do Protocolo de Contexto de Modelo (MCP) que permite entregar widgets HTML interativos renderizados diretamente dentro dos hosts de IA. Já o Amazon Bedrock AgentCore é a plataforma da AWS para construir, conectar e otimizar agentes em escala, com qualquer framework ou modelo.

Para o caso específico de MCP Apps, dois componentes do AgentCore entram em ação: o AgentCore runtime, que fornece um ambiente serverless, seguro e com isolamento de sessão para hospedar o servidor MCP; e o AgentCore Gateway, que expõe esse servidor por meio de um único endpoint gerenciado que os hosts compatíveis com MCP Apps conseguem acessar.

A aplicação de exemplo: Unicorn Rentals

Para demonstrar o conceito na prática, a AWS publicou uma aplicação de exemplo chamada Unicorn Rentals — um serviço fictício de aluguel de unicórnios. Com ela, os usuários podem visualizar unicórnios disponíveis, fazer reservas, consultar aluguéis ativos e devolver um unicórnio. Tudo isso por meio de linguagem natural dentro do ChatGPT ou do Claude.

O fluxo funciona assim na prática:

  • Listar unicórnios disponíveis: ao perguntar “pode me mostrar todos os unicórnios?”, o host interpreta a solicitação e renderiza cards interativos para cada unicórnio — com imagem, nome, descrição, valor por hora e disponibilidade.
  • Fazer uma reserva: dizendo “quero alugar o Stardust”, o sistema registra a reserva e confirma imediatamente com ID de reserva, data, valor e o unicórnio escolhido.
  • Consultar reservas ativas: ao pedir “mostre minhas reservas”, o app retorna o aluguel em andamento com duração e custo acumulado — neste caso, em formato de texto simples, sem card, pois nem toda resposta precisa de interface rica.
  • Devolver o unicórnio: com “quero devolver meu unicórnio”, o sistema encerra o aluguel, calcula o custo total com base na duração e no valor por hora, e exibe o resultado na conversa.

O ponto mais relevante aqui é que toda essa experiência é servida por um único servidor MCP rodando no AgentCore runtime, independentemente do host utilizado. Por ser baseado no padrão aberto MCP Apps, o mesmo servidor funciona tanto no ChatGPT quanto no Claude ou qualquer outro host que suporte a extensão.

Arquitetura da solução

A solução implanta um MCP App no Amazon Bedrock AgentCore que expõe lógica de negócio e widgets HTML interativos via Protocolo de Contexto de Modelo. Os usuários interagem com hosts de IA, que renderizam esses widgets usando o padrão MCP Apps. A lógica de negócio fica em uma função AWS Lambda dedicada, com o Amazon DynamoDB como camada de persistência.

O fluxo de registro e descoberta funciona da seguinte forma: ao registrar o MCP App em um host de IA, o host realiza chamadas tools/list e resources/list para o endpoint do AgentCore Gateway. O servidor MCP responde com a lista de ferramentas disponíveis (como list_unicorns, book_unicorn, view_bookings e return_unicorn) e os recursos de widget associados. O AWS WAF valida as requisições por meio de lista de permissões de IP e regras gerenciadas antes de chegarem ao Gateway.

Quando um usuário faz uma solicitação, o fluxo se divide em duas fases:

  • Fase 1 — Chamada de ferramentas: o host traduz a solicitação em linguagem natural para uma mensagem tools/call do MCP e a envia ao endpoint do AgentCore Gateway. O Gateway repassa ao AgentCore runtime, que aciona a Lambda de negócio. A Lambda executa as operações no DynamoDB e retorna o resultado, que o servidor MCP formata e devolve ao host.
  • Fase 2 — Renderização de widgets: se a ferramenta tiver um URI de recurso associado (como ui://widget/unicorn-list), o host inicia uma requisição resources/read para esse URI. O servidor MCP retorna o HTML do widget como conteúdo independente. O host renderiza esse HTML em um iframe isolado, injetando os dados estruturados retornados pela chamada de ferramenta. As imagens do widget são servidas pelo Amazon CloudFront, que usa o Amazon Simple Storage Service (Amazon S3) como origem. Ferramentas sem widget associado, como view_bookings e return_unicorn, retornam apenas texto e pulam essa fase.

Como o servidor MCP é construído

Estrutura do MCP App

O MCP App da solução é uma aplicação TypeScript construída sobre o SDK oficial @modelcontextprotocol/sdk, com a extensão @modelcontextprotocol/ext-apps — que fornece uma forma padronizada de entregar widgets interativos a partir de servidores MCP. A aplicação roda como um servidor HTTP Express.js gerenciado internamente pelo AgentCore runtime.

Ferramentas MCP

O app registra as ferramentas MCP (list_unicorns, book_unicorn, view_bookings e return_unicorn) que os hosts de IA podem invocar. O registro é feito com a função registerAppTool, fornecendo o nome da ferramenta, sua configuração e uma função de handler com a lógica de negócio. O campo _meta.ui.resourceUri na configuração da ferramenta indica ao host qual widget renderizar para exibir a resposta. O structuredContent na resposta da chamada contém o payload de dados que será injetado no widget durante a renderização.

Recursos MCP

Os widgets são registrados como Recursos MCP que os hosts de IA podem consumir. O registro usa a função registerAppResource, fornecendo nome, URI e um handler que retorna o HTML do widget. Cada recurso responde tanto a requisições de descoberta (resource/list) quanto de leitura (resource/read).

Hospedagem no AgentCore runtime

O processo de implantação empacota o código do MCP App em um arquivo zip, faz upload para um bucket S3 e cria um recurso de runtime no AgentCore referenciando esse pacote. A configuração especifica o ambiente NODE_22, o ponto de entrada e o modo de protocolo MCP. O runtime escala automaticamente conforme o volume de requisições. Políticas baseadas em recursos restringem quais entidades podem invocar o runtime — nesta solução, apenas a role de execução do AgentCore Gateway tem permissão.

Expondo o servidor via AgentCore Gateway

O AgentCore runtime suporta autenticação via Gerenciamento de Identidade e Acesso (IAM) com SigV4 e OAuth. A solução coloca um AgentCore Gateway na frente do runtime para que hosts externos acessem o servidor MCP por um único endpoint gerenciado. O Gateway aceita requisições sem autenticação do lado do cliente e invoca o runtime usando sua própria role IAM via SigV4 — ou seja, os chamadores não precisam gerenciar credenciais AWS. O AWS WAF protege o endpoint com lista de permissões de IP, regras de detecção de ameaças e limitação de taxa.

Camada de lógica de negócio

Uma função AWS Lambda implementa toda a lógica de negócio do serviço de aluguel, lidando com consultas de inventário e operações de reserva no DynamoDB. Essa Lambda não sabe nada sobre MCP — ela é apenas um serviço de backend. Em implementações reais, essa camada poderia ser serviços existentes rodando no Amazon Elastic Container Service (Amazon ECS), no Amazon Elastic Kubernetes Service (Amazon EKS) ou em qualquer outro serviço de computação. O servidor MCP atua como um adaptador de protocolo fino: a lógica de negócio permanece onde já está, conectada à camada MCP por padrões de invocação padrão como chamadas HTTP ou clientes SDK.

Como implantar a solução

Pré-requisitos

Implantação

A implantação usa um único script deploy.sh que orquestra o build e a implantação das stacks do CDK. Os passos são:

Passo 1: Baixe o código da solução:

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

Passo 2: Implante os recursos necessários na sua conta AWS executando o script de implantação:

bash deploy.sh

Anote as saídas exibidas após a implantação. Você precisará do valor de GatewayResourceUrl para conectar um host de IA.

Conectando hosts de IA

Como o servidor MCP implementa o padrão aberto MCP Apps, qualquer host que suporte a extensão pode se conectar e renderizar a experiência completa com widgets interativos.

ChatGPT: acesse https://chatgpt.com/, vá em Perfil do Usuário → Plugins → Modo Desenvolvedor e ative-o. Em Plugins, escolha Novo Plugin. Defina o nome como UnicornRentals, adicione uma descrição, informe o valor de GatewayResourceUrl como Connection e selecione No Auth como autenticação. Clique em Create.

Claude.ai: acesse https://claude.ai, vá em Customize → Connectors → Add Connector. Defina o nome como UnicornRentals, informe o valor de GatewayResourceUrl como URL do servidor MCP remoto e salve.

Considerações para produção

Ao levar esta solução para produção, a AWS recomenda atenção a alguns pontos:

  • Monitoramento e observabilidade: use o Amazon CloudWatch para monitorar métricas de requisições do AgentCore Gateway, invocações da Lambda e saúde dos containers do AgentCore runtime. Configure alarmes para taxas de erro e latência, e ative logs para rastrear chamadas de métodos MCP.
  • Otimização de custos: o AgentCore runtime usa precificação baseada em consumo, com base no tempo de execução do container e nas invocações. Dimensione corretamente a memória e CPU do container e revise as configurações de concorrência da Lambda conforme os padrões de tráfego esperados.
  • IA responsável: adicione controles de segurança nos limites de confiança. Valide os argumentos das ferramentas com schemas rigorosos no servidor MCP e revalide-os na Lambda de negócio. Para textos não estruturados que cruzam esses limites, use o Amazon Bedrock Guardrails para filtrar conteúdo prejudicial, bloquear tópicos negados e redigir dados sensíveis como Informações de Identificação Pessoal (PII) antes que as respostas cheguem ao cliente.

Para remover todos os recursos criados pelas stacks do CDK, execute:

cd infrastructure/cdk
npx cdk destroy

Por que essa abordagem é relevante

O que torna esse padrão arquitetural poderoso é justamente o que você não precisa construir. O AgentCore runtime cuida do escalonamento, do isolamento de sessão, do monitoramento de saúde e do gerenciamento de infraestrutura. A equipe foca na lógica de negócio e nos widgets — e escreve apenas um adaptador de protocolo fino apontando para os serviços existentes.

Por ser construída sobre o padrão aberto MCP Apps, a solução não fica presa a um único host de IA. O mesmo servidor, as mesmas ferramentas e os mesmos widgets interativos funcionam em qualquer host que suporte a extensão. E como a arquitetura separa claramente o tratamento de protocolo da lógica de negócio, cada parte pode evoluir de forma independente — trocar o banco de dados, adicionar novas ferramentas, redesenhar widgets ou conectar novos serviços de backend sem precisar rearquitetar a implantação.

O código-fonte e as instruções completas de implantação estão disponíveis no repositório GitHub da solução em aws-samples.

Fonte

Build interactive MCP Apps using Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-interactive-mcp-apps-using-amazon-bedrock-agentcore/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts