MCP Ticket Demo — A Full-Stack MCP Reference Server

A production-shaped MCP server you can run in under five minutes. Ships with 19 tools, 3 resources, 5 prompts, three auth modes, API key management, per-tool gates, rate limiting, a live observability dashboard, and a VS Code / Bob / Cursor / Windsurf control-plane extension.

Use it to learn MCP, test IDE integrations, run live demos, or as a reference implementation when building your own server.

Companion to MCP as a Platform: What I Learned Building a Portfolio of MCP Servers · MCP Dev Summit Toronto · 5 October 2026 · Talk slides →

Personal open-source project.

What makes this useful beyond a hello-world

Most MCP examples stop at "here is a tool that returns a string." This one goes further:

Quickstart — five minutes

# Run directly from npm — no clone needed
npx mcp-ticket-demo           # stdio (IDE spawns this)
MCP_MODE=http npx mcp-ticket-demo  # HTTP — opens /health /test /admin /mcp

# Or clone and run
git clone https://github.com/markusvankempen/mcp-ticket-demo
cd mcp-ticket-demo/server && npm install && npm run http

Then open in a browser:

From a terminal

The same mcp-ticket-demo command is also a client for a running server, local or deployed. With no arguments it is still the MCP server, so the IDE configs below keep working.

npx mcp-ticket-demo status                                    # http://127.0.0.1:8787/mcp by default
npx mcp-ticket-demo call run_query schema=tickets 'filter={"status":"open"}' limit=5   # any tool, values typed from its schema
npx mcp-ticket-demo demo apply --user demo --password demo    # users, keys, auth write, 30 calls / 60 s
npx mcp-ticket-demo demo check --user demo --password demo    # acts as each role and as nobody
npx mcp-ticket-demo status --url https://my-host.example.com  # a deployed server

--json prints one document for scripts, and exit codes are 0 done · 1 refused · 2 usage · 3 unreachable. Commands that delete or reconfigure ask first. Every command, option and example is in server/README.md, and a copy-paste page is at /clients/cli.html on a running desk. demo apply changes real settings, so use it on a server you own.

Laptop login: demo / demo. On a public bind (HOST=0.0.0.0, container, Code Engine) set ADMIN_PASSWORD — the default is disabled. Write smoke is /test?write=1 after admin sign-in.

Add to your IDE (one line)

VS Code / GitHub Copilot — .vscode/mcp.json:

{
  "servers": {
    "mcp-ticket-demo": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-ticket-demo"],
      "env": { "MCP_MODE": "stdio" }
    }
  }
}

Bob / Cursor / Windsurf — .bob/mcp.json / .cursor/mcp.json / .windsurf/mcp.json:

{
  "mcpServers": {
    "mcp-ticket-demo": {
      "command": "npx",
      "args": ["mcp-ticket-demo"],
      "env": { "MCP_MODE": "stdio" }
    }
  }
}

Or install the extension and click Register server with all IDEs — it writes all four configs at once: VS Code Marketplace · Open VSX

Tools

The server has 19 tools. Six are the ticket desk, below. Eight operate the server itself: update_settings (every setting is one patch: auth mode, rate limit, call trace, desk sign-in, transports, events, gates, locks and scopes), set_mqtt, users, API keys, import_settings and sample traffic. Most of those need the admin scope even while auth is off; server/README.md lists the scope of each. Three are timers, start_timer, stop_timer and push_timer, with no get_timer (push_timer also streams the timer as events; see Events): you read a timer through the schema, run_query with schema=timers (server/README.md). push_log sends a log line as an event, and watch_system publishes the machine as system.info, including a container's cgroup limit. Plain lists are not tools of their own: run_query reads settings (the saved settings, importable as they are), system (the machine), events (the events already sent), and, with an admin credential, users, api_keys, trace, errors and counters. The page at /clients/dashboard.html draws them. Each of these tools is declared once and everything else is generated from that definition.

The ticket desk (6)

3 Resources

Resources are addressable and pinnable — clients can subscribe and refresh. Tools are for agent loops.

Call resources/list to browse — you do not need to know a URI ahead of time. A denied read is a JSON-RPC error (not a fake ticket document you can pin).

5 Prompts

User-facing prompts — the user picks these, the model executes them.

Auth model

off    All tools open. No credential needed. Default for local dev.
write  Read tools open. Write tools need a credential. The customer phone shows only with a `pii` credential.
all    Every tool call requires a credential.

Credentials: Authorization: Bearer <api key> over HTTP · MCP_API_KEY env var over stdio.

Issue keys, set modes, toggle per-tool gates, and lock individual tools on /admin. A change broadcasts notifications/tools/list_changed to connected SSE and Streamable HTTP sessions (Cursor/Bob after initialize). One-shot POST /mcp (curl) has no session — it sees the new list on the next call.

Repo layout

mcp-ticket-demo/
  server/       MCP server — tools, resources, prompts, auth, HTTP pages
    src/cli/    The command line client (mcp-ticket-demo <command>)
    clients/    Copy-paste setup pages served at /clients/ (editors, browser, CLI, settings)
  extension/    VS Code / Bob / Cursor / Windsurf control-plane extension (packs a copy of server/)
  docs/         Walkthroughs, lessons learned, publishing guide
  Dockerfile    node:20-bookworm-slim, non-root USER node, WORKDIR /app

Docs

Environment variables

Honest limits

• Tickets live in memory — a new container starts from seed data.
• Admin auth is a session cookie, not SSO. Cookie is HttpOnly (+ Secure on HTTPS).
• /health being green does not mean the ticket went to the right person.
• Public /test does not create or close tickets. Use /test?write=1 after admin sign-in.
• Remote config, the extension's Remote config tab and the command line change real settings (auth mode, users, keys, rate limit) on whatever server you point them at. Demo setup is for a server you own.

Author: Markus van Kempen · markus.van.kempen@gmail.com · markusvankempen.github.io · MCP Dev Summit Toronto talk · Talk slides · npm · VS Code Marketplace · Open VSX