User's blog

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

Written by

Make.com Service User

in

MCP e o papel dos servidores de contexto para agentes de IA

O Protocolo de Contexto de Modelo (MCP) permite que modelos de fundação acessem dados externos e ferramentas de forma padronizada e segura — incluindo arquivos, bancos de dados e APIs. Com isso, agentes de IA ganham a capacidade de interagir com aplicações reais, reduzir alucinações com contexto preciso e manter conversas com múltiplos turnos e estado persistente. Não é à toa que arquiteturas de IA agêntica adotaram o MCP como padrão do setor rapidamente.

O Amazon Quick já suporta integrações MCP para execução autônoma, acesso a dados em tempo real e integração com sub-agentes especializados. Se você já tem um servidor MCP, pode usar o guia de integração oficial para conectá-lo ao Amazon Quick. Se ainda não tem, a AWS disponibilizou um guia para implantação de servidores MCP na AWS, seguindo os pilares do AWS Well-Architected.

Opções de arquitetura para hospedar seu servidor MCP

Dependendo do seu caso de uso, a AWS oferece três caminhos principais:

  • Se você já tem uma API REST própria ou rodando no Amazon API Gateway, pode integrar o Amazon Quick diretamente via Amazon Bedrock AgentCore Gateway.
  • Se prefere uma arquitetura serverless com o mínimo necessário, pode criar uma função AWS Lambda e integrá-la ao Amazon Quick via AgentCore Gateway.
  • Se precisa de uma solução gerenciada completa — com isolamento de sessão, tempo de execução estendido, sistema de arquivos persistente, autenticação integrada, observabilidade, streaming bidirecional e avaliações — a opção é usar o AgentCore Runtime para hospedar o servidor MCP e conectá-lo ao Amazon Quick via AgentCore Gateway.

Este artigo cobre exatamente esse terceiro caminho: do servidor MCP local até uma ferramenta autenticada e disponível dentro do seu agente de chat no Amazon Quick.

Visão geral da solução

Atualmente, o Amazon Quick pode ser usado via navegador ou aplicativo desktop, com agentes de chat ou Flows que oferecem capacidades de IA agêntica. Para conectar o agente ao servidor MCP, a integração é feita via conectores no lado do Amazon Quick e via AgentCore Gateway no lado do AgentCore.

O AgentCore Gateway e o Runtime fazem parte do Amazon Bedrock AgentCore, um serviço totalmente gerenciado para construção de aplicações de IA generativa. O fluxo de autorização do Amazon Quick para o AgentCore Gateway é chamado de Inbound Auth (autenticação de entrada), e o fluxo do Gateway para o Runtime é chamado de Outbound Auth (autenticação de saída).

  • Inbound Auth: autentica e autoriza o usuário a acessar o servidor MCP. O exemplo usa Amazon Cognito, mas outros provedores de identidade também são suportados.
  • Outbound Auth: lida com autenticação máquina a máquina usando o AgentCore Identity, um serviço de gerenciamento de identidade e acesso criado especificamente para agentes de IA. O protocolo MCP exige OAuth 2.0 para autenticação, portanto o Outbound Auth usa OAuth 2.0.

Pré-requisitos

Antes de começar, é necessário ter:

  • Uma conta AWS.
  • Amazon Quick configurado com assinatura Author ou superior.
  • Permissão para criar funções e políticas do Gerenciamento de Identidade e Acesso da AWS (IAM) e recursos para AgentCore, Amazon Cognito e Amazon CloudWatch.
  • Conhecimento básico dos serviços AWS.
  • Ambiente de linha de comando com AWS SDK e Python instalados.
  • Python 3.10+, credenciais AWS configuradas, SDK do Amazon Bedrock AgentCore, biblioteca MCP e Docker em execução.
  • Acesso ao Amazon Bedrock com modelos Anthropic habilitados.

Passo 1 — Implementar e implantar o servidor MCP no AgentCore Runtime

