A production-ready Model Context Protocol (MCP) Server built with Spring Boot 4, exposing ecommerce tools — product search, cart management, order lifecycle, inventory tracking, and coupon validation — to any AI client (Claude Desktop, GitHub Copilot, Cursor, Anthropic API).
This project demonstrates how to turn a Spring Boot ecommerce backend into an MCP Server — a standardized interface that allows AI models to call backend tools directly using natural language.
Instead of building a traditional REST API that humans call, an MCP server exposes structured tools that AI agents discover and invoke autonomously. You can ask Claude:
"Search for slim fit jeans under ₹1500, add one to Arjun's cart, validate coupon FLAT20, then place the order"
…and Claude will chain searchProducts → addToCart → validateCoupon → placeOrder automatically, returning a natural language summary.
What this server covers
Domain
Capabilities
Products
Full-text search, category/price/size filter, featured listings
Inventory
Stock status per SKU, low-stock alerts
Cart
Add/merge, view with totals, remove item, clear
Orders
Place, track, cancel (with stock restore), history, status update
22 integration tests covering all 6 feature domains. All run against the H2 in-memory database with seed data.
5. MCP Introduction & Core Components
What is MCP?
Model Context Protocol (MCP) is an open standard by Anthropic that defines how AI models communicate with external tools and data sources. It gives AI agents a structured way to discover and invoke backend capabilities — similar to how a browser uses HTTP to talk to web servers, MCP defines how an AI client talks to a tool server.
AI Client (Claude) ──MCP Protocol──▶ MCP Server (Your Spring Boot App)
│
┌─────▼──────┐
│ Tools │ searchProducts()
│ │ placeOrder()
│ │ addToCart()
└─────┬──────┘
│
┌─────▼──────┐
│ Services │
│ + JPA │
│ + H2 DB │
└────────────┘
Core MCP Concepts
Concept
Description
This Project
Tool
A callable function the AI can invoke
searchProducts, placeOrder, etc.
Tool Schema
JSON Schema describing inputs
Auto-generated from @ToolParam annotations
Transport
How client and server communicate
SSE (Server-Sent Events)
Session
Stateful connection per client
Managed by Spring AI automatically
Tool Discovery
Client fetches available tools at connect time
Via tools/list JSON-RPC call
Key Spring AI Annotations
// Marks a method as an MCP-callable tool
@Tool(description = "Human-readable description the AI uses to decide when to call this")
public ProductDto getProduct(
@ToolParam(description = "Product ID e.g. 'prod-001'") String productId
) { ... }
The description fields are critical — the AI reads them to understand when and how to call each tool. Write them like documentation for a developer, not for a user.
MCP Inspector is a purpose-built browser tool that handles SSE session management automatically, giving you a clean form-based interface for each tool.
npx @modelcontextprotocol/inspector
# Opens at http://localhost:6274
Set Transport → SSE, URL → http://localhost:8080/sse, click Connect. Then browse and invoke tools from the visual UI without managing sessions manually.
11. Integrating with AI Clients
Client 1 — Claude Desktop
Claude Desktop connects to local SSE servers via the mcp-remote Node.js proxy.
Look for the 🔨 hammer icon in the chat input — click to confirm tools are listed
Example conversations:
You: Show me all featured products
You: Search for blue jeans in size 32 under ₹1500
You: Add the Navy Polo shirt in size M to Arjun's cart (cust-001)
You: Check the stock level for prod-010
You: Place an order for cust-001 for a Formal White Shirt size M
and Slim Fit Jeans size 32, ship to Hyderabad, apply FLAT20 coupon
You: What's the status of order <orderId>?
You: Show me Arjun's last 5 orders
Client 2 — VS Code + GitHub Copilot
Requires VS Code 1.102+ and a GitHub Copilot subscription. MCP tools only work in Agent mode.
Option A — Workspace config (committed to repo, shared with team)
Verify: Cursor Settings → MCP — server should show as Connected.
Use in Composer (Ctrl+I) or Agent mode.
Client 4 — Anthropic API (direct integration)
Useful for building your own AI-powered frontend. The Anthropic API calls your MCP server from the cloud, so you need a public URL.
Expose localhost with ngrok (for testing):
ngrok http 8080
# Note the https URL e.g. https://abc123.ngrok.io
Python example:
import anthropic
client = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Search for jeans under ₹1500 in size 32 and add the cheapest one to cust-001's cart"
}],
mcp_servers=[{
"type": "url",
"url": "https://abc123.ngrok.io/sse", # your ngrok URL
"name": "ecommerce-mcp"
}],
betas=["mcp-client-2025-11-20"]
)
for block in response.content:
if block.type == "text":
print(block.text)
Node.js example:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const response = await client.beta.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{
role: "user",
content: "Show me all featured products and place an order for the cheapest t-shirt for cust-002"
}],
mcp_servers: [{
type: "url",
url: "https://abc123.ngrok.io/sse",
name: "ecommerce-mcp"
}],
betas: ["mcp-client-2025-11-20"]
});
console.log(response.content);
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Ecommerce?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Ecommerce necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.