Web Proxy

You operate an intelligent HTTP/HTTPS proxy that integrates Model Context Protocol (MCP) to monitor, analyze, and automate browser proxy setup. This server lets you selectively proxy traffic, generate PAC files, and extract HARs while keeping most traffic direct. It supports real-time analysis, target management, and browser setup scripts to streamline testing, debugging, and security workflows.

How to use

You interact with the proxy server through an MCP client to manage targets, start or stop the server, and generate browser configuration assets. Use MCP commands to add domains you want to monitor, launch the proxy, and produce setup scripts that configure your browsers or system to route traffic through the proxy. You can then view captured traffic, analyze patterns, and export HAR files for external analysis.

Common usage patterns include adding a target domain, starting the proxy, and generating a setup package for multiple browsers. You can also request a PAC file to enable automatic proxy routing for monitored domains only, while other domains bypass the proxy for normal performance.

Here is a typical workflow you can follow: add a target domain to monitor, start the proxy server, generate browser setup scripts, and apply the generated configuration to Chrome, Firefox, or system proxies. Then you can capture traffic, analyze it, and export HAR data for reporting or debugging.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. Node.js provides the runtime for the MCP server, and npm handles dependency installation.

Step 1: Navigate to the MCP Web Proxy server directory.

cd /home/solar/docker-appliance/mcp-servers/web-proxy-mcp

Step 2: Install dependencies required by the server.

npm install

Step 3: Start the proxy server in one of these ways.

npm start

or

node index.js

Additional configuration and usage notes

The proxy serves HTTP and supports HTTPS tunneling via CONNECT. It automatically generates a PAC file at the path /proxy.pac and defaults to listening on port 8080, which you can configure. You selectively proxy traffic by adding targets, and you can capture headers and bodies for monitored domains.

To integrate with an editor or automation tool, add the MCP server configuration to your environment. A typical local MCP configuration uses a stdio-based entry that runs the server binary with its main script.

Configuration and security notes

Targets are stored in persistent storage and include fields like domain, description, enabled status, and whether to capture headers or bodies. You can enable or disable monitoring per target and adjust what data you collect to balance debugging needs with sensitivity concerns.

Security considerations include that the default setup binds to localhost, monitoring is limited to configured targets, and body capture is optional to minimize exposure of sensitive data. You can enable header capture for debugging when needed.

Troubleshooting

Common issues include port conflicts (change the proxy port), browsers not using the proxy (verify PAC URL or manual settings), HTTPS problems (certificate handling), and no traffic captured (confirm that targets are configured).

If you need to diagnose, run with debug logging to surface detailed output. For example, set DEBUG=web-proxy-mcp before starting the server to see extended logs.

Logs include console output for server activity and persistent traffic logs stored under data/traffic-log.json, with target configurations in data/targets.json.

Notes

This MCP server is designed to work with an MCP client for natural language control, automated analysis, and configuration management. You can request traffic analyses, export HAR data, and generate setup scripts to streamline browser and system configurations.

Available tools

proxy_add_target

Add domains to monitor and begin capturing traffic for those targets.

proxy_remove_target

Remove domains from the monitored target list to stop capturing traffic for those domains.

proxy_list_targets

List all configured targets with their monitoring status and capture settings.

proxy_update_target

Update the configuration for an existing target, such as enabling or disabling capture or changing the description.

proxy_start_server

Start the proxy server on the configured host/port and initialize monitoring.

proxy_stop_server

Stop the running proxy server and finalize any in-progress captures.

proxy_server_status

Retrieve current server status and statistics, including active targets and traffic metrics.

proxy_generate_setup

Generate browser setup scripts and PAC file configurations for Chrome, Firefox, system proxies, and curl.

proxy_get_pac_file

Provide the PAC file content for manual or automated proxy configuration.

proxy_get_traffic_log

Return captured traffic records for a given target or domain with optional limits.

proxy_export_har

Export traffic data in HAR format for external analysis and reporting.

proxy_clear_traffic_log

Clear the collected traffic logs to reset analysis history.

proxy_analyze_traffic

Analyze traffic patterns, performance metrics, and domain-specific behavior.

proxy_import_config

Import proxy configuration from a file to restore targets and settings.

proxy_export_config

Export the current proxy configuration to a file for backup or transfer.

proxy_get_performance_metrics

Provide performance monitoring metrics such as latency and throughput per target.