MANUAL · 06
Agent access.
SUB/WAVE isn't only for human listeners. An AI agent can read what's on air and put songs and DJ segments onto the broadcast through the station's MCP server.
WHAT IT IS
An MCP server for the station.
subwave-mcp is a small server that speaks the Model Context Protocol — the standard way an AI agent like Claude reaches an external tool. It is the agent-facing twin of the listener request panel: where a human types into the browser, an agent calls a tool, and the same controller does the work.
The server holds no logic of its own — each tool is a typed wrapper over one controller endpoint. The agent never sees a URL or an auth header, only the five intent-shaped tools below.
THE TOOLS
Five things an agent can do.
| Tool | What it does | Auth |
|---|---|---|
subwave_now_playing | The current track, station context, and live listener count. | — |
subwave_station_state | The upcoming queue, recent history, and the DJ booth log. | — |
subwave_request_song | Queues a track from a natural-language request — a song, an artist, or a vibe. | — |
subwave_dj_announce | Puts a spoken update on air, rewritten in persona or read verbatim. | Admin |
subwave_dj_segment | Fires a scripted segment on demand — station ID, the hour, or a link. | Admin |
Like the human request path, subwave_request_song queues a track — it never interrupts the song that's playing — and it's rate-limited. The two DJ-control tools speak immediately.
PUBLIC vs ADMIN
Reading and requesting are open.
The three read-and-request tools need no credentials — they map to the same public, rate-limited endpoints a browser uses. The two DJ-control tools, which put a voice on air, are gated: the server sends the station's ADMIN_USER / ADMIN_PASS as a Basic auth header, read from its own environment. Without them, an agent can still see what's on air and request songs — it just can't drive the DJ.
WIRING IT UP
Point an MCP client at it.
The server lives in the repo at mcp-subwave/. Build it once with npm install && npm run build, then point any MCP client — Claude Code, Claude Desktop, or another — at the built dist/index.js, passing the controller URL and, optionally, the admin credentials as environment variables. The station must be running first.
docs/mcp-server.md in the repo covers every tool's options, the configuration variables, the error messages, and ready-to-paste client snippets. To run the station itself, see Admin & Settings.