MCPKit Examples ¶

Runnable examples covering authentication, async tasks, MCP Apps, and proto-based code generation. Each example is self-contained with its own go.mod.

Most examples ship a guided walkthrough. Each walkthrough is a scripted MCP host that drives the server through every wire-format detail of the feature. Two terminals: just serve (real MCP server, also works with VS Code/MCPJam/Claude Desktop) + just demo (the walkthrough). External MCP hosts are only needed when there is no just demo.

Adding or auditing an example? See CONVENTIONS.md for the canonical structure (layout, server setup, walkthrough, Makefile). The /example-new, /example-audit, and /example-upgrade skills under .claude/commands/ apply and enforce these conventions.

Walkthrough-driven examples ¶

The primary path. Run the demo from the CLI and read the on-disk WALKTHROUGH.md for the sequence diagram and step-by-step explanation.

Example	Walkthrough covers
auth/	Public discovery, JWT/JWKS validation, scope step-up (HTTP 403 + WWW-Authenticate per SEP-2643), session hijacking prevention
tasks/	Async tool lifecycle (SEP-1036): sync calls, optional async, polling, progress notifications, required-task tools, cancellation
tasks-v2/	Server-directed async (SEP-2557): no client task hint, resultType discriminator, inlined results, tool-vs-protocol error semantics
mrtr/	SEP-2322 ephemeral MRTR — InputRequiredResult round-trips for elicitation/create, sampling/createMessage, roots/list; multi-round accumulation via signed requestState; client.CallToolWithInputs auto-loop
list-ttl/	SEP-2549 list TTL — server emits "ttl": <seconds> cache-freshness hint on every list endpoint; three-state pointer encoding (nil / &0 / &N); client.ListXPage typed helpers
file-inputs/ ⚠ experimental	SEP-2356 file inputs — x-mcp-file schema marker on tool input properties, RFC 2397 base64 data URI encoding (core.EncodeDataURI / core.DecodeDataURI), single-file + array-of-files + unconstrained tools; embedded testdata/ fixtures (PNG / PDFs / text) so just demo is hermetic
skills-core/ ⚠ experimental	SEP-2640 minimal shape (scoped-down core blessed 2026-06-30): a skills file served as skill:// resources + skill://index.json discovery + tool handling (a skill points the host at a tool), consumed load-on-demand. Archives / remote sources / fsnotify are the extended surface in skills/
elicitation/ ⚠ experimental	URL-mode elicitation with consent approval (FineGrainedAuth UC1 — tracks draft SEP-2643)
fine-grained-auth/ ⚠ experimental	Authorization denial with scope step-up (UC2) + RAR per-payment ephemeral credentials (UC3) — tracks draft SEP-2643
host/01-apphost/	AppHost mediator — host-side app management, bidirectional tool calls
host/02-multi-server/	ServerRegistry with 3 servers, name-collision resolution
events/discord/ ⚠ experimental	MCP Events extension — events/list, push (SSE), poll (cursor), cursorless typing source (cursor:null), webhook with TTL auto-refresh via the typed Go SDK at experimental/ext/events/clients/go/
events/telegram/ ⚠ experimental	Same protocol as discord, lighter walkthrough — focuses on the telegram-specific payload shape and the typed Receiver[TelegramEventData]

cd examples/<name>
just serve   # terminal 1 — real MCP server
just demo    # terminal 2 — scripted walkthrough

Examples that need an MCP host ¶

These don’t have a CLI demo — point an MCP host at the running server.

Example	What it shows	Host needed
apps/	MCP Apps — server-defined HTML/JS UIs in an iframe (vanilla, todolist, react, interactive, dashboard)	MCPJam (browser-based, supports the Apps extension)
protogen/bookservice/	Proto annotations to MCP tools, resources, prompts	Any MCP host (Claude Code, VS Code, MCPJam, Claude Desktop)

cd examples/apps/todolist
go run . -addr :8080
# then connect MCPJam / your host to http://localhost:8080/mcp

Prerequisites ¶

• Go 1.26+
• Node.js + pnpm — only needed for the React MCP App and the tasks TS reference server
• buf CLI — only needed if regenerating protogen output from .proto

Connecting an external MCP host ¶

If you’re using just serve and want to point an external host at it (instead of just demo):

Claude Code ¶

claude mcp add my-server --transport streamable-http http://localhost:8080/mcp

Claude Desktop / VS Code ¶

Add to your MCP settings JSON:

{
  "mcpServers": {
    "my-server": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

MCPJam ¶

1. Server URL: http://localhost:8080/mcp
2. Transport: Streamable HTTP
3. For auth examples, paste the printed token into the Authorization header
4. Required for apps/ — MCPJam is currently the only host with iframe support for MCP Apps

Troubleshooting ¶

• Port already in use — another example is still running. Kill it or use a different -addr.
• go run fails with replace directive errors — make sure you’re running from the example’s own directory (where its go.mod lives), not from the repo root.
• MCP App shows nothing in the host — your host needs Apps support. Try MCPJam.