This documentation reflects the current state of the MCIP MCP Server. It is designed for AI agents to interact with the product catalog via the Model Context Protocol (MCP).
The Model Context Protocol (MCP) is a standard open protocol that enables AI models to connect directly to external systems, data sources, and tools. It standardizes how AI agents discover capabilities and execute actions against APIs.
For more information, visit the official MCP documentation.
AI agents connect to this server using the HTTP transport layer.
Currently, the server exposes a single tool for product discovery. The input parameters are validated using Zod schemas to ensure type safety.
Tool: search-products
Description: Searches the product catalog based on a user query. It uses semantic search to interpret natural language intent.
Parameter: query (type: string) - the natural language query from the user (e.g., "affordable blue running shoes").
Below are conceptual examples of how an AI agent interacts with the search-products tool.
1. Request (Conceptual)
The AI agent identifies the need to search and sends a tool call request.
// The agent sends a request to execute the tool
{
"name": "search-products",
"arguments": {
"query": "gaming laptop under $1500"
}
}2. Response: Success
If products are found, the server returns a structured object containing search metadata and a list of ranked items.
{
"meta": {
"count": 8,
"take": 10,
"skip": 0,
"q": "Find me a laptop",
"filteringStatus": "AI_FILTERED",
"appliedFilters": {
"priceRange": {
"min": 0,
"max": 10000,
"currency": "USD"
},
"attributes": {
"category": "Electronics > Computers"
}
}
},
"items": [
{
"externalId": "1",
"url": "/product/laptop-example",
"title": "Laptop",
"description": "Now equipped with seventh-generation Intel Core processors, Laptop is snappier than ever. From daily tasks like launching apps and opening files to more advanced computing, you can power through your day thanks to faster SSDs and Turbo Boost processing up to 3.6GHz.",
"category": "Electronics > Computers",
"brand": "Generic",
"price": {
"amount": 1558.8,
"currency": "USD"
},
"mainImage": "http://exaxmple.com/assets/preview/71/derick-david-409858-unsplash__preview.jpg",
"attributes": [
{
"name": "Feature",
"value": "Electronics"
},
{
"name": "Feature",
"value": "Computers"
},
{
"name": "Feature",
"value": "Apple"
},
{
"name": "13-inch",
"value": "13 inch"
},
{
"name": "8gb",
"value": "8GB"
}
],
"variants": [
{
"sku": "L2201508",
"title": "Laptop 15 inch 8GB",
"price": {
"amount": 1678.8,
"currency": "USD"
},
"available": true
},
{
"sku": "L2201316",
"title": "Laptop 13 inch 16GB",
"price": {
"amount": 2638.8,
"currency": "USD"
},
"available": true
},
],
"score": 0.5319843
},
...
]
} 3. Response: No Results
If the search yields no matches, the server returns a direct text response informing the agent.
// The server responds with a text notification
{
"content": [
{
"type": "text",
"text": "No products found for query: \"nonexistent item xyz\""
}
]
}