Environment Variables

Summary

Variable	Default	Purpose
MCDBUS_NOTIFY_CONFIRM	unset	Enable desktop notification fallback for confirmations
MCDBUS_REQUIRE_ELICITATION	unset	Hard-fail if MCP elicitation is unavailable
MCDBUS_TIMEOUT	30	Timeout in seconds for individual D-Bus method calls

---

MCDBUS_NOTIFY_CONFIRM

Default: unset (disabled)

Enables a desktop notification fallback when the MCP client does not support the elicitation protocol. When set to any non-empty value, confirmation-gated operations (system bus method calls and all property mutations) will display a desktop notification with Approve and Deny action buttons instead of failing or proceeding silently.

How it works

1. A tool requests user confirmation via ctx.elicit()
2. The MCP client does not support elicitation (returns CancelledElicitation or throws)
3. mcdbus sends an org.freedesktop.Notifications.Notify call on the session bus with:
   • Urgency level critical (value 2)
   • Two action buttons: Approve and Deny
   • Icon: dialog-warning
4. The server subscribes to ActionInvoked and NotificationClosed signals
5. If the user clicks Approve within 60 seconds, the operation proceeds
6. If the user clicks Deny, dismisses the notification, or 60 seconds elapse, the operation is denied
7. Match rules and the notification are cleaned up regardless of outcome

If the notification service itself is unreachable (e.g. headless server, no desktop session), the fallback fails gracefully: a warning is logged to stderr and the operation proceeds.

Configuration

Claude Code

claude mcp add -e MCDBUS_NOTIFY_CONFIRM=1 mcdbus -- uvx mcdbus

JSON config

{
  "mcpServers": {
    "mcdbus": {
      "command": "uvx",
      "args": ["mcdbus"],
      "env": {
        "MCDBUS_NOTIFY_CONFIRM": "1"
      }
    }
  }
}

---

MCDBUS_REQUIRE_ELICITATION

Default: unset (disabled)

When set to any non-empty value, mcdbus will raise a ToolError if the MCP client does not support the elicitation protocol. No fallback methods are attempted — not desktop notifications, not silent proceed.

This variable takes precedence over MCDBUS_NOTIFY_CONFIRM. If both are set, MCDBUS_REQUIRE_ELICITATION wins and the notification fallback is never tried.

Use case

Deployments where unconfirmed state-changing operations must never proceed. If you are running mcdbus in an environment where a human must explicitly approve every system bus call and property mutation, set this variable to guarantee that requirement is enforced at the protocol level.

Configuration

Claude Code

claude mcp add -e MCDBUS_REQUIRE_ELICITATION=1 mcdbus -- uvx mcdbus

JSON config

{
  "mcpServers": {
    "mcdbus": {
      "command": "uvx",
      "args": ["mcdbus"],
      "env": {
        "MCDBUS_REQUIRE_ELICITATION": "1"
      }
    }
  }
}

Precedence

MCDBUS_REQUIRE_ELICITATION	MCDBUS_NOTIFY_CONFIRM	Behavior when elicitation unavailable
unset	unset	Warning logged to stderr, operation proceeds
unset	set	Desktop notification fallback attempted
set	unset	ToolError raised
set	set	ToolError raised (require wins)

---

MCDBUS_TIMEOUT

Default: 30 (seconds)

Sets the timeout for individual D-Bus method calls made through call_bus_method. This applies to all tool invocations that make D-Bus calls, including discovery, interaction, and shortcut tools.

The value is parsed as a float, so fractional seconds are supported (e.g. "2.5").

Relationship to other timeouts

The list_objects tool enforces its own TOTAL_WALK_TIMEOUT of 60 seconds for the entire breadth-first walk. This is a wall-clock deadline for the full tree traversal, separate from the per-call timeout. Each individual introspect call within the walk still respects MCDBUS_TIMEOUT. A slow service that takes 25 seconds per introspection call would hit the walk timeout after two or three nodes even though no single call timed out.

Configuration

Claude Code

claude mcp add -e MCDBUS_TIMEOUT=10 mcdbus -- uvx mcdbus

JSON config

{
  "mcpServers": {
    "mcdbus": {
      "command": "uvx",
      "args": ["mcdbus"],
      "env": {
        "MCDBUS_TIMEOUT": "10"
      }
    }
  }
}