Usher MCP — Movie Detail App

Interactive MCP server and UI widget that renders movie details from TMDB with the MCP Apps spec. The server runs on Cloudflare Workers; the UI is a sandboxed HTML resource served via ASSETS and rendered by MCP hosts.

What’s here

• MCP server (server/) exposing:

  • ui://widget/movie-detail-widget.html resource (HTML + CSS + JS from ASSETS)

  • Tool get-movie-detail that searches TMDB by title and returns details + cast

• Widget UI (web/) built with React/Tailwind:

  • Entry: widget.html → movie-detail-widget.js/.css

  • MCP Apps lifecycle: ui/initialize, tool input/result notifications, ui/open-link for showtimes

  • Showtimes link opens Google “ showtimes near me” via ui/open-link

• Root landing page: friendly message at / telling visitors to connect via /mcp

Prerequisites

• Node 18+

• Wrangler CLI

• TMDB API token (v4 bearer) stored as a secret

Install

npm install

Local dev (Workers)

Use .dev.vars for local secrets:

TMDB_TOKEN=your_tmdb_bearer_token

Run dev server:

npm run dev

MCP endpoint will be at http://localhost:8787/mcp.

Build the widget

npm run web:build

Outputs to web/dist/:

• movie-detail-widget.js

• movie-detail-widget.css

• widget.html

These are served by the ASSETS binding for the MCP UI resource.

Deploy to Cloudflare Workers

1. Set the secret in your account:

wrangler secret put TMDB_TOKEN

2. Deploy:

npm run deploy

MCP server code pointers

• server/lib/mcp.ts — registers resource + tool, uses ASSETS to serve built widget, pulls tmdbToken from env binding.

• server/index.ts — Hono entry, mounts /mcp and root landing page.

• web/src/movie-detail-widget.tsx — MCP Apps UI logic + render.

• web/vite.config.ts — builds widget assets with custom filenames for ASSETS.

MCP tool contract

• Tool: get-movie-detail

• Input: { "query": "<movie title>" }

• Returns:

  • content: text fallback

  • structuredContent.movie: movie payload (title, poster/backdrop URLs, runtime, genres, rating, cast, etc.)

Notes for hosts

• UI resource URI: ui://widget/movie-detail-widget.html

• MIME: text/html;profile=mcp-app

• CSP: allows https://image.tmdb.org/ for posters/backdrops

• Expects MCP Apps messages:

  • ui/notifications/tool-input / tool-input-partial

  • ui/notifications/tool-result

  • ui/open-link (to open showtimes link)

Type generation

Regenerate Cloudflare binding types if config changes:

npm run cf-typegen

Troubleshooting

• Missing TMDB token: set TMDB_TOKEN in .dev.vars (local) and via wrangler secret put (prod).

• Assets not loading: ensure npm run web:build was run and ASSETS binding is present.

• Host rejects ui/open-link: host must support MCP Apps ui/open-link; otherwise widget will show an error state.