O problema que essa solução resolve
Equipes de e-commerce que precisam lançar experiências de IA para clientes costumam enfrentar semanas de trabalho de integração personalizada. Construir um assistente de IA pronto para produção normalmente exige código de API customizado para cada cliente, gerenciamento de infraestrutura de containers e autenticação complexa. A AWS apresentou uma abordagem que simplifica esse processo combinando o Amazon Bedrock AgentCore com o Mistral AI Studio.
A proposta central é usar o Protocolo de Contexto de Modelo (MCP) como camada de integração padronizada. Com isso, você escreve um único servidor que múltiplos clientes de IA conseguem consumir, em vez de construir uma integração separada para cada cliente. O AgentCore Runtime cuida dos containers e valida tokens, enquanto o Amazon Cognito gerencia as identidades.
Visão geral da arquitetura
A solução é organizada em três camadas que trabalham juntas:
- Camada de aplicação: um servidor MCP escrito em Python com FastMCP, expondo seis ferramentas de e-commerce via endpoint
/mcpe um endpoint/healthpara monitoramento. O AgentCore Runtime hospeda o servidor como container. - Camada de dados: cinco tabelas no Amazon DynamoDB armazenam os dados de Produtos, Clientes, Pedidos, Avaliações e Devoluções, com capacidade sob demanda e Índices Secundários Globais para consultas eficientes.
- Camada de segurança: autenticação em duas etapas que mantém os dados de cada cliente isolados. O Amazon Cognito atua como provedor de identidade via OAuth 2.1, o AgentCore Runtime valida os tokens Token Web JSON (JWT) na camada de infraestrutura, e a aplicação extrai atributos do usuário autenticado para restringir o acesso aos dados daquele cliente específico.
A infraestrutura é provisionada via AWS Kit de Desenvolvimento em Nuvem (CDK) com quatro stacks: DynamoDBStack, CognitoStack, DataLoaderStack e AgentCoreRuntimeStack. O DataLoaderStack usa uma função AWS Lambda para popular o banco com dados de teste realistas — 50 produtos, 10 clientes, 50 pedidos, avaliações e devoluções — permitindo testar o servidor imediatamente após o deploy.
Fluxo de autenticação e requisições
O fluxo completo de uma interação do usuário passa por quatro fases distintas:
- Configuração (uma vez): o desenvolvedor executa
cdk deploypara criar todos os recursos AWS, configura o AgentCore Runtime com o user pool do Cognito e os IDs de clientes autorizados, e faz o deploy do container do servidor MCP. - Conexão (uma vez por sessão): o usuário abre o Vibe, adiciona um conector MCP customizado com OAuth 2.1 e informa a URL do servidor no AgentCore. O Vibe descobre o provedor de identidade do Cognito, abre um popup de login no navegador, e após a autenticação o Cognito emite um token JWT Bearer que o Vibe armazena e atualiza automaticamente durante a sessão.
- Descoberta (uma vez por sessão): logo após a autenticação, o Vibe envia uma requisição
list_tools()ao AgentCore com o token Bearer. O AgentCore valida o JWT e repassa a requisição ao servidor MCP, que retorna as seis ferramentas disponíveis e seus esquemas de parâmetros. - Requisição (a cada interação): quando o usuário pergunta algo como “Quais eletrônicos estão em estoque abaixo de R$500?”, o Vibe envia uma requisição MCP ao AgentCore com o token JWT. O AgentCore valida o token com o Cognito verificando assinatura, expiração e autorização do cliente. Uma vez validado, a requisição chega ao servidor MCP, que extrai a identidade do cliente via Cognito, consulta o DynamoDB com escopo restrito aos dados daquele cliente e retorna os resultados formatados.
Definindo ferramentas MCP com autenticação
As ferramentas MCP são definidas como funções Python decoradas com @mcp.tool(). Os parâmetros, anotações de tipo e docstring da função se tornam o esquema da ferramenta, que o modelo de IA lê para decidir quando e como chamar cada função. Veja o exemplo da ferramenta de histórico de pedidos:
@mcp.tool()
def get_order_history(limit: int = 10) -> dict:
"""
Get order history for the authenticated user.
REQUIRES AUTHENTICATION - Pass Authorization header.
Args:
limit: Maximum number of orders to return
Returns:
List of past orders with status, product details, and pricing
"""
customer_id = get_current_customer_id()
if customer_id == 'anonymous':
return {"success": False, "error": "Authentication required"}
try:
orders = db.get_customer_orders(customer_id, limit=limit)
# Enrich orders with product names
enriched_orders = []
for order in orders:
product_id = order.get('product_id')
if product_id:
product = db.get_product(product_id)
if product:
order['product_name'] = product.get('name', 'Unknown Product')
order['product_category'] = product.get('category', 'Unknown')
enriched_orders.append(order)
return {"success": True, "order_count": len(enriched_orders), "orders": enriched_orders}
except Exception as e:
return {"success": False, "error": str(e)}O servidor também é configurado para operação sem estado, requisito do AgentCore para balanceamento de carga:
mcp = FastMCP("ecommerce-mcp-server")
mcp_app = mcp.http_app(path="/mcp", stateless_http=True)Autenticação em duas camadas
A autenticação é dividida entre duas camadas com responsabilidades distintas:
Camada de infraestrutura: o AgentCore Runtime valida criptograficamente cada JWT antes que a requisição chegue à aplicação. Ele verifica a assinatura contra as chaves públicas do Cognito e confere emissor, expiração e ID do cliente na lista de autorizados. Tokens inválidos são rejeitados imediatamente — o código da aplicação não executa para requisições não autenticadas.
Camada de aplicação: o servidor resolve o JWT validado em uma identidade de cliente. Como tokens OAuth 2.1 não incluem atributos customizados no payload, o servidor chama o Cognito para recuperar o custom:customer_id que vincula o usuário aos seus dados de e-commerce. A implementação usa uma abordagem de método duplo para lidar com diferentes tipos de token:
def extract_customer_id_from_token(access_token: str) -> Optional[str]:
"""
Extract custom:customer_id from a Cognito access token.
Handles OAuth 2.1 tokens using AdminGetUser via IAM.
"""
cognito = boto3.client('cognito-idp', region_name=AWS_REGION)
# Primary method: AdminGetUser for OAuth 2.1 Authorization Code tokens
try:
payload = _decode_jwt_payload(access_token)
username = payload.get('username') or payload.get('sub')
user_pool_id = payload.get('iss', '').rstrip('/').split('/')[-1]
if username and user_pool_id:
user_info = cognito.admin_get_user(
UserPoolId=user_pool_id,
Username=username
)
for attr in user_info['UserAttributes']:
if attr['Name'] == 'custom:customer_id':
return attr['Value']
except (ClientError, Exception):
pass
# Fallback method: get_user() for token types with admin scope
try:
user_info = cognito.get_user(AccessToken=access_token)
for attr in user_info['UserAttributes']:
if attr['Name'] == 'custom:customer_id':
return attr['Value']
except ClientError:
pass
return NoneVale destacar que o AgentCore Identity suporta claims customizados em tokens JWT, o que permitiria encaminhar atributos como customer_id diretamente para a aplicação sem chamada de API adicional. Para mais detalhes, consulte a documentação sobre Configurando OAuth para o AgentCore Runtime e o Autorizador JWT de Entrada.
Fluxo de deploy
O deploy do servidor MCP envolve quatro etapas:
- Provisionamento de infraestrutura: executar
cdk deploy --alla partir do diretórioecommerce-mcp-cdkcria os quatro stacks em sequência. O processo leva cerca de 5 minutos e exibe os valores necessários para os próximos passos — ARN do papel IAM, URI do repositório ECR, URL de descoberta do Cognito e IDs de clientes. - Criação de usuários: o script
create_cognito_users.pycria dez usuários de teste (demo1@example.comademo10@example.com) e atribui a cada um um ID de cliente único que os vincula aos pedidos e avaliações no DynamoDB. - Configuração do AgentCore: o comando
agentcore configuregera o arquivo.bedrock_agentcore.yamlcom as configurações necessárias. - Deploy do container: o comando
agentcore deployorquestra um build e deploy baseado na nuvem. O AgentCore cria um projeto CodeBuild na conta AWS, envia o código-fonte para o Amazon S3, e constrói uma imagem Docker ARM64 no CodeBuild — sem necessidade de Docker instalado localmente. Em seguida, envia a imagem para o ECR e chama a API do Bedrock AgentCore para criar e iniciar o runtime.
O código-fonte completo, scripts de deploy e guia passo a passo estão disponíveis no repositório GitHub.
Boas práticas para servidores MCP
Design de ferramentas
- Limite o número de ferramentas por servidor: mantenha entre 5 e 8 ferramentas bem definidas em vez de dezenas de funções sobrepostas. Cada ferramenta adicional aumenta a complexidade de decisão do modelo. Se precisar de mais operações, divida em múltiplos servidores MCP agrupados por domínio.
- Orientação explícita de parâmetros: inclua exemplos nas docstrings e destaque erros comuns.
- Retorne respostas estruturadas: inclua tanto identificadores legíveis por máquina (
order_id,product_id) quanto rótulos legíveis por humanos (product_name,status) para que o modelo gere respostas naturais sem chamadas adicionais.
Segurança em camadas
- Valide na camada da ferramenta: verifique a identidade do usuário no início de cada função protegida, mesmo que o AgentCore Runtime bloqueie requisições não autenticadas na borda.
- Verifique propriedade dos dados: antes de mutações, confirme que o recurso pertence ao usuário autenticado para evitar acesso não autorizado.
- Aplique privilégio mínimo no IAM: restrinja o papel de execução do AgentCore Runtime a ações específicas em recursos específicos, sem permissões com caractere curinga.
- Restrinja tokens antes de passar para ferramentas: ao encaminhar um JWT para uma ferramenta, remova-o para apenas os claims que a ferramenta precisa. Não passe o token completo com todos os escopos e atributos.
Conectando ao Mistral Vibe com segurança
Ao conectar servidores MCP ao Mistral AI Vibe, é fundamental conectar apenas servidores confiáveis — preferencialmente os que você mesmo controla. Um servidor MCP mal-intencionado pode realizar injeção de prompt, sombreamento de ferramentas ou escalada de privilégios via encaminhamento de tokens. Além disso, recomenda-se limitar a 5 ou 6 conectores ativos por vez para reduzir a complexidade de decisão do modelo e a chance de comportamentos inesperados.
Limpeza de recursos
Para evitar cobranças contínuas, basta executar agentcore delete --name ecommerce_mcp_server para parar o runtime, e depois cdk destroy --all a partir do diretório ecommerce-mcp-cdk para remover as tabelas DynamoDB, o user pool do Cognito, os papéis IAM, o repositório ECR e demais recursos. Verifique a remoção completa pelo console do AWS CloudFormation.
Próximos passos e recursos relacionados
Os padrões desta solução se aplicam a outros domínios. Para quem já opera workloads no AgentCore Runtime, basta substituir as ferramentas de e-commerce por operações específicas do seu domínio — como uma ferramenta de suporte ao cliente que consulta um banco de tickets, ou uma ferramenta de serviços financeiros que recupera registros de transações.
Para produção, recomenda-se adicionar dashboards no Amazon CloudWatch para latência e taxas de erro, integrar o AWS WAF para filtragem adicional de requisições, e usar o Amazon EventBridge para disparar notificações em eventos de pedidos.
Para explorar soluções relacionadas, a AWS indica o AWS para Agentes Autônomos para padrões de arquitetura de agentes, a documentação do Amazon Bedrock AgentCore para recursos avançados como persistência de memória e aplicação de políticas, e os guias de integração da Mistral AI para conectar ferramentas empresariais adicionais ao Vibe. Para as documentações dos serviços AWS utilizados, consulte o Guia do Desenvolvedor do Amazon DynamoDB, o Guia do Desenvolvedor do Amazon Cognito, o Guia do Desenvolvedor do AWS CDK, a documentação do FastMCP e a especificação do Model Context Protocol.
Fonte
Building and connecting a production-ready ecommerce MCP server using Amazon Bedrock AgentCore and Mistral AI Studio (https://aws.amazon.com/blogs/machine-learning/building-and-connecting-a-production-ready-ecommerce-mcp-server-using-amazon-bedrock-agentcore-and-mistral-ai-studio/)
Leave a Reply