Sample Shop MCP server

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.