How We Built YeloScale: An MCP-Ready Ecommerce Platform for the AI Search Era
YeloScale is a commerce and delivery platform built by OHY Labs for merchants who sell online and ship with cash on delivery. It generates a storefront from the merchant workspace, publishes pages that Google and AI assistants can read, and exposes a secure MCP server so AI agents can work with orders, products, and stores. This case study explains what we built, why, and how AI-assisted engineering shaped the result.
The Problem: Merchants Run on Ten Disconnected Tools
A typical merchant sells through a social page and a marketplace, tracks stock in a spreadsheet, creates shipments on each delivery provider’s portal, and reconciles cash-on-delivery payments by hand. Every order touches five systems and nobody owns the truth.
We wanted one workspace where the merchant owns products, stock, orders, shipments, and payments, and where external stores and delivery providers plug in as integrations rather than acting as the database. That principle, that the platform is the source of truth, became the rule that constrained every later design decision.
- Products and variants with stock across depots and warehouses.
- Orders imported from Shopify, WooCommerce, or created by hand.
- Orders converted to shipments and pushed to delivery providers such as Massar, Sendex, First Delivery, Aramex, DHL, FedEx, and UPS.
- Manifests per provider, shipment tracking, and cash-on-delivery reconciliation.
- Team members, roles, and workspace settings with strict tenant isolation.
Architecture: A Multi-Tenant Command Center
YeloScale is a monorepo with a React and Vite frontend, a NestJS SaaS backend on Postgres, a Fastify delivery gateway with Prisma and BullMQ workers, and separate invoice and image services. Redis handles caching and queues. Everything ships as Docker containers with blue/green deployments so releases do not interrupt merchants during a sale.
Every table, service, API route, and UI view is scoped by workspace. Provider credentials are encrypted at rest. The frontend loads views as lazy chunks so the high-traffic pages, orders and shipments, stay fast on a phone in a warehouse.
Why the delivery gateway is a separate service
Delivery providers have inconsistent APIs, rate limits, and failure modes. Isolating them behind one gateway with queued workers means a slow carrier never blocks the merchant dashboard, and every provider call is retried and logged in one place.
Storefronts Generated from the Workspace
A merchant does not build a website. They publish a store, and YeloScale generates it from what already exists in the workspace: products, collections, prices, stock, and delivery rules. The storefront lives on a yeloscale.shop link or a custom domain, and it reuses the same cart, checkout, and cash-on-delivery flow across every store.
Storefront sections, product cards, and campaign pages are templates the merchant configures rather than code they write. Scheduled drops add countdowns and launch locks that the server enforces, so a customer changing their browser clock cannot unlock a product early.
- Store, product, and collection pages generated from catalog data.
- Custom domains with automatic certificates, plus yeloscale.shop subdomains.
- Scheduled drops with countdowns, launch locks, and cache expiry at the launch boundary.
- Redis-cached catalog reads with zero-downtime publishing.
Built for Google and AI Search, Not Only Followers
Most AI crawlers do not execute JavaScript. A client-rendered store is invisible to ChatGPT, Claude, and Perplexity, and a weak baseline even for Google. So YeloScale renders public store pages on the server, with real HTML content, clean URLs, and structured data layered on top.
Each store publishes Store, Product, Offer, CollectionPage, and BreadcrumbList JSON-LD, its own robots.txt and sitemap.xml, and an llms.txt file that summarises the store for language models. A public store directory with server-side search lets people, and AI assistants, find a store that sells a specific product.
Why this matters for a small merchant
Discovery used to depend on how many followers a merchant had. With crawlable, structured pages, a shop in Tunis can be surfaced by an AI assistant answering “where can I buy X” without paying for ads. This is the same generative engine optimisation discipline OHY Labs applies to its own site.
The MCP Server: Letting AI Agents Work with Orders and Products
MCP, the Model Context Protocol, gives an AI agent a menu of approved tools with clear schemas and permissions. YeloScale ships a remote MCP server over Streamable HTTP at a single endpoint, protected by OAuth bearer tokens from an external identity provider, with discovery metadata so MCP clients can connect without custom code.
Before writing a single tool we classified every backend capability into five exposure categories. Public read-only tools need no auth but are rate limited. Authenticated reads require membership, scope, and the workspace permission. Reversible writes add strict schemas, idempotency keys, and audit entries. Sensitive or destructive actions use a two-stage prepare-and-confirm flow with a signed, single-use token bound to the actor and tenant. Some capabilities are intentionally never exposed.
- Live tools: list and get orders, list and get products, list workspaces, and search the public store directory.
- A Category-D example: removing a team member requires a prepare call, then a confirm call with a single-use token.
- Tenant context is derived from the authenticated principal, never from a tool argument.
- Scopes such as orders:read or catalog:write map to fine-grained workspace permissions that are re-checked on every call.
- Per-tool rate limits, request and response size caps, replay protection, and audit logging to the activity log.
- A master kill switch keeps the whole MCP surface off until the identity provider and Inspector checks pass.
What an agent can do with it
A sales agent can answer “which orders from yesterday are still unpaid” from real data. A support agent can look up a product and its stock before replying to a customer. A research agent can search the store directory for merchants selling a category. None of them can bypass the permission the human already has.
How AI Agents Helped Build It
YeloScale was built by a small team working with AI coding agents. The method is spec first: each feature starts as a written design document with problem, constraints, what already exists, and what must not be rebuilt. Agents implement against that spec in small tasks, each with a brief and a report, and every change runs through automated tests before review.
This is why the repository contains audits of the full order workflow, a threat model for the MCP server, a feature-to-MCP matrix, load-testing notes, and an operations runbook. The documentation is not an afterthought; it is the input that made AI-assisted development reliable.
- Design specs and per-task briefs as the contract between humans and agents.
- Unit and protocol tests on backends, including MCP handshake and tool registration.
- Security reviews for tenant isolation before any multi-workspace feature ships.
- Blue/green Docker deployments driven from CI so releases are boring.
What Merchants Get
A merchant gets a real online store, orders and cash-on-delivery in one place, shipments sent to any supported carrier, and pages that Google and AI assistants can read. Their business also becomes agent-ready: when they add an AI sales or support agent, the MCP server is already there with the right permissions.
For OHY Labs, YeloScale is the reference implementation of what we mean by MCP-friendly infrastructure. The same approach, source-of-truth platform, generated public surfaces, and a scoped MCP layer, is what we bring to client platforms.