Fix MCP Browser Screenshot Certificate Warnings

If you use the MCP (Model Context Protocol) browser tool and your screenshots come back showing a browser certificate warning page instead of the actual site, the issue is almost always a TLS/SSL trust problem between the headless browser and the target server. This guide walks through the exact steps to identify why the certificate is being rejected and how to fix it so your screenshots capture the real content.

What You’ll Need

Access to the machine where the MCP browser server is running (local or remote).
Read/write access to the MCP server configuration file (often mcp.json, config.json, or set via environment variables).
Knowledge of the target URL that is failing.
Basic command-line access to run diagnostic commands like curl or openssl.

Step-by-Step

Reproduce the issue and note the exact warning text. Take a screenshot manually. The warning page will usually say something like “Your connection is not private”, “NET::ERR_CERT_AUTHORITY_INVALID”, or “NET::ERR_CERT_DATE_INVALID”. Write down the exact error code; it tells you which part of the certificate chain is failing.
Check the certificate from the command line. Run openssl s_client -connect example.com:443 -servername example.com (replace with your target). Look at the output for “Verify return code”. A code of 0 means the certificate is valid from your machine’s perspective. If you get 20 (unable to get local issuer certificate) or 21 (unable to verify the first certificate), the server is using a certificate that your system doesn’t trust.
Determine if the certificate is self-signed or from a private CA. If the target is an internal tool (like a staging server or a corporate app), it likely uses a self-signed certificate or one issued by an internal Certificate Authority. Public websites rarely cause this issue unless they have a misconfigured chain.
Decide on the fix: trust the certificate or bypass verification. The correct fix depends on your environment. For production and public sites, fix the server’s certificate chain. For internal tools, you have two options: add the CA certificate to the system trust store, or configure the MCP browser to ignore certificate errors.
Add the CA certificate to the system trust store (recommended for internal CAs). Export the CA certificate (not the leaf cert) from the server or your internal PKI. On Linux, copy it to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates. On macOS, open the certificate file in Keychain Access, add it to “System”, and mark it as trusted. On Windows, import it into “Trusted Root Certification Authorities”. Restart the MCP browser server after making the change.
If you cannot add a CA, configure the MCP browser to ignore certificate errors. Most headless browser implementations (Playwright, Puppeteer) have a flag for this. In Playwright, launch the browser with ignoreHTTPSErrors: true. In Puppeteer, use args: ['--ignore-certificate-errors']. Find where the MCP server launches the browser (often in its config or code) and add the appropriate flag. This is a security trade-off and should only be used for testing or internal tools.
Check the system clock. A certificate warning with NET::ERR_CERT_DATE_INVALID often means the machine running the MCP server has the wrong date or time. Run date on the server. If it’s off by more than a few minutes, fix it with NTP (sudo timedatectl set-ntp true on Linux, or enable “Set time automatically” on macOS/Windows).
Restart the MCP browser server. After any change to trust stores, browser flags, or the system clock, the MCP server process must be restarted. If it runs as a service, use systemctl restart mcp-browser or equivalent. If it’s a background process, kill it and start it again.
Re-take the screenshot. Request a new screenshot through your MCP client. It should now show the actual page content instead of the warning.

Common Mistakes

Adding the leaf certificate instead of the CA certificate. The browser needs to trust the issuer, not just the individual site’s certificate. Adding the leaf cert to the trust store rarely works and can cause other errors.
Editing the wrong config file. Some MCP setups have a global config and a project-specific config. Make sure you’re editing the one the server actually reads. Check the server’s startup logs to see which config path it loads.
Forgetting to restart the server after adding a certificate. The trust store is read at browser launch time. If you don’t restart, the old browser process still has the old trust settings.
Using --ignore-certificate-errors on a public-facing production server. This disables all TLS verification for that browser instance, making it vulnerable to man-in-the-middle attacks. Only use it for internal, non-sensitive tools.
Assuming the warning is from the target site. Sometimes the MCP browser itself has a proxy configured that presents its own certificate. Check the server’s environment variables for HTTP_PROXY or HTTPS_PROXY; if present, the proxy’s cert may be the issue.

Tips

Test with curl first. Run curl -v https://example.com from the same machine. If curl shows a certificate error, the problem is system-wide and not specific to the browser. If curl succeeds but the browser fails, the issue is in the browser’s own certificate store or flags.
Use a dedicated user-data directory for the browser. If the MCP browser uses a persistent profile, it may have cached the bad certificate state. Configure it to use a fresh temporary profile directory to rule out caching issues.
Check for intermediate certificate omissions. A common server misconfiguration is sending only the leaf certificate without the intermediate chain. Use openssl s_client -showcerts to see the full chain. If the intermediate is missing, ask the server admin to fix it; it’s not something you can fix client-side.
Document the exception. If you’re using the ignore-errors flag, add a comment in your config file explaining why, so a future maintainer doesn’t remove it accidentally.

Troubleshooting

The warning still appears after adding the CA. Verify the CA was added correctly by running openssl verify -CAfile /path/to/ca.pem example.com.pem. If it fails, the CA file is wrong or incomplete. Also confirm the MCP server is actually using the system trust store – some headless browsers (especially older Chromium builds) use their own bundled store. In that case, you must use the browser-specific flag to add the CA, not the system one.

The screenshot shows a blank page instead of a warning. This can mean the browser is silently failing to load. Check the MCP server logs for TLS errors. If the logs show a handshake failure, the server may be using an outdated TLS version. Try adding --ssl-version-max=tls1.3 to the browser args if supported.

Only some URLs fail. If internal URLs fail but public ones work, it’s definitely a private CA issue. If public URLs fail too, check if the MCP server is routing through a corporate proxy that intercepts TLS. Look at the server’s environment variables and the browser’s proxy settings.

The fix works but breaks after a restart. This usually means the configuration change wasn’t persisted. If you added a browser flag via a command-line argument in a script, make sure the script is saved. If you added a CA cert, confirm it’s in the correct directory that survives reboots (e.g., not /tmp).

You cannot modify the MCP server code or config. If the server is a managed service or you don’t have access, the only option is to fix the server-side certificate. Ask the site administrator to install a publicly trusted certificate (e.g., from Let’s Encrypt) or to properly configure the internal CA chain.

Frequently Asked Questions

Q: Is it safe to use ignoreHTTPSErrors for production?
A: No. It disables all certificate validation, meaning any attacker could intercept the traffic. Use it only for testing or internal tools that don’t handle sensitive data.

Q: Why does the screenshot show the warning but my regular browser loads the site fine?
A: Your regular browser likely has the internal CA installed in its own trust store, or it uses a different network path. The headless browser used by MCP may not have that CA, or it may be running on a different machine.

Q: What does NET::ERR_CERT_AUTHORITY_INVALID mean exactly?
A: It means the browser cannot find a trusted certificate authority that signed the server’s certificate. The server’s cert is signed by an unknown CA, or the chain is broken.

Q: Can I fix this by setting an environment variable?
A: Some browsers respect NODE_EXTRA_CA_CERTS (for Node.js-based tools) or SSL_CERT_FILE. If your MCP server runs on Node.js, try NODE_EXTRA_CA_CERTS=/path/to/ca.pem. For Python-based servers, SSL_CERT_FILE may work.

Q: The certificate is expired. What should I do?
A: Renew the certificate on the server. Do not bypass the error for an expired cert, as it indicates a real security issue. If the server is internal, you may need to renew it manually.

Q: Will this affect other MCP tools that use the same browser?
A: Yes, if they share the same browser instance or profile. The fix is global for that browser. If you need different settings for different tools, run separate MCP browser servers with different configurations.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →