Explore Unknown Services

One of the most valuable uses of mcdbus is exploring D-Bus services you have never worked with before. The discovery tools let you walk the entire object hierarchy, read interfaces, and test methods — all through conversation with Claude. No prior knowledge of the service is required.

This guide walks through the full workflow using a real example: discovering what the Flatpak system helper exposes on D-Bus.

The five-step workflow

1. Find the service. List everything on the bus and look for the service name.

2. Walk the object tree. See what object paths the service exposes.

3. Introspect an object. Read its interfaces, methods, properties, and signals.

4. Read properties. Get the current state without changing anything.

5. Call methods. Interact with the service.

Step 1: List services

Start by listing all well-known service names on the bus you want to explore:

“What services are on the system bus?”

list_services(bus="system")

This returns every well-known service name. On a typical desktop system, there are 30-80 services on the system bus. Claude can scan the list and highlight anything relevant to what you are looking for.

For the session bus, the same approach works:

list_services(bus="session")

Session bus services tend to include desktop environment components, media players, file managers, and application portals.

Tip

If you already know the service name, skip this step. The discovery tools do not require you to start from scratch every time.

Step 2: Walk the object tree

Once you have a service name, see what object paths it exposes:

“Show me the object tree for org.freedesktop.Flatpak.SystemHelper.”

list_objects(bus="system", service="org.freedesktop.Flatpak.SystemHelper")

The tool performs a breadth-first walk starting from /, introspecting each node to find children. The result is a flat list of all object paths with their non-standard interfaces:

- `/` -- (no interfaces)
- `/org/freedesktop/Flatpak/SystemHelper` -- `org.freedesktop.Flatpak.SystemHelper`

Some services have deep trees with hundreds of objects (bluez, systemd). Others, like this one, have just one or two meaningful paths.

The walk is bounded: it stops at 500 objects or 60 seconds, whichever comes first. You can also scope it to a subtree:

list_objects(
    bus="system",
    service="org.freedesktop.systemd1",
    root_path="/org/freedesktop/systemd1/unit"
)

Step 3: Introspect

Pick an object path and look at its interfaces in detail:

“Introspect the Flatpak system helper.”

introspect(
    bus="system",
    service="org.freedesktop.Flatpak.SystemHelper",
    object_path="/org/freedesktop/Flatpak/SystemHelper"
)

The response shows every interface, its methods (with argument names, types, and directions), properties (with type and read/write access), and signals. Standard interfaces like org.freedesktop.DBus.Peer and org.freedesktop.DBus.Introspectable are filtered out by default. To include them:

introspect(
    bus="system",
    service="org.freedesktop.Flatpak.SystemHelper",
    object_path="/org/freedesktop/Flatpak/SystemHelper",
    include_standard=true
)

Step 4: Read properties

Before calling any methods, read the service’s current state:

“Read all properties on the Flatpak SystemHelper interface.”

get_all_properties(
    bus="system",
    service="org.freedesktop.Flatpak.SystemHelper",
    object_path="/org/freedesktop/Flatpak/SystemHelper",
    interface="org.freedesktop.Flatpak.SystemHelper"
)

Properties are returned as a markdown table with name-value pairs. Values longer than 80 characters are truncated for readability. For the full value of a specific property, use get_property:

get_property(
    bus="system",
    service="org.freedesktop.Flatpak.SystemHelper",
    object_path="/org/freedesktop/Flatpak/SystemHelper",
    interface="org.freedesktop.Flatpak.SystemHelper",
    property_name="version"
)

Step 5: Call methods

Once you understand the interface, you can call methods. On the session bus, this happens immediately. On the system bus, mcdbus asks for confirmation first.

“Call GetServerInformation on the notification daemon.”

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="GetServerInformation"
)

For methods that take arguments, you need to provide the D-Bus type signature and a JSON array of arguments. The introspect output shows the expected types for each method parameter.

Using the explore_service prompt

Instead of manually stepping through each stage, you can activate the explore_service prompt to get a guided walkthrough:

“Use the explore_service prompt for org.freedesktop.Flatpak.SystemHelper on the system bus.”

This loads a step-by-step guide into the conversation context, directing Claude through the same workflow automatically. The prompt accepts two parameters:

• bus: “session” or “system” (default: “session”)
• service: the service name to explore (optional — if omitted, starts from listing all services)

Using the debug_service prompt

When a service is not behaving as expected — method calls failing, properties returning unexpected values, or the service not appearing at all — use the debug_service prompt:

“Use the debug_service prompt for org.freedesktop.Notifications on the session bus.”

This loads a diagnostic workflow that checks:

1. Whether the service is registered on the bus
2. Whether the root path is introspectable
3. The full object tree
4. Current property values on key interfaces
5. Basic connectivity via the Peer interface’s Ping method

Tips for exploring unfamiliar services

Start with properties, not methods. Properties are read-only by default and give you a snapshot of the service’s state without risk of changing anything.

Use include_standard=false (the default). Standard D-Bus interfaces are the same on every object. Filtering them out makes the output much easier to read.

Check both buses. Some services register on both the session and system bus with different capabilities. NetworkManager, for example, has a presence on the system bus (full control) and sometimes the session bus (limited status).

Look for ObjectManager. Services that manage a collection of objects (bluez for Bluetooth devices, UPower for power devices, udisks2 for storage) typically implement org.freedesktop.DBus.ObjectManager at their root path. Calling GetManagedObjects on that interface returns the entire device tree in one call, which is much faster than walking the tree node by node.