Shopping MCP Server

Project Overview

• Name: Shopping MCP Server
• Version: 1.0.0
• Type: Production TypeScript MCP (Model Context Protocol) server
• Platform: Infosys Equinox agentic shopping assistant
• Purpose: Let AI agents drive complete B2B and B2C shopping journeys - catalog browsing, search, cart, pricing, addresses, payments, and order placement - against a large enterprise commerce platform spanning many microservices and APIs

This is a closed-source, IP-protected component of Infosys Equinox. The description below covers architecture and engineering concepts only; no proprietary code, endpoints, or business logic is disclosed.

My Role / Contribution

I built and own this server end to end - the transport and auth layer, the tool surface exposed to agents, the inline UI rendering pipeline, and the security and multi-pod design decisions described below. The work spans protocol implementation (MCP, OAuth 2.1), agent-experience design (how a model perceives and operates a shopping flow), and production-hardening concerns (statelessness, secret handling, resilience) for a horizontally scaled deployment.

Key Capabilities

• Dual-result pattern - every interaction returns both structured data for the agent to reason over and a self-contained interactive HTML UI that renders inline within the assistant chat for the end user
• Inline MCP Apps UIs - rich storefront interfaces (search results, product detail, cart, orders, payments, address book, profile, secure entry forms) delivered as single-file HTML bundles and rendered directly in the conversation
• Full B2B and B2C checkout - end-to-end flows from browsing through order placement, including the purchase-order path for business buyers
• OAuth 2.1 authentication - PKCE / S256, with both a self-hosted authorization-server mode and an external-issuer introspection mode, selectable by configuration
• Multi-transport - stdio, SSE, and Streamable HTTP served from a single codebase for flexible local and production deployment
• Composite agent tools - one tool exposes many related backend operations through an action selector, consolidating a sprawling API surface into a small, agent-friendly toolset

Architecture (High Level)

Transport and request lifecycle

• A fresh MCP server instance is created per request over the HTTP transport, keeping the process stateless so it scales cleanly across multiple pods behind a load balancer
• Connection lifecycle, structured request logging, JSON error envelopes, and health and readiness endpoints are handled at the Express layer
• The server supports both a default-tenant route and a tenant-scoped route, with the storefront identifier resolved per request

Authentication

• Self-hosted OAuth mode: the server acts as its own authorization server, implementing dynamic Protected Resource Metadata (RFC 9728), authorization-server metadata (RFC 8414), dynamic client registration (RFC 7591), and PKCE
• Introspection mode: integrates with an external issuer via metadata advertisement and token introspection
• Metadata and auth routes are mounted to be reverse-proxy aware, so discovery works whether the server is reached directly or through an upstream proxy

Session resolution (multi-pod safe)

A layered strategy keeps authenticated flows working without assuming shared in-memory state:

1. A session identifier the model is instructed to carry on each call (primary, multi-tenant safe)
2. The OAuth bearer token from the authenticated request (per-request, needs no shared state)
3. A guarded server-side fallback, disabled by default because it is neither cross-pod reliable nor safe in a shared process

Secure payment handling

• The card verification value never reaches the LLM in plaintext
• It is sealed into an encrypted, self-contained token (AES-256-GCM) bound to the payment reference with a short time-to-live, so any pod sharing the key can decrypt it server-side at the moment of payment
• Only the encrypted token travels through the conversation; the raw value is injected into the backend request and never forwarded onward

Resilience and agent ergonomics

• Shared API layer with request timeouts and a single retry on transient 5xx and network errors
• Centralized 401/403 detection that returns model-actionable guidance (prompt the user to re-authenticate and re-display the login UI) instead of blind retries
• Response summarizers shape verbose backend payloads into concise, agent-consumable results

Technical Stack

• Language: TypeScript (ES modules, strict)
• Protocol: Model Context Protocol via the official MCP SDK and the MCP Apps extension (SEP-1865)
• Server: Express 5 with CORS and DNS-rebinding protection
• Auth: OAuth 2.1 - PKCE, RFC 9728 / RFC 8414 / RFC 7591
• Validation: Zod schemas for every tool input
• Crypto: Node crypto (AES-256-GCM) for sealed secret tokens
• UI build: Vite single-file HTML bundles for inline MCP Apps interfaces
• Tooling: tsx, pnpm, concurrently for the build and dev workflow