# Sample Shop MCP server [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/apitoagents/mcp-examples  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sample-shop-mcp-server

## Description
Sample shop MCP server: paginated search, idempotent orders, guarded cancellation. Four languages.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What Sample Shop MCP server does

Sample Shop MCP server MCP server connects MCP clients to a small Sample Shop REST API. The repository provides equivalent implementations in TypeScript, Python, C# and PHP, each exposing the same four tools through the same interface. It is intended both as a working shop integration and as a reference for building an API-backed MCP server.

The project belongs in the 🛒 E-Commerce category because its example API handles products and orders. It can support clients that need to browse a product list, inspect one product, place an order or cancel an order under explicit conditions.

## How it works

Each implementation runs as a stateless Streamable HTTP MCP endpoint at `/mcp`, except that the PHP example uses a file-based session store. The servers forward requests to the sample API, which runs separately on `127.0.0.1:4010` and expects the `X-API-Key` header. The upstream key remains in the server environment rather than being exposed to the assistant.

The four tools have distinct behaviors:

- `search_products` returns summarized product results and uses an opaque `nextCursor` for pagination.
- `get_product` looks up a product by ID and reports a non-retryable not-found error when appropriate.
- `create_order` accepts an idempotency key so a retry after a timeout does not create another order.
- `cancel_order` requires `confirm=true` before performing the cancellation.

Tool annotations identify read-only, destructive and idempotent behavior. Errors distinguish invalid input, missing resources, conflicts and upstream unavailability, with guidance for the next action.

## Setup and configuration

Start the sample API with Node.js, then choose one language implementation. The TypeScript, Python, C# and PHP commands are documented in the repository and expose ports 3001, 3002, 3003 and 3004 respectively. A conformance test can run against the MCP URL of whichever implementation is active.

The servers read `UPSTREAM_URL` and `UPSTREAM_API_KEY`. They default to `http://127.0.0.1:4010` and `demo-key`, matching the included sample API. The language examples use Streamable HTTP URLs such as `http://127.0.0.1:3001/mcp`.

Sample Shop MCP server MCP server has no authentication on its MCP endpoint by default. That is suitable for local use but not for direct public exposure; an externally deployed instance should add bearer-token or OAuth protection.

## Tools and capabilities

The main capability set is deliberately limited to four outcome-focused tools rather than mirroring every REST endpoint. This makes the Sample Shop MCP server MCP server useful for examining boundaries between reads, writes and guarded actions.

The repository also includes a conformance scenario that runs the same workflow against all four implementations. Developers adapting the example can replace the sample API description and shop client calls, then update the conformance test for the new tool behavior.

## Limitations and notes

The included service is an example API, not a production commerce backend. The MCP endpoint has no built-in authentication, and the README does not describe inventory, payments, customer accounts or shipping features. The PHP implementation requires PHP 8.2 or later; the other language directories have their own SDK and runtime requirements.

The repository is MIT licensed. ChatGPT, Claude and other MCP clients can connect through the Streamable HTTP endpoint, subject to the client’s connector or MCP configuration support.

_Full upstream README: https://allmcps.com/mcp/sample-shop-mcp-server/readme_