Configuration

These tools control session-level configuration, privacy settings, and connection health diagnostics.

firefox_set_config

Set per-session configuration for this agent. Currently supports domain allowlisting to restrict navigation to specific domains (security sandboxing).

Parameters

Parameter	Type	Required	Default	Description
allowedDomains	string[]	No	-	List of allowed domains. Supports wildcards: "*.example.com". When set, firefox_navigate and firefox_create_window block requests to unlisted domains. Pass an empty array to clear the restriction.
handleConsent	boolean	No	false	When true, automatically attempt to dismiss GDPR/cookie consent overlays 800ms after every firefox_create_window or firefox_navigate (fire-and-forget, non-blocking). Set to false to disable auto-consent.
timeout	number	No	150000	Request timeout in ms (5000-300000)

Example

// Restrict to a single domain
const result = await firefox_set_config({
  allowedDomains: ["example.com"]
});

// Allow a domain and all subdomains
const result = await firefox_set_config({
  allowedDomains: ["example.com", "*.example.com"]
});

// Clear domain restrictions
const result = await firefox_set_config({
  allowedDomains: []
});

// Enable automatic consent overlay dismissal
const result = await firefox_set_config({
  handleConsent: true
});
// Now consent overlays will be auto-dismissed 800ms after each navigation

// Disable auto-consent
const result = await firefox_set_config({
  handleConsent: false
});

Notes

• Domain restrictions apply only to the current agent session. Other agents are unaffected.
• Restrictions apply to both firefox_navigate and firefox_create_window.
• Use this for security sandboxing when you want to prevent accidental navigation to unintended sites.
• handleConsent: true enables automatic GDPR/consent overlay dismissal. For explicit control, use firefox_handle_consent tool directly.

---

firefox_set_private_mode

Enable or disable private (incognito) browsing mode. When disabled, new windows use regular browsing with persistent cookies.

Parameters

Parameter	Type	Required	Default	Description
enabled	boolean	Yes	-	true = private/incognito windows (default behavior), false = regular windows with persistent cookies
timeout	number	No	150000	Request timeout in ms (5000-300000)

Example

// Disable private mode to access sites requiring login
const result = await firefox_set_private_mode({ enabled: false });

// Navigate to a site that needs cookies
await firefox_create_window({ url: "https://x.com" });

// Re-enable private mode when done
await firefox_set_private_mode({ enabled: true });

Notes

• Private mode is enabled by default.
• Disable private mode when you need to access sites that require login or persistent cookies (e.g., X.com, authenticated dashboards).
• This setting affects new windows only. Existing windows retain their original mode.

Mode Awareness (v0.6.4+)

You don’t have to call firefox_set_private_mode blind — the current window mode and Firefox’s private-window capability are exposed in two responses you’re already going to see:

• firefox_activate response now includes privateWindowsAvailable (whether Firefox has granted the incognito permission) and currentWindowMode (the mode of the existing shared window, or null if no window is open yet). Use this to decide whether you can safely request private mode at all.
• firefox_create_window response carries isPrivate, privateFallback, and modeWarning fields so the agent always knows the actual mode of the tab it just opened, even when the requested mode wasn’t honored. See firefox_create_window notes for auto-fallback behavior.

If you set private: true on firefox_create_window while the existing shared window is non-private (or vice-versa), the call returns a structured MODE_MISMATCH error instead of silently producing the wrong mode.

---

firefox_diagnose

Diagnose Claudezilla connection health. Checks socket file, auth token, connection status, and extension version. Use this when troubleshooting connection issues.

Parameters

This tool takes no parameters. It runs locally on the MCP server without communicating through the extension.

Example

const result = await firefox_diagnose();
// Returns diagnostics including:
// - Socket file existence and permissions
// - Auth token status
// - Connection state
// - Extension version

Notes

• This tool runs locally and does not go through the Firefox extension. It works even when the extension connection is broken.
• Does not accept the timeout parameter (unlike all other tools).
• Use this as a first step when any other Claudezilla tool returns connection errors.

Tool Discovery and Activation

Claudezilla supports two catalog-loading modes. Lazy discovery is the default for Claude Code: only firefox_activate is exposed initially, saving approximately 6,400 context tokens. After activation, the server emits notifications/tools/list_changed so clients can refresh the dynamically available tools.

Clients that discover tools only once at startup should use eager discovery. Start the server with --all-tools, --tools all, or set CLAUDEZILLA_TOOL_MODE=all. This exposes the complete catalog immediately. The firefox_activate tool remains available as a backward-compatible no-op in eager mode.

Session and cleanup settings:

• CLAUDEZILLA_AGENT_TIMEOUT_MS overrides the default 600,000 ms (10-minute) idle-agent reaper threshold. Use a positive millisecond value for human-in-the-loop workflows that leave tabs idle between calls.
• Session ID priority is --resume <id>, --session-id <id>, CLAUDEZILLA_SESSION_ID, OMP_SESSION_ID, PI_SESSION_ID, HERMES_SESSION_ID, CLAUDE_CODE_SESSION_ID, then the host’s __default__ bucket.

See Tool Discovery for the activation schema and category list.