About Sample Shop MCP server
Sample Shop MCP server is a sample commerce integration built with the official TypeScript SDK, with equivalent implementations in Python, C#, and PHP. It demonstrates paginated reads, idempotent ordering, and confirmation-gated cancellation.
Key features
- 01Paginated product search and retrieval
- 02Idempotent order creation
- 03Cancellation requiring confirmation
- 04Implementations in four languages
Use cases
- 01Explore a sample shop catalog
- 02Create repeat-safe sample orders
- 03Test confirmation-gated cancellation flows
MCP support
It exposes product search, product retrieval, order creation, and guarded cancellation as MCP tools. It can run over stdio or Streamable HTTP.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://demo.apitoagents.com/mcpclaude mcp add --transport http apitoagents-sample-shop https://demo.apitoagents.com/mcp{"mcpServers":{"apitoagents-sample-shop":{"type":"http","url":"https://demo.apitoagents.com/mcp"}}}Open in Cursor{"servers":{"apitoagents-sample-shop":{"type":"http","url":"https://demo.apitoagents.com/mcp"}}}Open in VS Code{"mcpServers":{"apitoagents-sample-shop":{"type":"http","url":"https://demo.apitoagents.com/mcp"}}}{"mcpServers":{"apitoagents-sample-shop":{"serverUrl":"https://demo.apitoagents.com/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
4| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Page size. |
| query | string | No | Words to match against product names and descriptions. |
| cursor | string | No | Opaque token from a previous page's nextCursor. Never invent one. |
| category | enum | No | Restrict results to one category.lighting | furniture | kitchen |
Details
From the project README@apitoagents/sample-shop-mcp
An MCP server for a small sample shop, written with the official TypeScript SDK. It shows the three kinds of tool every real integration needs: paginated reads (search_products, get_product), an idempotent write (create_order) and a guarded action that refuses to run without explicit confirmation (cancel_order).
The same server exists in Python, C# and PHP, all passing one conformance scenario: github.com/apitoagents/mcp-examples. Walkthrough: apitoagents.com/docs/build-mcp-server-typescript.
Try it in one command (stdio)
npx @apitoagents/sample-shop-mcp
That starts the bundled Sample Shop API on 127.0.0.1:4010 and serves the MCP tools over stdio, which is what Claude Desktop, Claude Code and the MCP Inspector expect from a local server.
Claude Code:
claude mcp add sample-shop -- npx -y @apitoagents/sample-shop-mcp
Claude Desktop (claude_desktop_config.json):
{ "mcpServers": { "sample-shop": { "command": "npx", "args": ["-y", "@apitoagents/sample-shop-mcp"] } } }
Run it over Streamable HTTP
UPSTREAM_URL=http://127.0.0.1:4010 npx -p @apitoagents/sample-shop-mcp node node_modules/@apitoagents/sample-shop-mcp/dist/server.js
Or from a clone: npm ci && npm run build && npm start (listens on 127.0.0.1:3001/mcp). Environment: HOST, PORT, UPSTREAM_URL, UPSTREAM_API_KEY (default demo-key), ALLOWED_HOSTS (comma-separated public hostnames accepted in the Host header).
Public demo
A hosted copy runs at https://demo.apitoagents.com/mcp (in-memory data, resets regularly). Add it as a remote MCP server in Claude or ChatGPT and ask for a desk lamp.
MIT. Built by API to Agents, which designs and hosts servers like this for companies' own APIs.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.