# How to Configure and Use the FastMCP Server for Programmatic Access in Music Assistant

> Learn to configure and use the FastMCP server in Music Assistant for programmatic access. Control playback and query player states with the fastmcp client or HTTP requests.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-14

---

**The FastMCP server is a built-in provider plugin that exposes Music Assistant's core functionality via a JSON-RPC-style ASGI endpoint, enabling external scripts to control playback and query player states using the `fastmcp` client library or direct HTTP requests.**

The FastMCP server eliminates the need for browser-based interaction by providing programmatic access to the `music-assistant/server` repository's media control API. When enabled, this provider creates a lightweight, high-performance endpoint that registers tools such as `find_and_play` and `get_player_state`, allowing automation frameworks and custom scripts to manage your audio ecosystem remotely.

## What Is the FastMCP Server?

The FastMCP server is implemented as a **provider plugin** (`fastmcp_server`) within the Music Assistant architecture. When activated, it instantiates the `MCPServerRuntime` class, which constructs an ASGI application (`http_app`) that listens on a configurable TCP port. This runtime registers a suite of tools that mirror the public Python API, exposing methods to control players, adjust volume, and search the media library.

Unlike the standard web interface, this endpoint is designed specifically for machine-to-machine communication, utilizing a lightweight protocol that supports both authenticated and open-access modes depending on your security requirements.

## Configuration Options

The server is configured through the `mcp` section in your [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml) or via the Home Assistant UI configuration panel. All parameters are defined in the provider initialization and runtime setup.

```yaml
mcp:
  enabled: true          # Toggle the server on/off

  host: "0.0.0.0"        # Interface to bind (default: 0.0.0.0)

  port: 8096             # TCP port for incoming connections

  token: "your-secret-jwt-token"  # Optional: enables JWT authentication

```

When a `token` is specified, the server validates the `Authorization: Bearer <token>` header on every request using the logic in [`music_assistant/helpers/jwt_auth.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/jwt_auth.py). If omitted, the endpoint runs without authentication, suitable only for trusted network environments.

## Core Architecture and Source Files

The implementation spans four critical files in the repository:

- **[`music_assistant/providers/fastmcp_server/provider.py`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/fastmcp_server/provider.py)**: Contains the `MCPServerProvider` class that integrates the runtime into the Music Assistant core, handling lifecycle events like `start()` and `setup_runtime()`.
- **[`music_assistant/providers/fastmcp_server/server.py`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/fastmcp_server/server.py)**: Implements `MCPServerRuntime`, creates the ASGI application, and registers available tools that wrap the core API methods.
- **[`music_assistant/providers/fastmcp_server/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/fastmcp_server/manifest.json)**: Declares the MCP resource type (`resource_name: "Music Assistant MCP"`) for the plugin registry, allowing the core loader to discover and initialize the provider.
- **[`music_assistant/helpers/jwt_auth.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/jwt_auth.py)**: Provides JWT token validation when authentication is enabled, ensuring secure programmatic access.

## Enabling the FastMCP Server

To activate the server, modify your Music Assistant configuration to enable the MCP provider and specify your preferred network settings:

```yaml

# config.yaml

mcp:
  enabled: true
  host: "0.0.0.0"
  port: 8096
  token: "super-secret-jwt-token-123"

```

Upon restart, the `MCPServerProvider` initializes the runtime, mounts the ASGI app, and begins listening for incoming FastMCP protocol connections on the specified port.

## Connecting Programmatically

Once running, you can interact with the server using either the official `fastmcp` client library or direct HTTP requests.

### Using the FastMCP Client Library

The Python `fastmcp` library provides the most straightforward integration, handling serialization and connection management automatically:

```python
from fastmcp import FastMCP, Client

# Initialize the client connection

mcp = FastMCP(
    name="music_assistant",
    host="127.0.0.1",
    port=8096,
    token="super-secret-jwt-token-123"
)

client = Client(mcp)

# Search and play a track

await client.call_tool(
    "find_and_play",
    {
        "search_query": "Imagine Dragons",
        "player_id": "living_room_sonos"
    }
)

# Query current player state

state = await client.call_tool(
    "get_player_state",
    {"player_id": "living_room_sonos"}
)
print(state)

```

### Direct HTTP API Calls

For languages or environments without the `fastmcp` library, you can invoke tools directly via HTTP POST requests to the `/call_tool` endpoint:

```bash
curl -X POST "http://127.0.0.1:8096/call_tool" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer super-secret-jwt-token-123" \
     -d '{
           "tool": "set_player_volume",
           "params": {
             "player_id": "living_room_sonos",
             "volume_level": 75
           }
         }'

```

## Starting the Server Programmatically

For advanced use cases, such as testing or custom plugin development, you can instantiate and start the server manually from within Python:

```python
from music_assistant.providers.fastmcp_server.provider import MCPServerProvider

# Assuming 'core' is your Music Assistant core instance

mcp_provider = MCPServerProvider.__new__(MCPServerProvider)
mcp_provider.core = core
mcp_provider._setup_runtime()  # Creates the MCPServerRuntime instance

await mcp_provider.start()     # Starts the ASGI server and begins accepting connections

```

## Summary

- The **FastMCP server** is a provider plugin in `music-assistant/server` that creates an ASGI endpoint for remote control.
- Configuration occurs via the `mcp` section in [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml), supporting custom ports, hosts, and optional **JWT authentication**.
- Core implementation files include [`provider.py`](https://github.com/music-assistant/server/blob/main/provider.py) (lifecycle management), [`server.py`](https://github.com/music-assistant/server/blob/main/server.py) (ASGI runtime), and [`jwt_auth.py`](https://github.com/music-assistant/server/blob/main/jwt_auth.py) (security).
- Access the server using the **`fastmcp` client library** or direct HTTP POST calls to `/call_tool`.
- Available tools mirror the public API, including `find_and_play`, `get_player`, and `set_player_volume`.

## Frequently Asked Questions

### What is the default port for the FastMCP server?

The FastMCP server defaults to **port 8096** when enabled. You can override this by setting the `port` value in the `mcp` configuration section of your [`config.yaml`](https://github.com/music-assistant/server/blob/main/config.yaml).

### Is authentication required to use the FastMCP server?

Authentication is **optional**. If you omit the `token` parameter in the configuration, the server runs in open-access mode. When a token is provided, every request must include an `Authorization: Bearer <token>` header, validated against the logic in [`music_assistant/helpers/jwt_auth.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/jwt_auth.py).

### What tools are available through the FastMCP server?

The server exposes tools that mirror the Music Assistant public API, including **`find_and_play`** for media search and playback, **`get_player`** and **`get_player_state`** for querying device status, and **`set_player_volume`** for audio control. The full list is registered dynamically in `MCPServerRuntime` within [`music_assistant/providers/fastmcp_server/server.py`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/fastmcp_server/server.py).

### Can I run the FastMCP server without the Music Assistant web interface?

Yes. The FastMCP server operates **independently** as a background provider within the Music Assistant core. It does not require the web interface to be running, making it suitable for headless installations where you only need programmatic access via the ASGI endpoint.