MCP Server

System Bridge includes a Model Context Protocol (MCP) server, letting agents and other MCP clients query your system and trigger actions.

The primary endpoint uses Streamable HTTP:

http://{host}:9170/api/mcp

Replace {host} with the hostname or IP address of the machine running System Bridge. The port can be changed with the SYSTEM_BRIDGE_PORT environment variable. Use https:// when System Bridge is exposed through SSL configuration or TLS termination.

All connections require your API token. Pass it as a token query parameter:

http://{host}:9170/api/mcp?token=YOUR_TOKEN

Clients that support custom headers can instead send:

Authorization: Bearer YOUR_TOKEN

A missing or invalid token is rejected with 401 Unauthorized. See how to find your token.

Caution

The token provides access to MCP tools that can read system data, send notifications, and control media. Treat token-bearing URLs as secrets, and use HTTPS when the connection crosses an untrusted network.

Home Assistant

Home Assistant’s Model Context Protocol integration can connect directly to System Bridge. No command or WebSocket bridge is required.

1. In Home Assistant, go to Settings > Devices & services.
2. Select Add integration, then search for Model Context Protocol.
3. Enter the token-bearing Streamable HTTP URL, for example http://192.168.1.10:9170/api/mcp?token=YOUR_TOKEN.
4. Complete the setup flow.
5. Configure your conversation agent to use the System Bridge MCP tools.

Use a hostname or IP address that Home Assistant can reach. Use https:// if the endpoint is exposed over HTTPS.

Other MCP clients

For a remote MCP client, choose its Streamable HTTP transport and use the token-bearing endpoint:

http://{host}:9170/api/mcp?token=YOUR_TOKEN

Client configuration formats and option names vary. Some clients accept a remote MCP URL directly, while others require a transport type, URL field, or custom Authorization header. Follow the client’s documentation rather than assuming a particular configuration key.

Legacy WebSocket transport

The SDK-backed WebSocket transport remains available at the same path for compatibility:

ws://{host}:9170/api/mcp?token=YOUR_TOKEN

Use wss:// when connecting through TLS. Streamable HTTP is the primary setup for clients that support remote MCP servers.

For a stdio-only client, websocat can bridge the client’s standard input and output to the legacy WebSocket:

websocat "ws://localhost:9170/api/mcp?token=YOUR_TOKEN"

Configure the client to launch websocat with the WebSocket URL as its argument. The exact command and argument fields depend on the client.

Tools

system_bridge_get_data

Get current system information from one or more data modules. The tool returns each requested module’s latest data as JSON.

• modules (required): An array of module names to fetch.

Available modules:

Module	Description
battery	Charge level, charging state, and time remaining.
cpu	Usage, frequency, core counts, and per-core load.
disks	Mounted devices, partitions, and used/free space.
displays	Connected displays, resolution, and refresh rate.
gpus	GPU model, load, memory, and temperature.
media	Currently playing media: title, artist, and playback state.
memory	Physical and virtual memory usage.
networks	Network interfaces, addresses, and throughput.
processes	Running processes with CPU and memory usage.
sensors	Hardware sensors such as temperatures and fan speeds.
system	Hostname, OS, uptime, users, and version details.

Example arguments:

{ "modules": ["cpu", "memory", "battery"] }

system_bridge_send_notification

Send a desktop notification to the machine running System Bridge.

• title (required): The notification title.
• message (required): The notification body text.
• icon (optional): An icon name to display with the notification.

Example arguments:

{ "title": "Build finished", "message": "All tests passed", "icon": "dialog-information" }

system_bridge_media_control

Control playback of the system’s current media session.

• action (required): The action to perform. Must be uppercase.

Available actions:

Action	Effect
PLAY	Resume playback.
PAUSE	Pause playback.
STOP	Stop playback.
NEXT	Skip to the next track.
PREVIOUS	Return to the previous track.
VOLUME_UP	Raise the volume.
VOLUME_DOWN	Lower the volume.
MUTE	Toggle mute.

Example arguments:

{ "action": "PAUSE" }

Troubleshooting

Connection refused

• Confirm System Bridge is running. See Running.
• Check the port (default 9170) and SYSTEM_BRIDGE_PORT if you changed it.
• Verify the host in your config matches the machine running the backend.
• Confirm the client uses Streamable HTTP unless it explicitly needs the legacy WebSocket transport.

Unauthorized (401)

• The token is missing or incorrect. Run system-bridge client token on the host running the backend.
• Pass the token as a token query parameter or Authorization: Bearer {token} header.

Tool execution fails

• Check backend logs for the underlying error.
• For system_bridge_get_data, use valid module names (see the table above).
• For system_bridge_media_control, actions must be uppercase (PLAY, PAUSE, and so on).