Como conectar um servidor MCP hospedado no AgentCore Runtime ao Amazon Quick

O Model Context Protocol (MCP) se consolidou como o padrão para conectar agentes de IA a ferramentas e fontes de dados. A novidade é que o Amazon Quick — a nova suíte de agentes da AWS — passou a aceitar integrações MCP para execução autônoma, acesso a dados em tempo real e subagentes especializados. Este guia mostra como hospedar um servidor MCP no AgentCore Runtime e conectá-lo ao Amazon Quick, promovendo reutilização e evitando duplicação de ferramentas entre clientes.

O que você ganha (e o que não ganha)

• ✅ Reutilização: um único servidor MCP atende chat, Flows e outros clientes, sem recriar a mesma lógica.
• ✅ Segurança de ponta a ponta: o AgentCore Gateway aplica TLS, IAM e Cognito como camadas de autenticação.
• ✅ Deploy gerenciado: o AgentCore Runtime cuida de containerização e execução do servidor.
• ✅ Escalabilidade: ferramentas ficam disponíveis para múltiplos subagentes sem código duplicado.
• ⚠️ Curva inicial: exige configurar IAM, Cognito e o starter kit antes da primeira integração.
• ⚠️ Acoplamento à AWS: o padrão é específico do ecossistema Amazon Bedrock/AgentCore.

Requisitos

Passo 1 — Crie o servidor MCP localmente

Comece montando a estrutura do projeto. Um servidor MCP mínimo tem um arquivo principal, as dependências e um marcador de pacote:

mcp_server_project/
├── mcp_server.py      # Código principal do servidor
├── requirements.txt   # Dependências
└── __init__.py        # Marcador de pacote Python

O requirements.txt lista as bibliotecas necessárias:

mcp>=1.10.0
boto3
bedrock-agentcore
bedrock-agentcore-starter-toolkit>=0.1.21
strands-agents

Instale as dependências em um ambiente virtual. O uv acelera a instalação em comparação ao pip tradicional:

uv venv sample-venv              # Cria o ambiente virtual
source sample-venv/bin/activate  # Ativa o ambiente
uv pip install -r requirements.txt  # Instala as dependências

O servidor mínimo usa FastMCP para expor ferramentas. Cada função decorada com @mcp.tool() vira uma ferramenta chamável pelo agente:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def getOrder() -> int:
    """Get an order"""
    return 123

@mcp.tool()
def updateOrder(orderId: int) -> int:
    """Update existing order"""
    return 456

Teste o servidor localmente com um cliente MCP antes de implantar — isso valida que as ferramentas respondem corretamente.

Passo 2 — Implante no AgentCore Runtime

Com o servidor funcionando localmente, configure o projeto para o deploy. O comando de configuração gera automaticamente um Dockerfile e um .dockerignore para containerizar o servidor:

agentcore configure --entrypoint mcp_server.py --name simple_mcp_server

O parâmetro --entrypoint aponta para o arquivo que contém a lógica principal do agente, e --name define um identificador único na sua conta AWS. Em seguida, lance o servidor:

agentcore launch

Após o lançamento, o servidor MCP deve aparecer no Runtime, pronto para receber conexões.

Passo 3 — Configure o AgentCore Gateway

O Gateway atua como a ponte segura entre o Amazon Quick e o servidor MCP. A configuração segue as boas práticas de segurança, incluindo TLS de ponta a ponta:

• Crie uma função IAM com o caso de uso Amazon Bedrock AgentCore e uma política inline com as permissões bedrock-agentcore:InvokeAgentRuntime, bedrock-agentcore:InvokeRegistryMcp e secretsmanager:GetSecretValue.
• Crie um user pool no Amazon Cognito para validar as requisições recebidas do Amazon Quick antes que cheguem ao Gateway.

Com o Gateway configurado, o servidor MCP fica disponível como ferramenta autenticada dentro do chat do Amazon Quick, sem duplicar lógica em cada cliente.

Problemas comuns

• ❌ Servidor não aparece no Runtime → confirme que o agentcore launch concluiu sem erros e que o nome do projeto é único na conta.
• ❌ Erro de permissão IAM → verifique se a política inline inclui as três ações bedrock-agentcore:* e o acesso ao Secrets Manager.
• ❌ Ferramentas não aparecem no chat → valide o endpoint do Gateway e se o user pool do Cognito está configurado como camada de entrada.
• ❌ Falha na instalação de dependências → confirme que está usando Python 3.9+ e que o uv está atualizado.
• ❌ Erro de conexão TLS → revise o TLS de ponta a ponta no fluxo de entrada e saída do Gateway.

Perguntas frequentes

• Preciso ter um servidor MCP pronto? Se já tiver, use este guia para integrá-lo. Se não, o tutorial cobre a criação de um servidor mínimo do zero.
• Posso usar o Amazon Quick no desktop? Sim, na data de publicação é possível usar no navegador ou no aplicativo desktop, com chat ou Flows.
• O que é o AgentCore Gateway? É a camada que autentica e encaminha as requisições entre o Amazon Quick e o servidor MCP.
• Preciso de chaves de API? Não — a autenticação é feita por IAM e Cognito, dentro do ecossistema AWS.
• Serve para produção? O padrão foi desenhado para reutilização e segurança, mas valide carga e custos no seu cenário específico.