AWS Agent Toolkit: Mão na Massa com Skills de Custo no Claude Code

Visão Geral

Em 6 de maio de 2026, a AWS anunciou o Agent Toolkit for AWS, um suite guarda-chuva que reúne três coisas que agentes de IA para código precisam para trabalhar com segurança contra a AWS: um MCP server gerenciado, um conjunto de agent plugins, e mais de 40 agent skills pré-construídas. É a casa oficial com suporte AWS para essa stack, e substitui os experimentos anteriores do AWS Labs. O toolkit em si é gratuito; você paga apenas pelos recursos AWS que seus agentes criarem.

A arquitetura tem três camadas:

• Agent Skills: procedimentos curtos e prescritivos que ensinam ao agente como fazer coisas específicas da AWS corretamente: qual API chamar, quais argumentos usar, quais pegadinhas evitar.
• AWS MCP Server: um endpoint remoto gerenciado em https://aws-mcp.us-east-1.api.aws/mcp (também eu-central-1) que expõe mais de 15.000 operações da AWS API através de quatro tools MCP, execução Python em sandbox, e autenticação baseada em IAM traduzida de OAuth 2.1 pelo open source mcp-proxy-for-aws.
• Agent Plugins: bundles que conectam skills, acesso ao MCP server, hooks e docs de referência num workflow único.

O toolkit lança três plugins:

Plugin	O que cobre
aws-core	O plugin “comece por aqui”. Registra o aws-mcp server e empacota skills para CDK, CloudFormation, serverless, containers, IAM, observabilidade, os SDKs, e aws-billing-and-cost-management: a história de custos foco deste post.
aws-data-analytics	Skills e referências para workloads de analytics na AWS (Glue, Athena, EMR, Redshift, Kinesis, MSK, OpenSearch) para agentes de engenharia de dados e construção de pipelines.
aws-agents	Para construir agentes na AWS em vez de agir contra ela. Conecta Bedrock AgentCore, Strands, seleção de foundation models, e os primitivos de runtime/memory/identity do AgentCore.

Os três plugins instalam em Claude Code, Codex e Kiro (instruções de instalação), com as mesmas skills e o mesmo aws-mcp server. Os walkthroughs abaixo usam Claude Code.

Este post foca em aws-core. Seu .mcp.json conecta o endpoint aws-mcp na instalação, e sua skill aws-billing-and-cost-management conversa com Cost Explorer, Budgets, Price List API e Compute Optimizer através dele.

Setup

O setup no Claude Code leva uns cinco minutos se você já tem credenciais AWS configuradas. Instalar o plugin aws-core é o único passo necessário: ele já empacota o registro do MCP server junto com as skills.

Pré-requisitos

• Uma versão atual do Claude Code (os comandos /plugin e MCP remoto referenciados abaixo precisam de um build recente).
• uv instalado localmente; o .mcp.json do plugin roda uvx mcp-proxy-for-aws@latest para subir o proxy.
• Credenciais AWS disponíveis localmente (o proxy as pega via cadeia padrão do SDK).
• Para o MCP server gerenciado, um IAM principal com permissões para as ações que seu agente vai executar. A AWS recomenda escopar com SCPs e uma role dedicada para o agente.

Passo 1: Adicione o marketplace e instale aws-core

Dentro do Claude Code:

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-core@agent-toolkit-for-aws

Três escopos de instalação: user (em todos os seus projetos), project (compartilhado pelo repo), local (este projeto, só você). Comece com user.

Após a instalação, o Claude Code pede para aplicar as mudanças:

/reload-plugins

Sem isso, o aws-mcp server e as skills do aws-core ficam instalados em disco, mas não ativos na sessão atual.

Passo 2: Verifique o MCP server empacotado

O aws-core traz seu próprio .mcp.json que registra aws-mcp para você na instalação:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp"
      ]
    }
  }
}

O package do proxy é publicado no PyPI e roda como um stdio server localmente; as chamadas reais de API vão para o endpoint regional gerenciado. Troque us-east-1 por eu-central-1 se quiser residência na UE.

Verifique se conectou rodando /mcp dentro do Claude Code (não o claude mcp list no shell):

/mcp

Você deve ver plugin:aws-core:aws-mcp listado em Built-in MCPs com check verde e contagem de tools.

O server expõe tools incluindo call_aws (qualquer uma das mais de 15.000 operações da AWS API), search_documentation, read_documentation, e run_script (Python em sandbox sem rede ou filesystem, usado para coisas como aritmética de custo).

Passo 3: O que tem dentro do aws-core

O aws-core registra o aws-mcp server citado acima e um conjunto de skills cobrindo CDK, CloudFormation, serverless, containers, IAM, observabilidade, os SDKs, e a que me interessa neste post: aws-billing-and-cost-management. O SKILL.md da skill codifica duas regras que valem citar literalmente:

