proxy-doctor

Diagnose proxy misconfigurations that break AI coding tools.

When your browser works fine but Cursor / VS Code / Windsurf AI features don't — proxy-doctor tells you exactly why and how to fix it.

The Problem

AI coding tools (Cursor, VS Code with Copilot, Windsurf) rely on long-lived streaming connections (SSE/HTTP2) that break when:

• Your system proxy points to a localhost port where nothing is listening
• A VPN/proxy app was closed but its settings linger in macOS system preferences
• Your editor inherited stale proxy environment variables from launchctl
• The proxy is running but buffers streaming responses, breaking AI completions

The result: "browser works, AI editor doesn't" — the most common and frustrating developer experience.

What It Checks

proxy-doctor inspects 5 layers of your macOS proxy configuration:

| Layer | What | How | |-------|------|-----| | 1. System Proxy | Web/HTTPS/SOCKS proxy across all network services | networksetup | | 2. Residual Values | Disabled proxies with stale localhost addresses | Parse disabled-but-set entries | | 3. Port Health | Whether referenced proxy ports are actually listening | socket.connect() | | 4. Editor Config | settings.json, argv.json, recent error logs | File read + pattern match | | 5. GUI Environment | http_proxy/https_proxy in GUI app context | launchctl getenv |

Quick Start

CLI

# Install
pip install proxy-doctor

# Run diagnosis (JSON output — default, optimized for AI agents)
proxy-doctor check

# Run diagnosis (human-readable output)
proxy-doctor check --human

# Show recommended fixes
proxy-doctor fix

# Check a different editor
proxy-doctor check --editor vscode

As an MCP Tool (for AI agents)

proxy-doctor ships as an MCP server that AI agents can call directly:

# Install with MCP support
pip install proxy-doctor[mcp]

# Run MCP server
python -m proxy_doctor.mcp_server

Add to your MCP configuration (e.g., Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "proxy-doctor": {
      "command": "python3",
      "args": ["-m", "proxy_doctor.mcp_server"]
    }
  }
}

Note: "command" must point to the Python where proxy-doctor[mcp] is installed. If python3 doesn't work, use the full path (run which python3 or python3 -c "import sys; print(sys.executable)" to find it).

Your AI agent can then call:

• diagnose_proxy(editor="cursor") — full 5-layer diagnosis with evidence
• list_fixes(editor="cursor") — recommended fixes with executable commands
• supported_editors() — list available editors

For AI Agents: Quick Install

One-liner (paste this to your AI agent):

Install proxy-doctor (pip install proxy-doctor[mcp]) and add it to your MCP config with command python -m proxy_doctor.mcp_server. Then use the diagnose_proxy tool to check proxy health.

If you are an AI agent setting up proxy-doctor for your user:

# 1. Install
pip install proxy-doctor[mcp]

# 2. Find the Python path
python3 -c "import sys; print(sys.executable)"

# 3. Add to ~/.cursor/mcp.json (use the path from step 2)
# {
#   "mcpServers": {
#     "proxy-doctor": {
#       "command": "<python-path-from-step-2>",
#       "args": ["-m", "proxy_doctor.mcp_server"]
#     }
#   }
# }



... [View full README on GitHub](https://github.com/Jiansen/proxy-doctor#readme)