How We Built a VTEX MCP Server with 700+ Tools in a Single Day

Last month, I sat down in the morning and by the end of the day had a working MCP server with 710 tools covering the entire VTEX API surface. 68 API domains: catalog, orders, pricing, logistics, payments, promotions, marketplace, and the rest. Typed inputs, Zod validation, authentication, retries. The same approach works for any platform that publishes an OpenAPI spec.

OpenAPI as the source

VTEX publishes OpenAPI specifications for all of their APIs in a public GitHub repository. 68 schema files, each one describing every endpoint, parameter type, and request body for a given API domain. Catalog, orders, logistics, intelligent search, marketplace, payments, all of it.

The key insight: these specs already contain everything an MCP tool needs. Endpoint, parameters, types, descriptions. I wrote a pipeline that reads them and generates MCP tools directly. Write the pipeline once, run it against any spec.

Four stages, spec to server

The adapter layer

The bridge between the generated SDK and MCP is a single function. Here's what each tool definition looks like in the registry:

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

createToolFromOperation does several things with that config. It takes the generated Zod request schema, which has the nested OpenAPI structure ({ path: { brandId: number }, query: { fields: string }, body: {...} }), and flattens it into a single-level input schema. An agent just sends { brandId: 123, fields: "name,slug" }. The function rewrites the schema to accept that flat version, validates the input through Zod, then un-flattens it back into the structured { path, query, body } shape the SDK expects before making the call.

The flattening rules: path params stay required. Query params become optional. If the body is a JSON object, its fields get promoted to top level. If it's something else (an array, a primitive), it stays nested under a body key. Headers are stripped entirely because the client interceptor injects X-VTEX-API-AppKey and X-VTEX-API-AppToken automatically.

There's a numeric coercion layer too. Tool UIs and agent frameworks often serialize numbers as strings. The adapter detects numeric Zod fields and wraps them in a union type that accepts both 123 and "123", then normalizes to the correct type before the SDK call. Without this, half the tools would fail on valid input.

Every tool also runs with retry logic: exponential backoff starting at 500ms, up to 3 retries, triggered on network errors, timeouts, 429 rate limits, and 5xx responses. Jitter is added to prevent thundering herds when multiple tools hit VTEX concurrently.

68 API domains

Any OpenAPI spec

The pipeline reads OpenAPI, not VTEX. Most platforms already publish specs: AWS, Stripe, Shopify, Twilio, Salesforce, GitHub. Swap the schemas and the same pipeline produces a working MCP server for a different platform. OpenAPI specs already contain everything an MCP tool needs: endpoint, parameters, types, descriptions. The generation step is mechanical.

We built this because we needed it. Our agents work with VTEX stores daily, and typed access to the full platform API makes them more reliable. The generated output is 68 domain modules, 1,100+ files, 14 MB of typed SDK code, none of it maintained by hand. Update the spec, re-run the pipeline.