• Sempre cheque a data atual. Antes de qualquer chamada ao Cost Explorer, Budgets ou Savings Plans, o agente precisa determinar a data atual real. LLMs assumem datas dos seus dados de treino e silenciosamente produzem análises desatualizadas.
• Apenas cálculos determinísticos. Nada de aritmética na resposta do modelo. A matemática roda via run_script (ou um script Python local se o aws-mcp não estiver configurado), porque aritmética de LLM é pouco confiável em dados de custo.

Essas duas regras são o motivo pelo qual um MCP server gerenciado com tool de Python em sandbox importa para trabalho de custo, e o motivo pelo qual isso vem empacotado em vez de ser deixado em peças separadas.

Testes

Os dois testes abaixo exercitam a mesma skill, aws-billing-and-cost-management, mas em ramos diferentes da sua árvore de decisão. O guia de decisão mapeia perguntas em linguagem natural para a API AWS certa:

Pergunta	Tool
O que estou gastando? Onde os custos estão subindo?	Cost Explorer
Quanto custa um serviço?	Price List API
Onde posso economizar? (comece aqui)	Cost Optimization Hub
Devo comprar Savings Plans?	CE SP Recommendations
Devo comprar Reserved Instances?	CE RI Recommendations
Análise profunda de uma recomendação específica de EC2 / Lambda / EBS / RDS?	Compute Optimizer
Como configuro alertas de orçamento?	Budgets
O que está causando um pico de custo?	Cost Anomaly Detection
Estou dentro do Free Tier?	Free Tier API
Como reduzo minha conta?	Cost Audit workflow
Como consulto dados detalhados de billing?	CUR 2.0 + Athena
Como otimizo serviços específicos?	Per-service patterns
Como escopo custos para uma billing view?	Billing Views

O Teste 1 vai pela linha do Cost Explorer (olhar para o que já aconteceu); o Teste 2 vai pela linha da Price List API (estimar algo que ainda não foi deployado).

Teste 1: “O que estou gastando?” via Cost Explorer

Fiz ao Claude Code uma pergunta deliberadamente vaga, “What am I spending? Where are costs going up?”, para ver como o plugin a roteava.

O fluxo na tela, em ordem:

1. Esclarecer o escopo. O AskUserQuestion ofereceu AWS / Anthropic API / Cloudflare. A opção Cloudflare não foi um chute: eu tenho os MCP servers e skills do Cloudflare instalados nesta sessão do Claude Code junto com o aws-core, então o agente inferiu que as três eram fontes plausíveis de custo a partir das tools disponíveis. Escolhi AWS.
2. Carregar a skill. Skill(aws-core:aws-billing-and-cost-management) carregou o guia de decisão e as duas regras inegociáveis: cheque a data de hoje primeiro, nunca faça aritmética na resposta.
3. Fixar a data. O agente declarou “Today is 2026-05-08” antes de qualquer chamada de API, em vez de inferir um ano dos dados de treino.
4. Duas chamadas MCP. O plugin:aws-core:aws-mcp foi invocado duas vezes. A primeira tentativa de ce.GetCostAndUsage falhou na validação porque os parâmetros de boto3 foram passados no nível raiz em vez de dentro de um dict params; o agente corrigiu e a segunda chamada passou. As duas chamadas rodaram dentro do mesmo sandbox run_script, então totais e deltas mês a mês foram computados em Python, não pelo modelo.
5. Devolver uma resposta defensável. Totais mensais, top serviços, maiores movimentos MoM, e o agente sinalizou cerca de $46 de gasto de abril que não conseguiu atribuir aos top 15, em vez de arredondar pra fora.

Esse é o loop que o plugin foi desenhado para impor: esclarecer → carregar skill → data → chamada de API tipada → matemática em sandbox → resposta com ressalvas.

Teste 2: Estimativa pré-deploy via Price List API

Um prompt típico do tipo “estime o custo mensal de um workload pequeno de Lambda + API Gateway + DynamoDB” é roteado para o ramo da Price List. O que a skill prescreve tem a mesma forma toda vez: call_aws contra a Pricing API para cada serviço, com o ServiceCode certo e o filtro usagetype, depois run_script para somar os componentes. Os arquivos de referência da skill incluem as strings de filtro que a maioria dos modelos erra na primeira tentativa, que é a razão prática dela existir: sem essa tabela, o Claude chutaria service codes e a Pricing API não perdoa códigos errados.

Mesmo loop do teste do Cost Explorer, API diferente. O agente fixou suposições para um workload “pequeno” (1M de invocações Lambda a 128 MB / 200 ms, 1M de requisições REST no API GW, 1M de leituras + escritas no DynamoDB, 1 GB de storage), depois fez quatro chamadas GetProducts no aws-mcp (uma por componente de serviço) para puxar preços unitários ao vivo. A primeira tentativa usou um filtro usagetype chutado e voltou vazio para API Gateway e DynamoDB; o agente corrigiu os filtros e refez a query. A aritmética rodou em run_script, não na resposta, e a tabela final totaliza $4.87/mês com o API Gateway dominando a linha em cerca de 72% da conta. O Free Tier deliberadamente não foi aplicado, então o número reflete o que uma conta em escala realmente pagaria; com Free Tier o mesmo workload fica em ~$0.75/mês.

