Playback MCP ← Back to home
System Design

One broker, many sessions

Each session runs its own playback-mcp server and drives its own tab. A shared broker multiplexes them onto the one extension, routing by sessionId.

CLIENTS MCP SERVERS BROKER EXTENSION TABS stdio ws · :8765 node:sqlite SQLite library library.db · WAL Agent A Agent B Agent C session session session playback-mcp playback-mcp playback-mcp sessionId A sessionId B sessionId C broker 127.0.0.1:8765 extension service worker tab A tab B tab C one broker owns the port · routed by sessionId · one shared SQLite library on disk stdio shared SQLite library.db ws :8765 Agent A Agent B Agent C session session session playback-mcp playback-mcp playback-mcp sessionId A sessionId B sessionId C broker 127.0.0.1:8765 extension service worker tab A tab B tab C one broker · routed by sessionId · one shared library
shared broker shared SQLite store active <video>

MCP server

playback-mcp · Node ≥ 23.4
  • One process per session, speaking MCP over stdio to your agent.
  • Exposes every tool — play/seek/speed/volume, loops, sequences, library, transcripts.
  • Owns the shared library via node:sqlite (WAL).
  • Fetches captions straight from YouTube, server-side.
  • Auto-spawns the broker on first use.

Broker

playback-mcp-broker · :8765
  • Standalone daemon that owns 127.0.0.1:8765 — exactly one runs.
  • Multiplexes every server onto the single extension, routing by sessionId.
  • Enforces an Origin allow-list at the WebSocket handshake.
  • Idle-exits ~60s after the last session disconnects.

Extension

Chrome · worker + content script
  • Keeps one managed tab per session.
  • Drives only the page's <video> — time, rate, volume, play/pause.
  • Never clicks UI, scrapes, or navigates beyond opening a watch URL.
  • Supplies the current videoId so the server can fetch captions.