FastMCP Server Integration in Music Assistant: Architecture and Implementation

Music Assistant ships a built-in FastMCP server that implements the Music Control Protocol (MCP) using the fastmcp library, exposing player controls, library management, and queue operations through HTTP/ASGI endpoints.

The music-assistant/server repository includes a native FastMCP server integration that transforms Music Assistant into an MCP-compatible control plane. This integration allows external clients and automation systems to manipulate playback, manage media libraries, and configure players through a standardized protocol. The server implementation resides in the music_assistant.providers.fastmcp_server package and loads automatically as a provider plugin when Music Assistant starts.

Architecture of the FastMCP Integration

The integration follows a layered provider architecture that bridges the FastMCP protocol with Music Assistant's core services.

Provider Entry Point

The MCPServerProvider class in music_assistant/providers/fastmcp_server/provider.py subclasses PluginProvider to integrate with Music Assistant's plugin system. It implements lifecycle methods including handle_async_init, loaded_in_mass, unload, and update_config to manage the server's initialization and shutdown sequences.

Runtime and Server Initialization

The MCPServerRuntime class, defined in music_assistant/providers/fastmcp_server/server.py, instantiates the root FastMCP object. This runtime mounts sub-servers for distinct functional domains—such as players, media, and library operations—and wires them to the ASGI bridge for external communication.

Tool Registration and Sub-servers

Individual tools exposing MCP-compatible endpoints live under the tools/ directory. These include:

• tools/volume.py for volume controls (e.g., volume.set)
• tools/queue.py for queue management (e.g., queue.add)
• tools/playlists.py for playlist operations (e.g., playlists.create)
• tools/players.py for player state management

The runtime dynamically registers these tools during startup, making them available to MCP clients under the service name declared in manifest.json ("Music Assistant MCP").

HTTP Bridge and Transport

music_assistant/providers/fastmcp_server/http_bridge.py exposes the FastMCP root as an ASGI application. This bridge enables external MCP clients—including Home Assistant—to communicate over HTTP and WebSocket protocols via the /mcp endpoint.

Security and Configuration

Authentication and Authorization

The auth.py and middleware.py files enforce permission checks and translate FastMCP errors into Music Assistant's McpError exceptions. The middleware supports hot-swapping permission changes without requiring a server restart.

Configuration Management

music_assistant/providers/fastmcp_server/config.py handles validation, encryption, and file I/O for provider settings. The config_io/ subdirectory manages secrets such as API keys and allowed origin lists, ensuring sensitive data persists securely across restarts.

Resource Definitions

Static resource schemas defined in music_assistant/providers/fastmcp_server/resources/player_resources.py, library_resources.py, and _uri.py describe MCP resource names, URIs, and capabilities. These definitions enable discovery protocols that allow MCP clients to inspect available functionality at runtime.

Using the FastMCP Server

When Music Assistant boots, the core loads the provider listed in manifest.json. The MCPServerProvider's handle_async_init method creates the FastMCP runtime, mounts the sub-servers, and registers the ASGI app with the core's HTTP router.

Client Connection Examples

You can interact with the embedded server using any FastMCP client:

from fastmcp import Client

# Connect to the local MCP server (default HTTP endpoint is /mcp)

client = Client("http://localhost:8095/mcp")

# Query the current player state

player_state = client.call_tool(
    "players.get_player", {"player_id": "my_player"}
)
print("Player state:", player_state)

# Change the volume

client.call_tool(
    "volume.set",
    {"player_id": "my_player", "volume": 55}
)

# Add a track to the queue

client.call_tool(
    "queue.add",
    {"player_id": "my_player", "media_item_id": "track:12345"}
)

# List all playlists

playlists = client.call_tool("library.get_playlists", {})
print("Playlists:", playlists)

Extending the Server with Custom Tools

Third-party plugins can register additional MCP tools using the register_tool utility from music_assistant.providers.fastmcp_server.tools._common:

# my_custom_plugin/provider.py

from music_assistant import PluginProvider
from music_assistant.providers.fastmcp_server.tools._common import register_tool

class MyCustomProvider(PluginProvider):
    async def handle_async_init(self):
        # Register a new MCP tool under the "debug" namespace

        async def echo(context, payload):
            """Echoes back the given payload."""
            return {"echo": payload}

        await register_tool(
            name="debug.echo",
            func=echo,
            description="Echoes the payload for testing.",
            input_schema={"type": "object", "properties": {"msg": {"type": "string"}}},
        )

This extensibility allows the FastMCP server to grow with custom automation logic while maintaining strict protocol compliance.

Summary

• Provider-based architecture: The FastMCP server implements MCPServerProvider in provider.py to hook into Music Assistant's plugin lifecycle.
• Modular tool system: Functionality is split across sub-servers in tools/, covering volume, queues, playlists, and player controls.
• ASGI transport: http_bridge.py exposes the server over HTTP/WebSocket at the /mcp endpoint.
• Security layers: auth.py and middleware.py enforce permissions and error translation.
• Configuration management: Encrypted settings and hot-reload support are handled by config.py and config_io/.
• Extensible design: Plugins register custom tools via register_tool to expand the MCP interface without core modifications.

Frequently Asked Questions

What protocol does the Music Assistant FastMCP server use?

The server implements the Music Control Protocol (MCP) on top of the open-source fastmcp library. It exposes tools and resources through ASGI-compatible HTTP and WebSocket transports, allowing any MCP-compliant client to discover and invoke functions.

Where is the FastMCP server configuration stored?

Configuration validation and encryption are handled in music_assistant/providers/fastmcp_server/config.py, with file operations managed by the config_io/ submodule. This includes secrets like API keys and allowed origin lists that persist across server restarts.

How do I add custom functionality to the FastMCP server?

Third-party plugins can import register_tool from music_assistant.providers.fastmcp_server.tools._common and invoke it during their handle_async_init method. This registers new tools under custom namespaces (e.g., debug.echo) without modifying the core server code.

What endpoints are available on the FastMCP server?

The server exposes standard MCP tools including players.get_player, volume.set, queue.add, playlists.create, and library.get_playlists. The complete schema is defined in the resources/ directory, particularly player_resources.py and library_resources.py, which describe resource URIs and capabilities for client discovery.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}