Grandes poderes, grandes responsabilidades

Tudo acima mostra as skills fazendo a coisa certa. Aqui vem a parte que deveria te deixar desconfortável: o aws-mcp server empacotado é um proxy gerenciado na frente da AWS API inteira. Sua tool call_aws consegue invocar qualquer uma das mais de 15.000 operações, e run_script executa Python com boto3. As skills adicionam disciplina por cima, mas a tool subjacente vai fazer o que o IAM principal chamador tiver permissão de fazer. Para os workflows de custo e troubleshooting que este post acabou de demonstrar, credenciais read-only quase sempre bastam. A AWS publica políticas gerenciadas (ReadOnlyAccess, AWSBillingReadOnlyAccess, AWSCostExplorerReadOnlyAccess) que cobrem a tabela inteira do guia de decisão sem conceder uma única permissão de mutação. Reserve write access amplo para sessões em que você está conscientemente pedindo para o agente construir.

Enquanto escrevia este post, dei ao agente credenciais amplas e um prompt “YOLO” de uma linha para ver o que aconteceria. Não faça o que eu acabei de fazer:

> create a ec2 t3.micro in us-east-1 just for testing, no ssh key. you can
  decide vpc/subnet. configure session manager

  Called plugin:aws-core:aws-mcp 3 times (ctrl+o to expand)

⏺ No default VPC exists; the only VPC is a security-training environment
  ("AWS_GOAT_VPC") I shouldn't touch. I'll build a small dedicated test VPC
  with IGW + public subnet, then create the IAM role + instance profile and
  launch the instance. Narrating as I go.

  Called plugin:aws-core:aws-mcp (ctrl+o to expand)

⏺ VPC + networking ready. Now the IAM role for SSM.

  Called plugin:aws-core:aws-mcp (ctrl+o to expand)

⏺ Role + profile created. Now launching the instance.

  Called plugin:aws-core:aws-mcp (ctrl+o to expand)

⏺ Instance launched. Done.

  Created:
    • Instance         i-0EXAMPLE1234567890 (t3.micro, AL2023, us-east-1a)
    • VPC              vpc-0EXAMPLE1234567890 (10.99.0.0/16)
    • Subnet           subnet-0EXAMPLE1234567890 (public, auto-assign IP)
    • IGW              igw-0EXAMPLE12345678
    • Route table      rtb-0EXAMPLE12345678
    • Security group   sg-0EXAMPLE12345678 (no inbound, all egress)
    • IAM role         ec2-test-ssm-role + AmazonSSMManagedInstanceCore
    • Instance profile ec2-test-ssm-profile

  All tagged purpose=ec2-test, createdBy=aws-agent-toolkit-blog.

  Connect via Session Manager
  Wait ~2 minutes for the SSM agent to register, then:

  aws ssm start-session --target i-0EXAMPLE1234567890 --region us-east-1

  Or from the console: EC2 → Instances → select → Connect → Session Manager.

  Cleanup when done
  aws ec2 terminate-instances --instance-ids i-0EXAMPLE1234567890 --region us-east-1
  …then tear down the SG, subnet, IGW (detach first), VPC, instance profile
  (remove role first), and role. Want me to run the teardown now or leave it
  running?

Três coisas para notar:

• O agente fez um julgamento sobre qual VPC usar. Rodou DescribeVpcs, viu que a única VPC existente se chamava AWS_GOAT_VPC (um ambiente conhecido de treinamento em segurança), e escolheu construir networking do zero em vez de reusar. Razoável aqui, mas numa conta onde VPCs de produção não estão tão obviamente rotuladas, o mesmo raciocínio poderia provisionar no lugar errado com a mesma facilidade.
• Oito recursos a partir de um prompt de uma linha, sem portão de confirmação. VPC, IGW, subnet, route table, security group, IAM role, instance profile, instância. O call_aws não tem um “tem certeza?”: executa o que o IAM permitir, na hora.
• Tagging e um caminho de teardown foram cortesia, não garantia. O agente marcou tudo com purpose=ec2-test, createdBy=aws-agent-toolkit-blog e ofereceu um script de limpeza. Bacana, mas nada na plataforma exigiu nenhum dos dois.

A correção fica antes do agente: escope o IAM principal que o mcp-proxy-for-aws assume. Para os workflows de leitura de conta deste post, as três políticas gerenciadas acima reduzem o blast radius a zero.

Veredito

Vale instalar. Três peças, um workflow:

• Skills transformam prompts vagos em chamadas de API prescritas e impõem regras de disciplina.
• aws-mcp elimina a fiação de credenciais por serviço e coloca permissões no IAM.
• Sandbox run_script roda computação ao lado de dados de API ao vivo, então os resultados são derivados em vez de inferidos.

Uma coisa que não é específica do toolkit: qualquer agente de código com credenciais de cloud deve rodar com IAM de menor privilégio. Use read-only para trabalho read-only; busque permissões de escrita só quando você está conscientemente pedindo para o agente construir.