O primeiro passo é criar e implantar um servidor MCP de exemplo no AgentCore Runtime. O código completo está disponível no notebook de exemplos do AgentCore no GitHub. A estrutura básica do projeto é:

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

O arquivo requirements.txt deve conter:

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

Para instalar as dependências:

uv venv sample-venv                  # Criar ambiente virtual
source sample-venv/bin/activate      # Ativar ambiente virtual
uv pip install -r requirements.txt   # Instalar dependências

Um exemplo mínimo de servidor MCP (sample_mcp_server.py), conforme descrito pela AWS — para detalhes sobre configuração segura de autenticação, consulte o artigo Building a secure auth code flow setup using AgentCore Gateway with MCP clients:

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

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

O servidor usa FastMCP com stateless_http=True, obrigatório para compatibilidade com o AgentCore Runtime. O decorador @mcp.tool() transforma funções Python em ferramentas MCP. Quando o AgentCore Runtime é configurado com o protocolo MCP, o serviço espera que os containers do servidor MCP estejam disponíveis no caminho 0.0.0.0:8000/mcp.

Com o servidor testado localmente, é hora de implantar no AgentCore Runtime usando o starter kit do AgentCore. No terminal, com o diretório do projeto como diretório atual:

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

Esse comando gera automaticamente um Dockerfile, um arquivo .dockerignore e um arquivo de configuração .bedrock_agentcore.yaml. Em seguida, para implantar:

agentcore launch

Após a execução, o servidor MCP estará visível no Runtime.

Passo 2 — Integrar o servidor MCP ao AgentCore Gateway

O AgentCore Gateway atua como a ponte segura entre o Amazon Quick e o servidor MCP implantado. A configuração envolve quatro sub-etapas. Para configuração programática, consulte o tutorial de MCP server como target no GitHub.

2a — Criar uma função IAM para o AgentCore Gateway

No Console de Gerenciamento da AWS, acesse IAM e crie uma nova função selecionando Amazon Bedrock AgentCore como caso de uso. Anexe a seguinte política inline de permissões:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MCPServerRuntimePermissions",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeRegistryMcp",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:::runtime/",
        "arn:aws:bedrock-agentcore:::runtime//runtime-endpoint/*"
      ]
    }
  ]
}

Use o nome de exemplo agentcore-sample-mcpgateway-role (ou escolha o seu). Em Resource, substitua pelos valores do ARN do servidor MCP implantado no AgentCore Runtime.

2b — Criar um user pool do Amazon Cognito para Inbound Auth

Acesse o Amazon Cognito e crie um novo user pool para a camada de autorização de entrada, que valida as requisições vindas do Amazon Quick antes de chegarem ao Gateway. Configure um servidor de recursos com o escopo personalizado protegido invoke. Anote o Client ID, Client Secret e a Discovery URL do formato: https://cognito-idp.{REGION}.amazonaws.com/{gw_user_pool_id}/.well-known/openid-configuration.

2c — Criar um user pool do Amazon Cognito para Outbound Auth

Crie um segundo user pool no Amazon Cognito para a camada de autorização de saída, permitindo que o Gateway se autentique ao fazer chamadas para o servidor MCP no AgentCore Runtime. Configure também um servidor de recursos com escopo invoke e anote as mesmas informações (Client ID, Client Secret e Discovery URL).

Em seguida, crie um provedor de credencial OAuth no AgentCore Identity: acesse Amazon Bedrock AgentCore, escolha Identity, selecione Add Outbound Auth e Create OAuth Client. Preencha com a Discovery URL, Client ID e Client Secret do user pool de Outbound Auth.

2d — Criar o AgentCore Gateway

Acesse Amazon Bedrock AgentCore, escolha Gateway e crie um novo gateway (no exemplo, nomeado ac-gateway-mcp-server). Para o Inbound Auth, selecione JWT como tipo de autenticação e forneça a Discovery URL e o Client ID do user pool criado no passo 2b. Na seção de permissões, use a função IAM do passo 2a.

Na seção Target, registre o servidor MCP como alvo. Selecione OAuth Client como tipo de autorização (o protocolo MCP não suporta outros métodos neste momento). A URL do endpoint MCP segue o template:

https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{encoded_agentcore_runtime_mcp_server_arn}/invocations?qualifier=DEFAULT

Substitua encoded_agentcore_runtime_mcp_server_arn pelo ARN do seu servidor MCP codificado em URL. Para o Outbound Auth, use o OAuth client criado no passo 2c. Aguarde o Gateway e seu Target atingirem o estado Ready antes de prosseguir.

Passo 3 — Registrar a integração MCP no Amazon Quick

No Amazon Quick, acesse Connectors e escolha Create for your team. Selecione Model Context Protocol (MCP) como tipo de integração. Forneça um nome, descrição e o MCP Server Endpoint (a Resource URL do AgentCore Gateway criado no passo 2d). Também é possível escolher conectividade VPC privada para restringir a visibilidade do servidor MCP na rede.

Na tela de autenticação, preencha os detalhes do Inbound Auth configurado no Gateway. Selecione o tipo de autenticação conforme seu caso de uso: User authentication (para autenticar usuários individuais) ou Service authentication (para integrações mais sistemáticas). O tutorial da AWS usa User authentication com Amazon Cognito.

Preencha Client ID, Client Secret, Token URL e Authorization URL. Para a Token URL, use o template abaixo — atenção: o underscore no ID do user pool deve ser removido (por exemplo, us-west-2_qNBcTlLbR vira us-west-2qNBcTlLbR):

https://{user_pool_id_without_underscore}.auth.{REGION}.amazoncognito.com/oauth2/token

Para a Authorize URL, use a mesma URL substituindo token por authorize. Após criar a integração, aguarde o status da Action ficar como Available ou Ready — isso indica que as ferramentas foram sincronizadas com o servidor MCP.

Passo 4 — Testar a integração no Amazon Quick

Com a integração configurada, é possível escolher Test Action APIs para verificar se as ferramentas MCP estão acessíveis e funcionando. Em seguida, adicione a integração como uma Action no seu agente de chat ou Flow. Para o tutorial da AWS, cria-se um agente de chat de exemplo, vincula-se a integração na seção Actions e testa-se diretamente no chat antes de publicar o agente.

Passo 5 — Limpeza dos recursos

Para evitar custos desnecessários, exclua os recursos criados na ordem inversa à da criação. Você também pode consultar o código de limpeza no notebook do tutorial no GitHub. A ordem recomendada é:

  1. Agente de chat ou Flow no Amazon Quick
  2. Action no Amazon Quick
  3. AgentCore Gateway
  4. Recursos do AgentCore Identity
  5. User pools do Amazon Cognito (Inbound e Outbound Auth)
  6. AgentCore Runtime
  7. Função IAM do AgentCore Gateway

Conclusão

O padrão descrito pela AWS demonstra como o Amazon Quick pode ser integrado a servidores MCP personalizados hospedados no Amazon Bedrock AgentCore Runtime. A abordagem cobre desde a implantação do servidor MCP até a segurança com autenticação de entrada e saída via Amazon Cognito e AgentCore Identity, passando pela ponte com o Amazon Quick por meio do AgentCore Gateway.

O principal benefício é a reutilização de ferramentas e agentes de IA entre equipes: em vez de criar conectores personalizados para cada caso de uso, as capacidades especializadas são expostas por uma interface MCP padronizada e consumidas diretamente nos agentes de chat e Flows do Amazon Quick.

Para saber mais sobre o Amazon Quick, consulte o post Announcing Amazon Quick: your agentic teammate for answering questions and taking action. Para mais detalhes sobre o Amazon Bedrock AgentCore, veja o post Introducing Amazon Bedrock AgentCore Gateway: Transforming enterprise AI agent tool development.

Fonte

Connect an AgentCore Runtime hosted MCP server to Amazon Quick (https://aws.amazon.com/blogs/machine-learning/connect-an-agentcore-runtime-hosted-mcp-server-to-amazon-quick/)

Comments

Leave a Reply

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

More posts