Proxy Configuration

This page documents how the MCP server routes outbound HTTP traffic through an optional proxy, including the environment variable priority chain, the internal functions that implement proxy-aware fetching, and example configurations for corporate network environments.

For the full list of all environment variables (including non-proxy settings like PERPLEXITY_API_KEY, PERPLEXITY_TIMEOUT_MS, and PERPLEXITY_LOG_LEVEL), see Environment Variables Reference. For how the proxy fits into the overall network topology, see System Architecture.

---

Overview

All outbound requests from the server to api.perplexity.ai go through a single fetch wrapper called proxyAwareFetch. When a proxy URL is detected in the environment, this function switches from the native fetch global to undici's ProxyAgent-backed fetch. When no proxy is set, it passes the call directly to the native fetch global.

No proxy configuration is required for direct internet connections. It is only necessary in environments where outbound HTTPS traffic must transit a corporate proxy or firewall.

---

Proxy Resolution Priority Chain

The server reads proxy settings by calling getProxyUrl(), exported from src/server.ts. This function checks three environment variables in a fixed priority order and returns the first one that is defined.

Priority order:

Priority	Variable	Notes
1 (highest)	PERPLEXITY_PROXY	MCP-server-specific; overrides all others
2	HTTPS_PROXY	Standard convention for HTTPS proxies
3	HTTP_PROXY	Standard convention for HTTP proxies
—	(none set)	getProxyUrl() returns undefined; direct connection used

If none of the three variables is set, getProxyUrl() returns undefined and proxyAwareFetch uses the native global fetch without any proxy agent.

Proxy Resolution: getProxyUrl priority chain

Sources: src/server.test.ts60-113 README.md134-138

---

proxyAwareFetch Implementation

proxyAwareFetch is exported from src/server.ts and is the single outbound HTTP call site used by both performChatCompletion and performSearch. It delegates to different underlying clients depending on whether getProxyUrl() returns a value.

Fetch dispatch: proxyAwareFetch logic

Sources: src/server.test.ts116-193 src/index.test.ts740-784

Key behavioral details:

• When no proxy is set, global.fetch is called directly. This means the standard Node.js fetch stack is used and any options (headers, body, signal) are passed through unchanged.
• When a proxy URL is present, global.fetch is not called. undici handles the connection and tunnels HTTPS traffic through the proxy using CONNECT. This is confirmed by the test at src/server.test.ts147-159 which asserts global.fetch was not called when PERPLEXITY_PROXY is set.
• The AbortSignal timeout (controlled by PERPLEXITY_TIMEOUT_MS) is forwarded through proxyAwareFetch regardless of which fetch path is used.

---

URL Format Requirements

Proxy URLs must be well-formed and include the scheme. The README specifies https:// is required, though the underlying undici ProxyAgent also accepts http:// proxies.

Accepted formats:

https://proxy-host:8080
https://username:password@proxy-host:8080
http://proxy-host:3128

Common proxy ports:

Port	Convention
8080	Most common corporate proxy
3128	Squid default
80	HTTP-only proxies

Credentials are embedded in the URL using the standard user:password@host:port format. There is no separate username/password environment variable.

Sources: README.md119-138

---

Example Configurations

Shell (temporary, current session)

Shell (with credentials)

MCP client env block (e.g. Cursor, Claude Desktop)

Docker

Using standard variables instead of PERPLEXITY_PROXY

If your environment already sets HTTPS_PROXY system-wide (common in enterprise Linux environments), the server will automatically pick it up:

Sources: README.md109-138 src/index.test.ts725-784

---

Code Entity Map

The diagram below maps the proxy system's natural-language concepts to the specific code symbols that implement them.

Proxy system: concept-to-code mapping

Sources: src/server.test.ts1-3 src/server.test.ts60-193 src/index.test.ts2

---

Troubleshooting

Symptom	Likely cause	Resolution
Connection timeout to api.perplexity.ai	Proxy required but not configured	Set PERPLEXITY_PROXY
407 Proxy Authentication Required	Proxy requires credentials	Add user:password@ to the proxy URL
Works in shell but not in MCP client	Client doesn't inherit shell env	Add PERPLEXITY_PROXY to the client's env block explicitly
PERPLEXITY_PROXY ignored	Typo or wrong variable name	Verify exact spelling; it is case-sensitive
Proxy set but undici connection fails	Proxy URL scheme wrong	Ensure URL starts with https:// or http://

For timeout-related issues on long sonar-deep-research requests, see also PERPLEXITY_TIMEOUT_MS in Environment Variables Reference. For general connection errors unrelated to proxies, see Troubleshooting.

Sources: README.md170-178