Moretes AWS Architect MCP

Arquitetura AWS com evidências, ferramentas abertas e decisões revisáveis.

By Fernando Azevedo · MIT · Node.js 22.13+ · Streamable HTTP + stdio

Um workbench MCP para levantar requisitos, comparar alternativas, consultar a documentação oficial da AWS, desenhar arquiteturas, produzir ADRs e preparar a operação. O modelo do seu cliente (Codex, Claude ou Kiro) conduz o raciocínio; as ferramentas devolvem cálculos, estruturas, fontes e lacunas explícitas. O servidor não chama modelos pagos.

English: An evidence-first AWS architecture workbench for your MCP client. Deterministic design tools, live official AWS knowledge, a versioned integration catalog, and optional authenticated local AWS tooling. See English guide.

Status and scope

24 public tools; up to 29 in explicitly enabled local mode. A catalog entry is not a hosted integration, a tested provider, or a permission grant. The public deployment cannot operate your AWS account. Authenticated AWS access runs locally using your own credentials. This release does not provide remote account OAuth, multi-tenant delegated IAM, background jobs, or automatic deployment.

Connect

The deployed endpoint and verification record are in deployment.md. Replace <MCP_URL> below with that URL.

# Codex
codex mcp add moretes-architect --url <MCP_URL>

# Claude Code
claude mcp add --transport http moretes-architect <MCP_URL>

Kiro configuration:

{"mcpServers":{"moretes-architect":{"url":"<MCP_URL>","disabled":false,"autoApprove":[]}}}

No API key is needed for the public endpoint. It has a shared daily allowance; install locally for unrestricted local design calculations. See client setup, including local Claude Desktop configuration.

Run locally

git clone https://github.com/fernando-moretes/moretes-aws-architect-mcp.git
cd moretes-aws-architect-mcp
npm ci --ignore-scripts
npm test
npm run build
npm start                       # MCP stdio; do not expect a chat UI
# Or in another terminal:
npm run http                    # http://127.0.0.1:8787/mcp + landing page

npm start writes protocol messages to stdout only. Diagnostics belong on stderr. Node.js, your MCP client and optional uv are prerequisites. There is no npm registry release of this project yet; clone a tagged GitHub release.

Use at work

“Use o Moretes Architect. Preciso de uma API para processar pedidos. Pergunte primeiro sobre tráfego, dados, SLO e orçamento. Compare Lambda e ECS, pesquise a documentação AWS, faça o diagrama e um ADR com hipóteses e testes pendentes.”

“Revise este desenho pelos seis pilares. Só marque um controle como atendido quando houver evidência. Mostre lacunas, responsável e critério de validação.”

“Planeje um ensaio de falha depois de gravar no alvo, mas antes de registrar sucesso. Explique como reconciliar sem repetir o efeito.”

Do not send confidential architecture, secrets or customer data to the public service. Use local stdio for private design inputs; the AWS Knowledge and public GitHub tools still transmit their explicit queries externally. Privacy and boundaries.

Integrate official AWS servers

Use integration_catalog to discover servers by service/category, then integration_config for a pinned setup. Review the linked official prerequisites; packages have different permissions, dependencies, flags and costs. Generated Kiro configs start disabled with no auto-approved tools.

For a single local workbench, the optional federation bridge starts only version-pinned official packages already installed in the uv cache, after account verification. An owner-reviewed file lists exact tools permitted per provider. There is no public arbitrary proxy, shell tool, package installer or dynamic URL dispatcher. Integration guide.

Architecture

flowchart LR
  C[Codex / Claude / Kiro] -->|Streamable HTTP| G[API Gateway: throttling]
  G --> L[Lambda: public MCP]
  L --> Q[DynamoDB: daily quota only]
  L --> K[AWS Knowledge: official public docs]
  L --> H[GitHub: public metadata]
  C -->|stdio, optional| S[Local MCP]
  S --> A[User SDK credentials + account guard]
  A --> R[Read-only AWS tools]
  A --> F[Installed official servers + exact allowlist]

The Lambda role can update only its quota table and write its own logs. No portfolio buckets, IAM administration, Bedrock invocation, STS delegation or application resource access. Design · Costs · Runbook.

Quality and maintenance

npm run typecheck
npm test
npm run build
npm audit --omit=dev
npm run smoke -- <MCP_URL>        # makes a live, public AWS docs query

CI runs on Node 22 and 24. Offline tests exercise real MCP SDK initialization, tools, resources, prompts and stateless HTTP, along with negative input and isolation cases. Live tests are opt-in and are not implied by unit tests. Validation record.

• Tool reference
• Workshop
• Contributing
• Security
• Roadmap
• Changelog
• Source attribution

This independent project is not an AWS product, official Well-Architected review, security certification or guarantee of pricing. AWS and other product names belong to their respective owners.