MCP reference server for real-world tasks

A minimal, dependency-free MCP server written against protocol revision 2026-07-28 — the one that removed sessions and the initialize handshake. It models a service that sends a person to check something in the physical world and returns structured evidence.

The domain is a toy. The shape is not: it is extracted from a production server that answers agents today, with the business logic replaced by a readable example so the protocol layer is the thing you actually read.

npm start   # http://localhost:8787
npm test    # 20 tests, no dependencies

curl -s -X POST http://localhost:8787/ \
  -H 'content-type: application/json' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'

What changed in 2026-07-28, and why it makes this simpler

If you last read the MCP spec before this revision, most of what you remember about transports is gone:

The practical consequence is the whole point of this repo: a stateless request handler is now the shape the spec expects. There is no session to store, nothing to expire, and no reason to reach for a durable object, a Redis, or a stateful process. src/protocol.js is a pure function from Request to Response.

Two things were added that are easy to miss and that clients silently rely on:

• Every result carries resultType: "complete".

• List results (tools/list, server/discover) carry ttlMs and cacheScope.

• server/discover is mandatory — clients may call it before anything else.

Related MCP server: hello-mcp

Layout

src/server.js exports fetchHandler(request) — a plain Request → Response function, so it drops unchanged into Cloudflare Workers, Deno Deploy, Bun, or a Next.js route handler. The Node listener exists so npm start works without a platform account.

The five decisions worth stealing

Everything below is a choice that cost real debugging somewhere else.

1. The header/body mirror is a real requirement, not decoration. Mcp-Method and Mcp-Name duplicate values from the body so intermediaries can route without parsing. If they disagree, reject with -32020. Skipping this creates a split-brain where a proxy routes on the header while your handler executes the body — which is exactly the bug the rule exists to prevent.

2. Unknown method is 404, not 200 with an error body. The spec uses the HTTP status so a client can tell "this endpoint does not implement that method" from "this URL is not an MCP endpoint at all". Return 200 and you break client fallback logic.

3. Read-only tools need no authentication. Quoting creates nothing, reserves nothing, costs nothing. There is nothing to gate. Gating it only teaches agents that exploring your service is expensive. Authenticate the tools that commit something.

4. Exactly one tool has a side effect, and its annotations say so. readOnlyHint, destructiveHint, idempotentHint and openWorldHint are what clients and directory reviewers branch on. An unannotated write tool will be treated as dangerous or rejected.

5. One pricing function serves every surface. In the production system this is extracted from, the same quote() answers the web form, the REST endpoint and the MCP tool. A human and an agent therefore cannot be shown different prices for identical work. If you take one idea from this repository, take this one — it is a correctness property, not an optimisation.

The safety shape

The example write tool (submit_request) is deliberately not a booking:

• It requires consent: true, set only after a human has agreed.

• It returns status: "pending_human_review" and dispatch: "never_automatic".

• Nothing in the response can be mistaken for a confirmation.

An agent should never be able to send a person into the physical world without someone reading the request first. In the system this comes from, that is a fixed product guardrail rather than a limitation to be lifted later — and the tool description says so, because the description is what the model reads when it decides whether to call it.

Compatibility with older clients

src/protocol.js answers initialize, notifications/initialized and ping for the 2025-* revisions, because deployed clients lag published specs by months. It is a shim, not a second protocol: both paths serve the same tools from the same definitions. Header mirroring is enforced only on the modern revisions, since requiring it on legacy clients would reject exactly the clients the shim exists for.

Delete LEGACY_PROTOCOL_VERSIONS once nothing in the wild still opens with a handshake.

Connecting it

Once deployed at a public HTTPS URL, add it as a custom connector in Claude (Settings → Connectors) or in ChatGPT (Settings → Apps → Advanced → Developer mode). Both accept a no-auth Streamable HTTP endpoint.

License

MIT. Built as a by-product of VorOrtAI, which runs the non-toy version of this.