booking-mcp-app

A view-only MCP App: an MCP server that exposes court-availability data and renders it as a read-only panel inside an MCP host (Claude Desktop, VS Code, or the free local test host), using the MCP Apps protocol (spec 2026-01-26).

This is the first phase of porting the generative-ui POC to MCP Apps. Read-only, no booking yet: the important shift from generative-ui is that the data lives on the server (the tool), not in the conversation. The UI only displays what the server returns.

What it does

The server registers one tool, get_court_availability, that returns which courts and time slots are free for a given date + sport from in-memory mock data. The tool is linked to a UI resource (ui://court-availability/panel.html) that the host renders in a sandboxed iframe as a read-only grid of courts x time slots (free vs taken).

Two data paths, both handled the same way in the UI:

• The host pushes a tool result to the app (app.ontoolresult) whenever the agent calls get_court_availability, e.g. with a different date or sport. The panel updates.
• The app pulls its own initial data on load (app.callServerTool). This is the app -> server -> app round trip, and it also populates the panel when it is opened directly.

There are no inputs, no submit, no booking. Changing the date or sport happens by calling the tool with different arguments (from the agent or the test host), not from a form.

Layout

booking-mcp-app/
  server.ts         MCP server: registers the tool + the ui:// resource, served over HTTP
  availability.ts   the booking domain (sports, courts, slots) + deterministic mock data
  mcp-app.html      UI entry point
  src/
    mcp-app.ts      the view: App client, ontoolresult + callServerTool, renders the grid
    mcp-app.css     panel styling (single light theme)
  vite.config.ts    bundles the UI into one self-contained HTML (vite-plugin-singlefile)
  dist/mcp-app.html the built UI, read by the server and served as the resource

Reuses the booking domain from generative-ui (Tennis / Football / Basketball / Padel, courts and time slots). Availability is deterministic per query, so the same date + sport always renders the same grid.

Run

Requires Node 18+ (developed on Node 24).

npm install
npm run build      # typecheck + bundle the UI to dist/mcp-app.html
npm run serve      # start the MCP server on http://localhost:3001/mcp

npm start does the build and serve in one step. Rerun npm run build after any UI change; the server reads dist/mcp-app.html fresh on each resource request.

• npm run check typechecks only (tsc --noEmit).
• PORT=4000 npm run serve changes the port.

See the panel in a host

Free: the local test host

The ext-apps repo ships a local host that renders MCP Apps with no account needed.

# 1) in this project, with the server already running (npm run serve)
# 2) in a separate clone of the ext-apps repo:
git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3001/mcp"]' npm start

Open http://localhost:8080, call get_court_availability (try { "sport": "Padel", "date": "2026-08-21" }), and the availability grid renders in the iframe. Call it again with a different sport to see the panel update.

Claude Desktop (paid plan)

Expose the local server with a tunnel and add it as a custom connector:

npx cloudflared tunnel --url http://localhost:3001

In Claude, go to Settings -> Connectors -> Add custom connector, paste the https://<something>.trycloudflare.com/mcp URL, then ask Claude to show court availability.

References

• MCP Apps overview — https://modelcontextprotocol.io/extensions/apps/overview
• Build guide — https://modelcontextprotocol.io/extensions/apps/build
• Spec (2026-01-26) — https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
• Examples — https://github.com/modelcontextprotocol/ext-apps/tree/main/examples