Como Construímos um Servidor VTEX MCP com 700+ Ferramentas em um Único Dia

Mês passado, sentei pela manhã e até o final do dia tinha um servidor MCP funcional com 710 ferramentas cobrindo toda a superfície da API VTEX. 68 domínios de API: catálogo, pedidos, preços, logística, pagamentos, promoções, marketplace, e o resto. Inputs tipados, validação com Zod, autenticação, retries. A mesma abordagem funciona para qualquer plataforma que publica um spec OpenAPI.

OpenAPI como fonte

VTEX publica especificações OpenAPI para todas as suas APIs em um repositório GitHub público. 68 arquivos de schema, cada um descrevendo cada endpoint, tipo de parâmetro e corpo da requisição para um dado domínio de API. Catálogo, pedidos, logística, busca inteligente, marketplace, pagamentos, tudo isso.

A percepção-chave: esses specs já contêm tudo que uma ferramenta MCP precisa. Endpoint, parâmetros, tipos, descrições. Escrevi um pipeline que os lê e gera ferramentas MCP diretamente. Escreva o pipeline uma vez, execute contra qualquer spec.

Quatro estágios, spec para servidor

A camada de adaptador

A ponte entre o SDK gerado e MCP é uma única função. Aqui está como cada definição de ferramenta fica no registry:

createToolFromOperation({
  id: "VTEX_GET_BRAND",
  description: "Get brand details by ID.",
  annotations: { readOnlyHint: true },
  requestSchema: catalogZod.zGetBrandData,
  sdkFn: catalogSdk.getBrand,
})

createToolFromOperation faz várias coisas com essa configuração. Pega o schema de requisição Zod gerado, que tem a estrutura OpenAPI aninhada ({ path: { brandId: number }, query: { fields: string }, body: {...} }), e o achata em um schema de input de nível único. Um agent apenas envia { brandId: 123, fields: "name,slug" }. A função reescreve o schema para aceitar essa versão flat, valida o input através do Zod, depois desachata de volta para a forma estruturada { path, query, body } que o SDK espera antes de fazer a chamada.

As regras de achatamento: parâmetros de path permanecem obrigatórios. Parâmetros de query se tornam opcionais. Se o body é um objeto JSON, seus campos são promovidos para o nível superior. Se for algo mais (um array, um primitivo), permanece aninhado sob uma chave body. Headers são removidos inteiramente porque o interceptador de cliente injeta X-VTEX-API-AppKey e X-VTEX-API-AppToken automaticamente.

Há também uma camada de coerção numérica. UIs de ferramentas e frameworks de agents frequentemente serializam números como strings. O adaptador detecta campos Zod numéricos e os envolve em um tipo union que aceita tanto 123 quanto "123", depois normaliza para o tipo correto antes da chamada SDK. Sem isso, metade das ferramentas falharia com input válido.

Cada ferramenta também roda com lógica de retry: exponential backoff começando em 500ms, até 3 retries, disparado em erros de rede, timeouts, rate limits 429, e respostas 5xx. Jitter é adicionado para prevenir thundering herds quando múltiplas ferramentas batem na VTEX concorrentemente.

68 domínios de API

Qualquer spec OpenAPI

O pipeline lê OpenAPI, não VTEX. A maioria das plataformas já publica specs: AWS, Stripe, Shopify, Twilio, Salesforce, GitHub. Troque os schemas e o mesmo pipeline produz um servidor MCP funcional para uma plataforma diferente. Specs OpenAPI já contêm tudo que uma ferramenta MCP precisa: endpoint, parâmetros, tipos, descrições. O passo de geração é mecânico.

Construímos isso porque precisávamos. Nossos agents trabalham com lojas VTEX diariamente, e acesso tipado à API da plataforma completa os torna mais confiáveis. O output gerado é 68 módulos de domínio, 1.100+ arquivos, 14 MB de código SDK tipado, nada disso mantido à mão. Atualize o spec, execute o pipeline novamente.