MCP — drive your TVs from an AI agent

Numbered on the diagram: 0 the user connects once — either they paste a personal access token, or they click Connect and sign in through OAuth, which issues the token. Then, per request: 1 the AI client sends that token to the MCP server; 2 the server — holding no credential of its own — forwards it to the relay; 3 the relay resolves the token to {you, your live role}, enforces exactly the same access rules and audit as the web app, and forwards the command to your site agent and the TV. The MCP server is a thin, stateless pipe; the relay stays the single authority.

What the agent can do

Read tools

list_sets · get_health · list_recordings · get_stats — plain reads, ACL-filtered to exactly the sets you can see. "Which TVs are online, and what did they record today?"

send_keys

Press a sequence of remote keys, in order — "HOME RIGHT OK". The agent takes control of a free TV automatically; it can't wrest it from someone who's using it.

send_text

Type straight into the TV's focused input — a search box, a login form — instead of arrow-keying an on-screen keyboard. Replaces the field's content; an empty send clears it.

launch_app + list_apps

Ask the TV what's installed (list_apps — titles, ids, versions), then start any of it by id — get the app under test on screen in one step and drive it with send_keys and send_text.

power

Switch the TV's mains via its smart plug — on, off, or cycle (the last-resort remote restart). Waits for the plug's confirmation.

play_scenario

Replay a recording's exact key-track onto a TV — reproduce a saved session on demand, on the same set or a different one.

Two ways to connect — same identity

Whichever you choose, the agent ends up holding a token that maps to your local account with your live role. There is no separate identity and no third-party login — Screenwhere is its own authority.

Personal access token

In Settings → Access tokens, create a token (shown once), name it, and paste it into your MCP client. Long-lived, revoke-only. Simplest to set up.

OAuth 2.1 click-to-connect

Add /mcp as a connector; the client opens our sign-in, you log in with your existing account (password + 2FA) and pick a scope. Short-lived token, auto-refreshed. Nothing to copy-paste.

You choose what it may do

On the OAuth consent screen you grant either read only or read + control. A read-only connection can look — sets, health, recordings, stats — but can't change anything or drive a TV; the relay enforces that server-side, so a read-only token is powerless to control even if a client tried. You can see every connected app, and its scope, in Settings → Connected apps, and disconnect any of them in one click — "sign out everywhere" drops them too.

Why it's safe

No new identity axis. A token resolves to a user with the role read live from the account — it can't out-rank or outlive you, and a role change or disable takes effect at once.
The server holds nothing. The MCP server has no standing credential and no state; it only forwards your token. The relay decides everything.
OAuth done right. PKCE is mandatory, redirect URIs are exact-matched, authorization codes are single-use and short-lived, and the sign-in is the same 2FA-gated, throttled check as the web login.
Least privilege + revocation. Read-only is a real, enforced scope; refresh tokens rotate on every use; and a token can never mint or revoke tokens — only a signed-in web session can.
Everything is audited as the real user — every key press, power switch and replay.

The full design, the token model and the tests are in docs/MCP-PLAN.md and mcp/README.md. See also the architecture and what shipped.