# Sample Shop MCP server

> Sample Shop MCP server is an open-source MCP server for developer tools. Sample shop MCP server in four languages, showing read, write and guarded tools. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, self-hosted
- **Website:** https://apitoagents.com/docs
- **Repository:** https://github.com/apitoagents/mcp-examples/tree/HEAD/typescript
- **MCP Registry name:** io.github.apitoagents/sample-shop-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

The README presents this as a teaching server for a small sample shop, built with the official TypeScript SDK. It exposes paginated product reads (search_products, get_product), an idempotent order creation tool (create_order), and a cancellation tool that refuses to run without explicit confirmation (cancel_order).

It can run locally over stdio with a single npx command, which also starts a bundled Sample Shop API on localhost, or over Streamable HTTP for remote clients. A hosted demo endpoint is available for trying it from Claude or ChatGPT without installing anything. The README says the same server exists in Python, C# and PHP, and that all four pass one shared conformance scenario.

The server is aimed at developers who want a reference for wiring an existing API into MCP clients. The docs of the vendor, API to Agents, cover building, connecting and productionising such servers, and the vendor also offers paid done-for-you setup for companies' own APIs.

## Features

- **Paginated product reads:** Search and fetch product records through tools that return results in pages.
- **Idempotent order creation:** The create_order tool is designed so that repeated calls do not duplicate orders.
- **Guarded order cancellation:** The cancel_order tool refuses to run without an explicit confirmation step.
- **Stdio and HTTP transports:** Runs over stdio for local clients or Streamable HTTP for remote connections.
- **Four-language reference set:** The README says equivalent servers exist in Python, C# and PHP, sharing one conformance test.

## Good for

- Learning how to structure read, write and guarded tools in an MCP server
- Testing an MCP client such as Claude Desktop or the MCP Inspector against a working example
- Using the hosted demo endpoint to try an MCP shop assistant without installing anything
- Comparing MCP server implementations across TypeScript, Python, C# and PHP

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http sample-shop-mcp https://demo.apitoagents.com/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://demo.apitoagents.com/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "sample-shop-mcp": {
      "url": "https://demo.apitoagents.com/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "sample-shop-mcp": {
      "type": "http",
      "url": "https://demo.apitoagents.com/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "sample-shop-mcp": {
      "serverUrl": "https://demo.apitoagents.com/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "sample-shop-mcp": {
      "type": "http",
      "url": "https://demo.apitoagents.com/mcp"
    }
  }
}
```

## Tools

- `search_products`: Paginated product search.
- `get_product`: Fetch a single product.
- `create_order`: Idempotent order creation.
- `cancel_order`: Guarded cancellation that requires explicit confirmation.

## FAQ

### How do I run it locally?

The README says npx @apitoagents/sample-shop-mcp starts the bundled Sample Shop API on 127.0.0.1:4010 and serves the MCP tools over stdio.

### Is there a hosted version to try?

The README says a hosted copy runs at https://demo.apitoagents.com/mcp with in-memory data that resets regularly.

### What license is it under?

The README states the package is released under the MIT licence.

### Is Sample Shop MCP server free?

Yes. Sample Shop MCP server is open source, so you can use and self-host it for free.

### How do I add Sample Shop MCP server to Claude Code?

Run this command in your terminal: claude mcp add --transport http sample-shop-mcp https://demo.apitoagents.com/mcp

### What are the best alternatives to Sample Shop MCP server?

The closest alternatives to Sample Shop MCP server are MCP Foundry — Build, Test & Publish MCP Servers, meirinho.com.br, leitura para agentes and Makefile MCP.

## Where this comes from

- Description: written from the project's README, the project's website and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [MCP Foundry — Build, Test & Publish MCP Servers](https://ai-powered.com/mcp/mcp-foundry-build-test-and-publish-mcp-servers): MCP Foundry — Build, Test & Publish MCP Servers is a freemium MCP server for developer tools.
- [meirinho.com.br, leitura para agentes](https://ai-powered.com/mcp/meirinho-com-br-leitura-para-agentes): meirinho.com.br, leitura para agentes is an open-source MCP server for developer tools.
- [Makefile MCP](https://ai-powered.com/mcp/makefile-mcp-2): Makefile MCP is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/sample-shop-mcp-server
