MCP server examples: one API, four languages, one tool interface
Ready-to-clone examples that expose a REST API to ChatGPT, Claude and any other MCP client, written with the official Model Context Protocol SDKs for TypeScript, Python, C# and PHP. All four servers wrap the same small Sample Shop API and publish an identical set of four tools, and a conformance test proves it by running the same scenario against each of them in CI.
Maintained by API to Agents, which builds and hosts this kind of server for companies that would rather not. The examples are MIT licensed; use them as a starting point for your own API.
What the examples show
Every integration needs the same three kinds of tool, and every example here has them:
| Tool | Kind | What it demonstrates |
|---|---|---|
search_products | read | Pagination with an opaque nextCursor, summarised results instead of raw records, a description that tells the assistant when the list is incomplete |
get_product | read | Lookup by id, "not found" reported as an error that says not to retry |
create_order | write | Idempotency: the assistant generates a key and reuses it on retry, so a timeout never creates a duplicate order |
cancel_order | guarded | Refuses to act until called with confirm=true, after showing the user what will be cancelled |
Also shown in each: the upstream API key lives in the server's environment and is never visible to the assistant; errors distinguish invalid input, not found, conflict and upstream unavailable, each with a hint about what to do next; tools carry readOnlyHint, destructiveHint and idempotentHint annotations.
Layout
sample-api/ Zero-dependency Node server + openapi.json. Products, orders, idempotent create, cancel.
typescript/ @modelcontextprotocol/server 2.3 + express, Streamable HTTP, stateless
python/ mcp 2.3 (MCPServer), Streamable HTTP, stateless
csharp/ ModelContextProtocol.AspNetCore 2.2, .NET 10, Streamable HTTP, stateless
php/ mcp/sdk 0.8, PHP 8.2+, Streamable HTTP with a file session store
tests/ Conformance scenario (TypeScript client) run against each server in CI
Run it
Start the sample API once; it listens on 127.0.0.1:4010 and expects X-API-Key: demo-key.
node sample-api/server.mjs
Then start any server. Each reads UPSTREAM_URL (default http://127.0.0.1:4010) and UPSTREAM_API_KEY (default demo-key) from the environment.
# TypeScript β http://127.0.0.1:3001/mcp
cd typescript && npm ci && npm run build && npm start
# Python β http://127.0.0.1:3002/mcp
cd python && python -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python server.py
# C# β http://127.0.0.1:3003/mcp
cd csharp && dotnet run
# PHP β http://127.0.0.1:3004/mcp
cd php && composer install && php -S 127.0.0.1:3004 public/index.php
Run the conformance scenario against whichever one is up:
cd tests && npm ci && MCP_URL=http://127.0.0.1:3001/mcp npm test
Connect an assistant
Each server is a remote MCP server over Streamable HTTP at /mcp. For a client on another machine, expose it over HTTPS and point the client at that URL:
- Claude (web, desktop, Claude Code): add it as a custom connector or MCP server by URL.
- ChatGPT: add it through the connector settings available on your plan.
- Any MCP client: use the Streamable HTTP transport with the server URL.
These examples use an API key on the upstream side only and no authentication on the MCP endpoint itself, which is fine on localhost and wrong on the internet. Before exposing one publicly, add bearer-token or OAuth protection at the endpoint; each SDK documents how.
Adapting to your own API
- Replace
sample-api/openapi.jsonwith your API description and theshopclient in your language of choice with calls to your endpoints. - Keep the tool count small and outcome-shaped. The point is not to mirror every endpoint; see choosing which API actions to expose.
- Keep the three kinds distinct: reads with permission checks, writes with idempotency keys, guarded actions with confirmation.
- Keep the conformance test: edit
tests/conformance.mjsto your tools and run it against every change.
Or run the free Agent Readiness Audit: it reads your documentation and proposes the tools, the boundaries and a fixed price for having it built and hosted.
License
MIT. See LICENSE.