Windows and WSL2 Troubleshooting

Windows

Desktop app does not start

If the installer completed but the app does not launch:

• Check that the app appears in your Start menu
• Try running it as administrator once to complete initial setup
• Check Windows Defender or your antivirus. Some security software blocks new applications on first run.

Toast notifications not appearing

MCPFirewall uses Windows toast notifications for approval requests. If they do not appear:

1. Open Settings > System > Notifications
2. Make sure notifications are enabled globally
3. Check that “MCPFirewall” appears in the app list and is enabled

No auto-start service

The Windows CLI binary does not include a service manager. Auto-start is handled by the desktop app (Tauri). If you are using the CLI only, add mcpfw serve to your startup folder or use Task Scheduler.

WSL2

AI clients on Windows cannot reach the gateway

By default, the gateway binds to 127.0.0.1, which is only reachable from inside WSL2. Windows AI clients (Claude Desktop, Cursor) run on the Windows host and need the gateway to bind to the WSL2 network interface.

MCPFirewall detects WSL2 automatically and binds to 0.0.0.0. If auto-detection fails, specify it explicitly:

mcpfw serve --bind-addr 0.0.0.0

The gateway prints the accessible IP address in its startup output. Use this IP in your Windows AI client configurations.

Finding the WSL2 IP address

MCPFirewall reads the Windows host IP from /etc/resolv.conf (which WSL2 populates automatically). You can check it manually:

grep nameserver /etc/resolv.conf

This is the IP your Windows apps should use to reach the gateway.

Config paths

When running inside WSL2, MCPFirewall discovers AI clients using Linux paths. For Windows AI clients (which store configs on the Windows filesystem), the paths are:

• Claude Desktop: /mnt/c/Users/<you>/AppData/Roaming/Claude/claude_desktop_config.json
• Cursor: /mnt/c/Users/<you>/.cursor/mcp.json
• VS Code: /mnt/c/Users/<you>/AppData/Roaming/Code/User/mcp.json

If auto-discovery does not find your Windows clients, use Add Custom Integration on the Integrations page and provide the /mnt/c/ path.

Socket transport not available

WSL2 uses TCP transport (not Unix sockets) for shim-to-gateway communication. This is the expected behavior. TCP on localhost is secure within the WSL2 environment.