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's tools fall into these groups. See the MCP Tools Reference for every tool.
| Tool Group | Description |
|---|---|
| System | Current state of players, zones and routing |
| Playback | Play, pause, stop, skip and seek |
| Volume | Player and zone volume and mute |
| Routing | Connect players to zones and disconnect them |
| Players | Create playlist, app-capture, AirPlay and SoundMachine players |
| Playlists | Create playlists, add and reorder tracks, assign them to players, set the playback mode |
| Sound processing | Zone EQ and compressor, player auto level |
| Jingles | Play jingles with ducking, create text-to-speech jingles |
| Library and radio | Search the media library and internet radio stations |
| SoundMachine | Find and switch stations, mixes and schedules; like or dislike songs |
| Workspaces | Show, save and load workspaces |
Licensing
Section titled “Licensing”MCP access is gated by a license feature flag.
Connecting AI apps
Section titled “Connecting AI apps”Connecting an AI app needs no Node.js and no hand-edited config files. Open Settings → MCP server (AI integration) in MZAP:
- Click Connect AI apps. MZAP creates an AI Assistant user. It is an Admin by default; to limit what AI apps can do, change its role or its assigned players and zones in Users. The AI Assistant cannot sign in to MZAP. It only owns the API key that AI apps use.
- Click Install in Claude Desktop. This installs the MZAP extension, and Claude Desktop starts MZAP's connector by itself. MZAP must be running for the tools to work. If MZAP starts after Claude Desktop, the tools appear once MZAP is up.
Other AI apps (advanced) has ready-to-copy setup for Claude Code, Gemini CLI, VS Code and Cursor, with the key already filled in. Add to VS Code and Add to Cursor set them up in one click. The VS Code and Cursor snippets are complete config files: .vscode/mcp.json for VS Code, mcp.json for Cursor.
Setting up Claude Desktop manually
Section titled “Setting up Claude Desktop manually”In the MZAP desktop app, Set up manually shows a claude_desktop_config.json entry to use instead of the extension. It points Claude Desktop at mzap-mcp.exe in the MZAP install folder. The config holds no key; the connector reads it from MZAP. Restart Claude Desktop after editing the file.
Things to know
Section titled “Things to know”- After turning authentication on or off in MZAP, reconnect Claude Code, Gemini CLI, VS Code and Cursor. Claude Desktop reconnects by itself.
- The AI Assistant key works only for AI apps. It is not accepted by the REST API or the live event streams.
- To turn on authentication, MZAP needs an Admin user other than the AI Assistant.
- ChatGPT, claude.ai on the web or phone, and Claude's "Add custom connector" are not supported: they connect from the internet and cannot reach MZAP on your PC.
When Claude cannot use MZAP
Section titled “When Claude cannot use MZAP”Claude shows one of these messages instead of a result:
| Message | What to do |
|---|---|
| MZAP is not running on this computer. | Start MZAP and try again. |
| MZAP is not connected to Claude yet. | In MZAP, open Settings → MCP server and click Install in Claude Desktop. |
| MZAP rejected the AI Assistant key. | The account may be disabled. Check Users, or open Settings → MCP server and click Connect again. |
| The MCP server is not included in this MZAP license. | MCP needs a license that includes it. |
If Claude Desktop was started before MZAP and the MZAP tools still don't appear once MZAP is running, restart Claude Desktop.
Other MCP clients
Section titled “Other MCP clients”Any MCP-compatible client can connect to:
http://localhost:5000/mcpThe server uses Streamable HTTP transport and supports session tracking for concurrent connections.
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, EQ/compressor, auto level, SoundMachine source changes and like/dislike, and routing players to zones (manage_routing) |
| Admin | Everything, including creating players and playlists, 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 AI apps limited access, change the AI Assistant user's role or its assigned players and zones in Users. For a client set up by hand, you can also create a dedicated user with the role you want and use that user's API key in the client's configuration.