retail-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@retail-mcp check inventory for SKU-12345"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Retail Enterprise MCP Portfolio
A complete enterprise portfolio that connects AI clients to retail customer, inventory, sales, order, and support capabilities through the Model Context Protocol (MCP). It combines strategic assessment, a working server, and production security/deployment artifacts in one repository.
Portfolio coverage
MCP architecture assessment and design: architecture, MCP evaluation, risk assessment, ROI, and executive summary.
Production MCP server: resources, tools, prompt, PostgreSQL adapter, Redis cache, connection pool, validation, transactions, idempotency, tests, and API documentation.
Enterprise framework: security, Prometheus/Grafana, Docker, Kubernetes, TLS gateway, CI/CD, deployment, and disaster recovery.
Multi-agent extension proposal: dialogue synthesis, safeguards, conflict resolution, and human intervention.
Related MCP server: RL-MCP
Architecture
flowchart LR
U[Enterprise User] --> H[AI Host / MCP Client]
H -->|Streamable HTTP + TLS| G[Gateway / WAF]
G --> M[Stateless MCP Replicas]
M --> A[Authentication + RBAC]
A --> R[Resource Manager]
A --> T[Tool Manager]
R --> C[(Redis Cache)]
R --> P[Connection Pool]
T --> P
P --> D[(PostgreSQL)]
D -. adapters .-> E[CRM / ERP / Inventory / Support]
M --> O[Metrics / Audit / Alerts]The editable diagram is docs/architecture.mmd.
MCP contract
Resources
URI template | Permission | Description |
|
| Customer profile with role-based PII filtering |
|
| Quantity, reorder threshold, and price |
|
| Confirmed retail sale |
Tools
Tool | Permission | Safety property |
|
| Transaction, row lock, idempotency key, stock validation |
|
| Bounds validation, non-negative invariant, cache invalidation |
|
| Length/control-character validation and audit event |
The investigate_customer_issue prompt provides workflow guidance but grants no permission.
Quick start
Prerequisites: asdf, uv, and optionally Docker. The repository pins Python in
.tool-versions, following the workspace standard.
asdf install
asdf current python
cp .env.example .env
uv sync --python "$(asdf which python)" --extra dev
uv run pytest
uv run retail-mcp --transport httpIn another terminal, run the non-destructive protocol smoke test, or let it manage a
temporary local server with --start-server:
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --start-serverConnect an MCP client to http://localhost:8000/mcp and send one of these headers:
X-API-Key: dev-admin-keyor:
Authorization: Bearer dev-admin-keyBundled keys work only in development. Production mode rejects them. For STDIO:
RETAIL_MCP_STDIO_API_KEY=dev-admin-key uv run retail-mcp --transport stdioFull stack
docker compose up --build -d
docker compose ps
curl http://localhost:8000/health/readyServices:
MCP server:
localhost:8000/mcpPrometheus:
localhost:9090Grafana:
localhost:3000PostgreSQL and Redis: private Compose network only
See deployment.md for production Compose, Kubernetes, TLS, secrets, SLOs, scaling, and rollback.
Configuration
All settings use the RETAIL_MCP_ prefix.
Variable | Purpose | Production requirement |
|
|
|
|
|
|
| PostgreSQL DSN | Secret |
| Shared cache URL | Secret/private endpoint |
| JSON key/subject/role records | Secret; no |
| Credential for local STDIO process | Environment secret |
| Per-principal application limit | Tune from load test |
| Dependency operation timeout | Below gateway timeout |
Example API_KEYS value:
[
{"key": "a-long-random-secret", "subject": "support-agent", "role": "customer_service"}
]API keys are the scenario's required authentication mechanism. Enterprise evolution should replace them with OAuth 2.1 and audience-bound tokens while retaining the same Principal and RBAC boundary.
Quality and validation
uv run ruff check .
uv run ruff format --check .
uv run pytest
docker compose config
docker build -t retail-mcp:local .The CI pipeline performs linting, tests with coverage, package build, dependency review, and container build. Before production, add organization-specific SAST, secret scanning, image vulnerability scanning, signing, provenance, and deployment approval.
Repository map
src/retail_mcp/ MCP server and enterprise application layers
tests/ Unit, authorization, resilience, and API tests
migrations/ PostgreSQL schema and seed data
monitoring/ Prometheus alerts and provisioned Grafana dashboard
deploy/ TLS gateway and Kubernetes deployment/HPA
docs/ Architecture, business, security, operations, and DR
.github/workflows/ CI pipelineImportant limitations
The API-key manager is intentionally replaceable; use the corporate IdP for user-delegated production access.
The sample is single-tenant. Tenant identity must be enforced in principals, queries, row policies, and cache keys before multi-tenant use.
The PostgreSQL projection represents integration with systems of record; real CRM/ERP adapters and synchronization are organization-specific.
Performance and ROI figures are hypotheses until validated with production-like load tests and business measurements.
Available Tools
3 toolscreate_support_ticketB
Create a customer support ticket. Requires ticket:write.
Inputs: subject (required), customer_id (required), description (required), priority. Returns: object
process_orderB
Create an order atomically and decrement inventory. Requires order:write.
Inputs: sku (required), quantity (required), customer_id (required), idempotency_key (required). Returns: object
update_inventoryA
Adjust inventory with validation and audit logging. Requires inventory:write.
Inputs: sku (required), reason (required), quantity_delta (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct domain action: support ticket creation, order processing, and inventory updating. No two tools overlap in purpose, ensuring clear differentiation for an agent.
All tools follow a consistent verb_noun pattern (create_support_ticket, process_order, update_inventory), making the naming predictable and easy to navigate.
With only 3 tools, the server feels sparse for a retail domain, which typically involves many more operations (e.g., product listings, customer management). However, the tools are focused and non-redundant.
The tools cover core retail actions (support, order processing, inventory) but miss obvious CRUD operations like reading or searching orders/inventory, creating products, or listing customers, leaving notable gaps.
Maintenance
Related MCP Connectors
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Connect AI agents to Replynodes over the Model Context Protocol.
Related MCP Servers
- FlicenseBqualityDmaintenanceImplements the Model Context Protocol (MCP) to provide AI models with a standardized interface for connecting to external data sources and tools like file systems, databases, or APIs.1153-
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.2-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to securely access and act on CRM, order, support, and automation systems through the Model Context Protocol, with authentication, authorization, audit logging, and guardrails.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to discover and invoke enterprise tools like web search, document parsing, meeting scheduling, and email through a unified Model Context Protocol server that aggregates and routes across multiple backends.1-