The MCP adaptor layer

What is MCP, and how QuickCart uses it

MCP (Model Context Protocol) is an open standard for exposing tools and resources to an agent runtime over JSON-RPC 2.0. A server advertises a list of callable tools (each with a JSON-Schema for its inputs), and a client invokes them by name over a transport — either stdio for a co-located process or streamable HTTP+SSE for a networked one. The protocol is transport-agnostic and schema-first, which is exactly what we want when talking to five very different retail backends.

QuickCart runs a single gateway service — mcp-adaptor — that fronts five per-platform MCP servers, one each for Blinkit, Zepto, BigBasket, Flipkart and Amazon. Every adaptor implements the same normalised tool contract (§4), so the Aggregation service can fan a query out to all five with identical call sites and merge the results without special-casing any platform. Each adaptor is a thin translator: it maps our canonical tool call onto whatever surface the platform genuinely offers, then maps the platform's native response back into QuickCart's canonical schema.

Put differently: MCP is our internal integration boundary. It is not something these retailers publish — it is how we choose to wrap them so a new source is "just another adaptor speaking the same eleven tools."

Adaptor topology

The Aggregation service never speaks to a retailer directly. It speaks MCP to the mcp-adaptor gateway, which routes each canonical tool call to the right per-platform server. Each server owns the credentials, rate-limit budget, native request shape and response-normalisation for exactly one platform.

The unified tool contract

Every adaptor implements the same eleven tools. Read tools are mandatory; write tools are optional and only wired up where a platform's commerce API genuinely permits programmatic cart/checkout. All price fields are in ₹ (INR); all availability and ETA calls are location-scoped because quick-commerce stock is hyperlocal.

{
  "name": "get_offers",
  "description": "Coupons and auto-applied discounts for a product at a location",
  "inputSchema": {
    "type": "object",
    "required": ["sourceProductId", "location"],
    "properties": {
      "sourceProductId": { "type": "string" },
      "location": {
        "type": "object",
        "required": ["lat", "lng"],
        "properties": {
          "lat": { "type": "number" },
          "lng": { "type": "number" },
          "pincode": { "type": "string" }
        }
      }
    }
  }
}

{
  "sourceId": "blinkit",
  "sourceProductId": "blk_88213",
  "offers": [
    { "code": "WELCOME50", "type": "FLAT", "value": 50, "minCart": 199, "expiresAt": "2026-09-30T18:30:00Z" },
    { "code": null, "type": "AUTO_PERCENT", "value": 10, "appliesTo": "item" }
  ],
  "fetchedAt": "2026-09-08T10:14:22Z",
  "ttlSeconds": 120
}

Per-platform adaptors

Same eleven tools, five very different realities. The strength of each platform maps directly to what it is: quick-commerce players are unbeatable on hyperlocal stock and ETA; the marketplaces are richer on catalogue depth, MRP and reviews. Access mechanisms and limits below are illustrative of each platform's real posture, not published MCP specs.

Capability matrix

What each adaptor can actually return today, given the access mechanisms above. This is the single most important table in the document — the Aggregation service degrades gracefully around every ◑ and ✕.

✓ Fully supported ◑ Partial / conditional (hover for the caveat) ✕ Not available via sanctioned access

Quick-commerce write/checkout cells are ◑ because they depend on a commerce partnership; marketplace checkout is ✕ because affiliate/PA-API programs deliberately exclude programmatic consumer purchase.

To what extent can we use them?

The honest answer differs per capability, not just per platform. Four axes govern everything:

Field mapping

Each adaptor's job ends here: collapse a native payload into QuickCart's canonical fields. Native field names below are illustrative — exact for Amazon PA-API, representative for the partner APIs whose schemas aren't public.

Sample MCP call

A single search_products invocation against the Blinkit adaptor over JSON-RPC, and the normalised list it returns. Note the adaptor has already collapsed Blinkit's native payload into our canonical fields — the caller never sees a Blinkit-shaped object.

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "amul butter 500g",
      "location": { "lat": 12.9716, "lng": 77.5946, "pincode": "560001" },
      "limit": 5
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [{ "type": "json", "json": {
      "sourceId": "blinkit",
      "products": [
        {
          "sourceProductId": "blk_88213", "title": "Amul Butter (Pasteurised)",
          "brand": "Amul", "packSize": "500 g",
          "mrp": 290, "sellingPrice": 278, "effectivePrice": 265,
          "inStock": true, "quantityAvailable": 14,
          "deliveryEstimate": { "minutes": 9, "deliveryFee": 0 },
          "image": "https://cdn.example/blk_88213.jpg"
        }
      ],
      "fetchedAt": "2026-09-08T10:14:22Z"
    } }]
  }
}

On the Aggregation side, the same call is one line via the MCP client — the gateway hides transport and auth:

import { mcp } from "./mcpAdaptorClient";

// Fan a single canonical tool out to one source; the adaptor normalises the shape.
export async function searchSource(sourceId, query, location) {
  const res = await mcp.call(sourceId, "search_products", {
    query, location, limit: 5
  }, { timeoutMs: 800 });       // per-source deadline; see Doc 05
  return res.products;                     // already in canonical schema
}

How these five per-source results are merged, SKU-matched and ranked into a single best-price answer is the subject of Document 05 — Price & Availability Engine.