MANUAL · 14
Agent access.
SUB/WAVE isn't only for human listeners. An AI agent can read what's on air and put songs, DJ segments, and sound effects 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 almost 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 intent-shaped tools below.
THE TOOLS
Seventeen things an agent can do.
| Tool | What it does | Auth |
|---|---|---|
subwave_health | Liveness: the controller is reachable and the stream reports on-air. | — |
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_schedule | Personas, shows, and the weekly schedule grid, in station time. | — |
subwave_session | The DJ's live session and its recent on-air transcript. | — |
subwave_request_song | Queues a track from a natural-language request — a song, an artist, or a vibe — and waits for the booth’s verdict. | — |
subwave_request_status | Checks on an earlier request by its receipt id. | — |
subwave_search_library | Searches the library by terms: exact results, no LLM, no rate limit. | Admin |
subwave_queue_track | Queues an exact search result — an operator pick, no DJ intro. | Admin |
subwave_skip_track | Force-ends the current track. An operator override; listeners have no skip. | Admin |
subwave_dj_announce | Puts a spoken update on air, rewritten in persona or read verbatim — optionally over a sound-effect stinger. | Admin |
subwave_dj_segment | Fires a scripted segment on demand: station ID, the hour, a link, guest banter, or a programme beat. | Admin |
subwave_list_skills | The skill catalogue — weather, news, and any custom skills installed. | Admin |
subwave_run_skill | Runs a named skill segment now, with real data behind it. | Admin |
subwave_list_sfx | The sound-effects library: short stingers the station can play. | Admin |
subwave_play_sfx | Fires a sound effect on air immediately, mixed over the programme. | Admin |
subwave_refresh_playlist | Rebuilds the fallback auto-playlist for the current mood. | 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 booth resolves the request in the background, so the tool waits for the outcome and reports the matched track and the DJ's ack. When an agent already knows the exact track, the search-and-queue pair does the same job with no LLM and no rate limit. The DJ-control tools speak immediately.
AN ALERT, WITH AN AIRHORN
Attention first, then the message.
The announce tool takes an optional sound effect from the station's library, aired under its opening words. That turns an external watcher into a proper alert system: an agent monitoring weather warnings for your area can call subwave_dj_announce with the warning text, mode: raw so nothing gets paraphrased, and sfx: airhorn to cut through the music before the words land. Effects can also fire on their own with subwave_play_sfx.
PUBLIC vs ADMIN
Reading and requesting are open.
The seven read-and-request tools need no credentials: they map to the same public endpoints a browser uses. Everything that drives the station — voice, segments, skills, effects, the queue, the skip — is 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, 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. Inside the repo itself, Claude Code picks the server up automatically from the root .mcp.json. 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.