How Proxy Settings Are Validated and Applied to Network Requests in 5ire

5ire validates proxy URLs through a strict validateAndGetProxy function that throws on malformed input, then applies them either as environment variables to MCP subprocesses or as HttpsProxyAgent instances for direct HTTP requests.

The open-source 5ire application (available at nanbingxyz/5ire) implements a centralized proxy management system that ensures only syntactically valid proxy URLs reach the network stack. This article examines the validation logic, application mechanisms for both Model Context Protocol (MCP) servers and generic HTTP requests, and the configuration sources that feed into this pipeline.

Understanding Proxy Configuration Sources

Users can define proxy settings in two primary locations within the 5ire codebase. First, the MCP configuration file (src/mcp.config.ts) accepts an optional proxy field for remote server connections. Second, provider-specific settings stored in src/stores/useProviderStore.ts allow per-provider proxy definitions that the UI layer retrieves when constructing requests.

When a proxy is specified, the value flows through a validation gate before any network activity occurs. This prevents invalid configurations from causing silent failures or security vulnerabilities in the request pipeline.

Strict URL Validation with validateAndGetProxy

Before application, every proxy string undergoes rigorous validation in src/main/mcp.ts. The validateAndGetProxy function attempts to construct a URL object from the input string. If the constructor throws, the function logs the error via the injected Logger and throws an exception, halting execution.

// src/main/mcp.ts
function validateAndGetProxy(proxyUrl: string): string {
  try {
    const url = new URL(proxyUrl);
    return url.toString();
  } catch (error) {
    Container.inject(Logger).error(`Invalid proxy URL: ${proxyUrl}`, error);
    throw new Error(`Invalid proxy URL: ${proxyUrl}`);
  }
}

This validation runs immediately before proxy application, ensuring that malformed URLs never reach subprocess environments or HTTP agent configurations. The function returns the normalized URL string only after successful parsing.

Applying Proxies to Network Requests

Once validated, 5ire applies proxy settings through two distinct mechanisms depending on the request type: environment variable injection for MCP subprocesses and agent-based routing for direct HTTP requests.

MCP Subprocess Environment Injection

For Model Context Protocol servers launched as child processes, 5ire injects the validated proxy URL into the process environment. In src/main/mcp.ts, the activation logic passes HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables to the StdioTransport constructor when a proxy is configured.

// src/main/mcp.ts (activation logic)
...(proxy
  ? {
      HTTP_PROXY: validateAndGetProxy(proxy),
      HTTPS_PROXY: validateAndGetProxy(proxy),
      ALL_PROXY: validateAndGetProxy(proxy),
    }
  : {}),

This approach leverages the conventional proxy-aware behavior of underlying command-line tools and transport layers, allowing the MCP server to route its own outbound connections through the specified proxy automatically.

Direct HTTP Requests via HttpsProxyAgent

For HTTP requests handled by the main process, 5ire integrates the https-proxy-agent package. The IPC request handler in src/main/main.ts checks for a proxy option in incoming requests. When present, it instantiates an HttpsProxyAgent with the validated URL and attaches it to the fetch options.

// src/main/main.ts (IPC request handler)
let agent: HttpsProxyAgent<string> | undefined;
if (proxy) {
  try {
    agent = new HttpsProxyAgent(proxy);
    logger.info(`Using proxy: ${proxy}`);
  } catch (error) {
    logger.error(`Invalid proxy URL: ${proxy}`, error);
  }
}

const fetchOptions: any = {
  method,
  headers,
  signal: abortController.signal,
  ...(agent && { agent }),
};

All subsequent fetch calls within that request scope route through the configured proxy without requiring modifications to the core request logic.

Configuration Examples

To configure a proxy for an MCP server, users modify the configuration object in src/mcp.config.ts or the persisted JSON configuration:

// Example MCP configuration with proxy
{
  key: "myRemote",
  url: "http://remote-mcp.example.com",
  proxy: "http://proxy.company.local:3128"
}

For direct API requests from the renderer process, the proxy parameter travels through the IPC bridge defined in src/main/preload.ts:

// Renderer process invoking a proxied request
await window.electron.invoke("request", {
  url: "https://api.openai.com/v1/models",
  method: "GET",
  headers: { Authorization: `Bearer ${token}` },
  proxy: "http://proxy.company.local:3128",
});

Summary

• Validation occurs centrally via validateAndGetProxy in src/main/mcp.ts, which throws exceptions for malformed URLs before they reach the network stack.
• MCP subprocesses receive proxy settings through standard environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) during StdioTransport initialization.
• Direct HTTP requests use HttpsProxyAgent from the https-proxy-agent package, instantiated in src/main/main.ts and attached to fetch options.
• Configuration originates from either src/mcp.config.ts for server definitions or src/stores/useProviderStore.ts for provider-specific settings.

Frequently Asked Questions

What happens if I provide an invalid proxy URL in 5ire?

The application throws an error immediately upon validation. The validateAndGetProxy function logs the invalid URL via the Logger service and throws an exception with the message Invalid proxy URL: ${proxyUrl}, preventing any network activity from occurring with the malformed configuration.

Does 5ire support different proxies for HTTP and HTTPS traffic?

The current implementation uses a single proxy URL for both protocols. When applied to MCP subprocesses, the same validated URL is assigned to both HTTP_PROXY and HTTPS_PROXY environment variables. For direct requests, the single HttpsProxyAgent handles all traffic through the specified proxy.

Where does 5ire store proxy configurations for providers?

Provider-specific proxy settings are managed in src/stores/useProviderStore.ts. The store retrieves the proxy value using the expression customProvider?.proxy || '', feeding it into the request pipeline when users select that provider in the UI.

Can I use a proxy with local MCP servers?

Proxy configuration is primarily intended for remote MCP servers that require external network access. Local subprocesses can be configured with a proxy, but the environment variable injection only occurs when a proxy value is explicitly provided in the server configuration at src/mcp.config.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}