MCP Overview
MZAP includes a built-in Model Context Protocol (MCP) server that enables AI assistants to control audio playback, routing, and system configuration via natural language.
What is MCP?
Section titled “What is MCP?”MCP is an open protocol that allows AI models to interact with external tools and data sources. MZAP implements an MCP server with a Streamable HTTP transport, accessible at the /mcp endpoint.
Capabilities
Section titled “Capabilities”The MCP server exposes 11 tool groups:
| Tool Group | Description |
|---|---|
| Playback | Play, pause, stop, seek, load tracks |
| Volume | Adjust player and zone volumes |
| Routing | Attach/detach players to zones |
| System | Initialize devices, health check |
| Player Management | Create/remove players |
| Playlists | List, create, modify playlists |
| DSP | Adjust EQ and compressor settings |
| Workspaces | Save, load, list workspaces |
| Jingles | Play jingles with ducking |
| Library | Search media library |
| Radio | Load internet radio streams |
Licensing
Section titled “Licensing”MCP access is gated by a license feature flag.
Connection
Section titled “Connection”Connect any MCP-compatible AI client to:
http://localhost:5000/mcpThe server uses Streamable HTTP transport and supports session tracking for concurrent connections.
Settings → MCP server (AI integration) shows the URL to use, whether the feature is licensed, how many clients are connected, and ready-to-copy setup for each supported client. See Settings → MCP server.
Authentication and roles
Section titled “Authentication and roles”With authentication enabled, MCP clients must send a valid API key in an X-API-Key header. The key belongs to a user, and that user's role decides which tools the client can see and call:
| Role | Tools available |
|---|---|
| Viewer | Read-only: get_system_status, get_workspace_info, search_library, list_tts_voices, search_radio_stations |
| Operator | The above, plus playback, volume/mute, jingle playback, playback mode, and EQ/compressor |
| Admin | Everything, including creating players and playlists, routing, TTS jingle creation, and saving/loading workspaces |
Tools outside a client's role are hidden from its tool list rather than failing when called. Non-admin clients also only see the players and zones assigned to their user in the workspace, and cannot act on the ones they cannot see.
A connection with a missing or invalid key is rejected with 401.
With authentication disabled, nothing changes: no key is required and every tool is available, matching how the desktop app and browser UI behave.
To give an AI client limited access, create a dedicated user with the role you want in Users, then use that user's API key in the client's configuration.