Linux Troubleshooting

systemd service fails to start

Check the logs:

journalctl --user -u mcpfw -n 50

Common causes:

Binary not on PATH for the systemd user session. The service file stores the full path at install time. If you moved the binary, reinstall:
Terminal window
```
mcpfw service uninstall
mcpfw service install
mcpfw service start
```
XDG_RUNTIME_DIR not set. This is needed for the Unix socket. On most desktop Linux systems it is set automatically. On headless servers, you may need to set it manually or use TCP transport instead.

systemd user services only start when a user session exists. On a headless server (no graphical login), enable lingering:

loginctl enable-linger $USER

This lets your user services start at boot without a login session.

MCPFirewall uses the FreeDesktop notification API via D-Bus. If notifications do not appear:

Check that a notification daemon is running (dunst, mako, notify-osd, or your desktop environment’s built-in daemon)
Verify D-Bus session is available: echo $DBUS_SESSION_BUS_ADDRESS
On headless systems, D-Bus notifications are silently skipped. This is expected.

The inline Approve/Deny buttons in Linux notifications require a notification daemon that supports actions (most modern ones do).

If shims cannot connect to the gateway socket:

ls -la ~/.mcpfw/gateway.sock

The socket should be owned by your user with 0600 permissions. If something changed them:

chmod 700 ~/.mcpfw/
mcpfw service restart

On Linux, the gateway also verifies peer credentials via SO_PEERCRED. Only processes running as your user can connect.

MCPFirewall auto-discovers VS Code in standard, Flatpak, and Snap install locations. If your VS Code installation is not detected:

If your path is different, use the Add Custom Integration option on the Integrations page.

Check what is using port 8765:

ss -tlnp | grep 8765

Either stop that process or start the gateway on a different port:

mcpfw serve --port 9000