# FastMCP Server Integration in Music Assistant: Architecture and Implementation

> Explore the FastMCP server integration in Music Assistant. Learn about its architecture and implementation for player controls, library management, and queue operations via HTTP/ASGI.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: architecture
- Published: 2026-06-16

---

**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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/tools/volume.py) for volume controls (e.g., `volume.set`)
- [`tools/queue.py`](https://github.com/music-assistant/server/blob/main/tools/queue.py) for queue management (e.g., `queue.add`)
- [`tools/playlists.py`](https://github.com/music-assistant/server/blob/main/tools/playlists.py) for playlist operations (e.g., `playlists.create`)
- [`tools/players.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/manifest.json) ("Music Assistant MCP").

### HTTP Bridge and Transport

[`music_assistant/providers/fastmcp_server/http_bridge.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/auth.py) and [`middleware.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/fastmcp_server/resources/player_resources.py), [`library_resources.py`](https://github.com/music-assistant/server/blob/main/library_resources.py), and [`_uri.py`](https://github.com/music-assistant/server/blob/main/_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`](https://github.com/music-assistant/server/blob/main/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:

```python
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`:

```python

# 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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/http_bridge.py) exposes the server over HTTP/WebSocket at the `/mcp` endpoint.
- **Security layers**: [`auth.py`](https://github.com/music-assistant/server/blob/main/auth.py) and [`middleware.py`](https://github.com/music-assistant/server/blob/main/middleware.py) enforce permissions and error translation.
- **Configuration management**: Encrypted settings and hot-reload support are handled by [`config.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/player_resources.py) and [`library_resources.py`](https://github.com/music-assistant/server/blob/main/library_resources.py), which describe resource URIs and capabilities for client discovery.