Session vs System Bus

Linux systems running D-Bus have two distinct message buses. Every mcdbus tool takes a bus parameter — either "session" or "system" — that selects which one to talk to. The choice affects what services are available, what permissions are required, and whether mcdbus prompts for confirmation.

The session bus

The session bus is per-user, per-login-session. It starts when you log in (typically managed by dbus-daemon --session or dbus-broker --scope user) and dies when you log out. Its address is stored in the DBUS_SESSION_BUS_ADDRESS environment variable.

Desktop applications and user services register here. The session bus is where you find:

• Notification daemons (org.freedesktop.Notifications)
• Media players via MPRIS2 (org.mpris.MediaPlayer2.*)
• Desktop environment components (KDE KWin, GNOME Shell, etc.)
• XDG portals (org.freedesktop.portal.*)
• User-level systemd (org.freedesktop.systemd1 on the session bus manages systemctl --user services)
• Input methods, screen savers, file managers

Because the session bus is scoped to your user session, any process running as your user can send messages to any service on it. There is no authentication step — if you can reach the socket, you can talk. This is by design: desktop applications need to communicate freely within a single user’s session.

mcdbus treats session bus operations as low-risk. Method calls on the session bus execute without a confirmation prompt. Property mutations (via set_property) still prompt because they change state, but the prompt is about intent rather than privilege.

The system bus

The system bus is system-wide. There is exactly one instance, started at boot by the init system. Its socket lives at /var/run/dbus/system_bus_socket (or equivalent). Every user on the machine can connect to it, but access is tightly controlled.

System-level services register here:

• systemd manager (org.freedesktop.systemd1)
• NetworkManager (org.freedesktop.NetworkManager)
• UPower battery management (org.freedesktop.UPower)
• bluez Bluetooth stack (org.bluez)
• udisks2 disk management (org.freedesktop.UDisks2)
• Avahi mDNS/DNS-SD (org.freedesktop.Avahi)
• CUPS printing (org.cups.cupsd)
• Accounts service (org.freedesktop.Accounts)

The system bus has stricter access control than the session bus. D-Bus bus policy files (XML configs in /etc/dbus-1/system.d/) define which users can send messages to which services. Many services also perform polkit authorization checks before executing privileged operations.

mcdbus treats system bus method calls as sensitive. Calling call_method with bus="system" triggers a confirmation prompt (via the confirmation flow) before the message is sent. Read-only operations through the shortcut tools (battery_status, network_status, bluetooth_devices, list_systemd_units) do not trigger confirmation because they only read properties — they never call service-specific methods that could change state.

What lives where

Service	Session bus	System bus	Notes
Notifications	Yes	—	Desktop notifications are per-user
MPRIS2 media players	Yes	—	Media players are user applications
KDE KWin	Yes	—	Window manager is per-session
XDG portals	Yes	—	Sandboxed app integration
systemd	Yes (user units)	Yes (system units)	Different manager instances
NetworkManager	—	Yes	System-wide network config
UPower	—	Yes	Hardware battery status
bluez	—	Yes	Bluetooth adapter and devices
udisks2	—	Yes	Disk and partition management
Avahi	—	Yes	mDNS service discovery
Accounts	—	Yes	User account management

Note

Some services register on both buses. systemd is the most prominent example: org.freedesktop.systemd1 on the session bus manages your user services (systemctl --user), while the same name on the system bus manages system services (systemctl). They are separate manager instances with different capabilities.

Security implications

The distinction between the two buses is a security boundary. The session bus assumes all participants are the same user and can be trusted at a basic level. The system bus assumes participants may be different users with different privilege levels and enforces access control accordingly.

For mcdbus, this means:

• Session bus: Low friction. Services are user-scoped. The worst case for an unintended call is usually a skipped track or a stray notification.
• System bus: Higher friction. Services can affect the entire machine. An unintended call could restart a system service, change network configuration, or trigger a disk operation. The confirmation prompt exists to prevent this.

The Lock Down Permissions guide covers how to add additional restrictions beyond mcdbus’s built-in confirmation behavior, using the operating system’s own D-Bus permission stack.

The bus parameter

Every mcdbus tool accepts the bus parameter as either "session" or "system". There are no other valid values. The parameter is a string, not an enum, because MCP tool arguments are JSON-typed.

Shortcut tools that target a specific bus have sensible defaults:

Tool	Default bus	Reason
send_notification	session (hardcoded)	Notifications are a session bus service
media_player_control	session (hardcoded)	MPRIS2 players are session bus services
battery_status	system (hardcoded)	UPower is a system bus service
network_status	system (hardcoded)	NetworkManager is a system bus service
bluetooth_devices	system (hardcoded)	bluez is a system bus service
kwin_windows	session (hardcoded)	KWin is a session bus service
list_systemd_units	system (default, overridable)	System units are the common case, but bus="session" shows user units

Discovery tools (list_services, list_objects, introspect) and interaction tools (call_method, get_property, set_property, get_all_properties) require the bus parameter explicitly. There is no default because assuming the wrong bus leads to confusing errors.