fix: stop routing all traffic through EnvHttpProxyAgent by default (#359)

* chore(deps): bump undici to 7.x

Our engines field requires Node >=20.20.0, which already satisfies undici
7.x (>=20.18.1). The 6.x pin was over-conservative — the original pin
message referenced Node 18 support, but we don't actually support 18.

8.x would require Node >=22.19.0, which would exclude Node 20 users.

* fix(proxy): only install EnvHttpProxyAgent when proxy env vars are set

PR #338 set EnvHttpProxyAgent as the default dispatcher unconditionally
so that Node's fetch (which ignores HTTP_PROXY/HTTPS_PROXY/NO_PROXY by
default) would pick up standard proxy env vars for managed-network users.

The tradeoff: we also took over the HTTP stack for every user, including
those whose shell has a stale or incidental proxy var (from a VPN client,
old dev setup, or inherited env) that wasn't meant to apply to Figma API
traffic. Those users silently routed through an intermediary that returned
403, and our error message still blamed Figma (issue #358).

Gate the swap on at least one of HTTP_PROXY/HTTPS_PROXY/NO_PROXY being
set. Corporate users get the zero-config behavior they had before; users
with no proxy vars keep Node's native dispatcher untouched.

* fix(fetch): attach truncated response body to HTTP errors

Throwing \`Fetch failed with status 403\` and discarding the body makes
it impossible to tell a real Figma 403 from a proxy/intermediary 403.
Read up to 500 chars of the body, collapse whitespace, and attach it
to both the error message and the \`responseBody\` property on HttpError.

Callers can pass \`redactFromErrorBody\` to scrub secrets from the body
before it's exposed — defense in depth against chatty intermediaries
that sometimes mirror request metadata into error pages.

FigmaService passes its API key and OAuth token through this channel
so they're scrubbed even in the unlikely case a proxy echoes them back.

* fix(figma): include response body in 403 error message

The canned \"Figma API returned 403 Forbidden\" message lied when the 403
actually came from an HTTP intermediary (proxy, firewall, VPN) rather
than Figma itself. Surface the response body so the LLM and user can see
what actually rejected the request, and add the intermediary case to the
list of common causes.

* feat(telemetry): add proxy_env_set common property

PR #338 made proxy configuration load-bearing for every user's HTTP
stack. Without a telemetry dimension for proxy-env presence we can't
answer "do auth-category 403s correlate with proxy env vars" empirically
across the user base — we can only respond to individual tickets.

Add \`proxy_env_set\` to the common properties attached to every PostHog
event. Boolean, so no proxy URL is logged. Shared helper in
\`src/utils/proxy-env.ts\` so server.ts (dispatcher gating) and
telemetry/client.ts (reporting) agree on the definition.

* feat(telemetry): replace proxy_env_set with proxy_mode, surface bypass hint on 403

\`proxy_mode: none | explicit | env\` distinguishes --proxy/FIGMA_PROXY
from env-derived proxies, which the boolean couldn't. Lets us correlate
#358-style failures with the specific configuration that produced them.

When a 403 surfaces and a proxy is configured, the error now hints at
the right bypass: unset --proxy for explicit mode, or set
NO_PROXY=api.figma.com for env mode. Users already have NO_PROXY as a
standard escape hatch (EnvHttpProxyAgent respects it) — no new flag.

* feat(proxy): support --proxy=none to bypass env-var proxies

Users with a system-level HTTPS_PROXY that misbehaves for api.figma.com
specifically couldn't easily opt out via the CLI — NO_PROXY worked but
required knowing the convention and the right hostname. Accept 'none' as
a special value for --proxy (also via FIGMA_PROXY) to explicitly skip
both ProxyAgent and EnvHttpProxyAgent, leaving Node's default dispatcher
in place regardless of what's in the environment.

No new flag surface; reuses the existing knob.

* chore: code cleanup pass + follow-ups

Incorporates an automated cleanup pass across the proxy/dispatcher code,
plus two manual follow-ups on top:

- server.ts: consolidate proxy branches, unify commentary, drop the
  emitWarning suppression (undici 7.x no longer emits UNDICI-EHPA).
- fetch-json.ts: push optional-handling for redactFromErrorBody to the
  boundary (destructure default + filter(Boolean)), tighten signatures.
- proxy-env.ts: reorder (type first), extract PROXY_ENV_VARS constant.
  Restored a short note on hasProxyEnv so future readers know it's
  shared across three files and shouldn't be re-inlined.
- figma.ts: split ternary into explicit per-mode branches, add rationale
  JSDoc on buildForbiddenMessage. Aligned HttpError cast style between
  buildForbiddenMessage and buildRateLimitMessage — both now use
  (error as HttpError).field ?? fallback with no optional chain, safe
  because both only run from the requestWithSize catch block.

Author: GLips

package.json

@@ -64,7 +64,7 @@
     "js-yaml": "^4.1.1",
     "posthog-node": "^5.29.2",
     "remeda": "^2.20.1",
-    "undici": "^6.24.1",
+    "undici": "^7.25.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -44,7 +44,8 @@ const argv = cli({
     },
     proxy: {
       type: String,
-      description: "HTTP proxy URL for networks that require a proxy (e.g. http://proxy:8080)",
+      description:
+        "HTTP proxy URL for networks that require a proxy (e.g. http://proxy:8080). Pass 'none' to ignore HTTP_PROXY/HTTPS_PROXY from the environment and connect directly.",
     },
     stdio: {
       type: Boolean,

src/bin.ts

@@ -5,6 +5,7 @@ import { Server } from "http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ProxyAgent, EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
 import { Logger } from "./utils/logger.js";
+import { hasProxyEnv, setProxyMode } from "./utils/proxy-env.js";
 import { createServer } from "./mcp/index.js";
 import type { ServerConfig } from "./config.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -23,17 +24,21 @@ const activeConnections = new Set<ActiveConnection>();
  * Start the MCP server in either stdio or HTTP mode.
  */
 export async function startServer(config: ServerConfig): Promise<void> {
-  if (config.proxy) {
+  // Three outcomes: explicit proxy URL → ProxyAgent; no proxy but env vars set
+  // → EnvHttpProxyAgent; otherwise Node's default (includes `--proxy=none`,
+  // which lets users opt out of system-level proxy vars misbehaving for
+  // api.figma.com — see issue #358).
+  //
+  // We deliberately do NOT install EnvHttpProxyAgent when no proxy vars are
+  // present, so a stale or incidental var in the user's shell (VPN client,
+  // old dev setup) can't silently route Figma traffic through an intermediary
+  // that may return 403.
+  if (config.proxy && config.proxy !== "none") {
     setGlobalDispatcher(new ProxyAgent(config.proxy));
-  } else {
-    // EnvHttpProxyAgent automatically respects HTTP_PROXY/HTTPS_PROXY/NO_PROXY
-    // env vars when present, and falls through to direct connections when absent.
-    // Suppress the UNDICI-EHPA experimental warning — the API is stable
-    // enough for our use case and the warning is noise for end users.
-    const { emitWarning } = process;
-    process.emitWarning = () => {};
+    setProxyMode("explicit");
+  } else if (!config.proxy && hasProxyEnv()) {
     setGlobalDispatcher(new EnvHttpProxyAgent());
-    process.emitWarning = emitWarning;
+    setProxyMode("env");
   }
 
   const telemetryEnabled = telemetry.initTelemetry({

src/server.ts

@@ -9,6 +9,7 @@ import { downloadAndProcessImage, type ImageProcessingResult } from "~/utils/ima
 import { Logger, writeLogs } from "~/utils/logger.js";
 import { fetchJSON } from "~/utils/fetch-json.js";
 import { getErrorMeta } from "~/utils/error-meta.js";
+import { proxyMode } from "~/utils/proxy-env.js";
 import type { HttpError } from "~/utils/fetch-json.js";
 
 export type FigmaAuthOptions = {
@@ -76,14 +77,15 @@ export class FigmaService {
 
       return await fetchJSON<T & { status?: number }>(`${this.baseUrl}${endpoint}`, {
         headers,
+        redactFromErrorBody: [this.apiKey, this.oauthToken],
       });
     } catch (error) {
       const meta = getErrorMeta(error);
       if (meta.http_status === 429) {
         throw new Error(buildRateLimitMessage(error), { cause: error });
       }
       if (meta.http_status === 403) {
-        throw new Error(buildForbiddenMessage(endpoint), { cause: error });
+        throw new Error(buildForbiddenMessage(endpoint, error), { cause: error });
       }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(
@@ -336,26 +338,48 @@ export class FigmaService {
 }
 
 /**
- * Build a user-facing 429 message from the Figma rate-limit response headers.
- * Figma includes plan tier, seat-level limit type, retry-after, and an upgrade
- * link — all of which let us give targeted guidance instead of a generic
- * "try again later."
- *
- * See https://developers.figma.com/docs/rest-api/rate-limits/
+ * Build a user-facing 403 message. Includes the raw response body (redacted +
+ * truncated by fetchJSON) because corporate proxies/firewalls frequently
+ * reject requests with their own 403 HTML before they ever reach Figma, and
+ * that body is the fastest way for a user to recognize "oh, this is Zscaler."
  */
-function buildForbiddenMessage(endpoint: string): string {
-  return [
-    `Figma API returned 403 Forbidden for '${endpoint}'.`,
-    "This usually means one of:",
+function buildForbiddenMessage(endpoint: string, error: unknown): string {
+  const body = (error as HttpError).responseBody;
+  const parts = [`Request to Figma API endpoint '${endpoint}' returned 403 Forbidden.`];
+  if (body) parts.push(`Response body: ${body}`);
+  parts.push(
+    "This is typically one of:",
     "- The access token doesn't have permission to this file (it must be owned by or explicitly shared with the token's account)",
     "- The file's share settings don't allow viewers to copy/share/export",
     "- For team/org files, the API token may not have access to that team",
+    "- An HTTP intermediary (corporate proxy, firewall, VPN) rejected the request before it reached Figma — check the response body above for clues",
     "Troubleshooting guide: https://www.framelink.ai/docs/troubleshooting#cannot-access-file",
-  ].join("\n");
+  );
+  const mode = proxyMode();
+  if (mode === "explicit") {
+    parts.push(
+      "",
+      "Note: this server is configured to route requests through an explicit proxy (--proxy/FIGMA_PROXY). If the proxy may be the source of the 403, unset it, change it to --proxy=none, or bypass it for this host.",
+    );
+  } else if (mode === "env") {
+    parts.push(
+      "",
+      "Note: this server picked up a proxy from HTTP_PROXY/HTTPS_PROXY in your environment. If the proxy may be the source of the 403, set NO_PROXY=api.figma.com, pass --proxy=none, or unset HTTP_PROXY/HTTPS_PROXY.",
+    );
+  }
+  return parts.join("\n");
 }
 
+/**
+ * Build a user-facing 429 message from the Figma rate-limit response headers.
+ * Figma includes plan tier, seat-level limit type, retry-after, and an upgrade
+ * link — all of which let us give targeted guidance instead of a generic
+ * "try again later."
+ *
+ * See https://developers.figma.com/docs/rest-api/rate-limits/
+ */
 function buildRateLimitMessage(error: unknown): string {
-  const headers = (error as HttpError)?.responseHeaders ?? {};
+  const headers = (error as HttpError).responseHeaders ?? {};
   const retryAfter = headers["retry-after"];
   const planTier = headers["x-figma-plan-tier"];
   const limitType = headers["x-figma-rate-limit-type"];

src/services/figma.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { PostHog } from "posthog-node";
+import { proxyMode, type ProxyMode } from "~/utils/proxy-env.js";
 import type { InitTelemetryOptions } from "./types.js";
 
 // Write-only project key for the Framelink MCP analytics project.
@@ -13,6 +14,16 @@ type CommonProperties = {
   os_platform: NodeJS.Platform;
   nodejs_major: number;
   is_ci: boolean;
+  /**
+   * Which dispatcher the server installed for outbound fetches:
+   * `none` (Node default), `explicit` (--proxy/FIGMA_PROXY), or `env`
+   * (EnvHttpProxyAgent driven by HTTP_PROXY/HTTPS_PROXY/NO_PROXY).
+   *
+   * Lets us correlate failure rates (especially auth-category 403s — see
+   * issue #358) with the proxy configuration a user was actually running
+   * under, without logging the proxy URL itself.
+   */
+  proxy_mode: ProxyMode;
 };
 
 let client: PostHog | undefined;
@@ -72,6 +83,7 @@ export function initTelemetry(opts?: InitTelemetryOptions): boolean {
     os_platform: process.platform,
     nodejs_major: parseNodeMajor(process.versions.node),
     is_ci: Boolean(process.env.CI),
+    proxy_mode: proxyMode(),
   };
 
   // disableGeoip: false is load-bearing — the Node SDK defaults GeoIP to off,

src/telemetry/client.ts

@@ -7,14 +7,25 @@ type RequestOptions = RequestInit & {
    * Avoids complexity of needing to deal with `instanceof Headers`, which is not supported in some environments.
    */
   headers?: Record<string, string>;
+  /**
+   * Secrets to scrub from the response body attached to thrown HTTP errors.
+   * Defense in depth: api.figma.com never echoes credentials, but HTTP
+   * intermediaries (corporate proxies, MITM filters) sometimes mirror
+   * request metadata into error pages.
+   */
+  redactFromErrorBody?: string[];
 };
 
 /**
  * Error thrown on HTTP failures. Carries response headers so callers (e.g.
  * figma.ts) can read rate-limit metadata without needing access to the
- * original Response object.
+ * original Response object, plus the (possibly-truncated, redacted) response
+ * body so callers can distinguish Figma errors from proxy/intermediary errors.
  */
-export type HttpError = Error & { responseHeaders?: Record<string, string> };
+export type HttpError = Error & {
+  responseHeaders?: Record<string, string>;
+  responseBody?: string;
+};
 
 const CONNECTION_ERROR_CODES = new Set([
   "ECONNRESET",
@@ -28,21 +39,30 @@ const CONNECTION_ERROR_CODES = new Set([
 // server-side failures. 4xx other than 429 are caller errors and not retryable.
 const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
 
+// Cap the attached error body. Corp-firewall HTML blocks can be 50KB+;
+// we only need enough to identify the origin ("Blocked by Zscaler", etc.).
+const MAX_ERROR_BODY_CHARS = 500;
+
 export async function fetchJSON<T extends { status?: number }>(
   url: string,
   options: RequestOptions = {},
 ): Promise<{ data: T; rawSize: number }> {
+  const { redactFromErrorBody = [], ...fetchOptions } = options;
   try {
-    const response = await fetch(url, options);
+    const response = await fetch(url, fetchOptions);
 
     if (!response.ok) {
       const responseHeaders: Record<string, string> = {};
       response.headers.forEach((value, key) => {
         responseHeaders[key] = value;
       });
+      const responseBody = await readErrorBody(response, redactFromErrorBody.filter(Boolean));
+      const bodySuffix = responseBody ? `\nResponse body: ${responseBody}` : "";
       const httpError: HttpError = Object.assign(
-        new Error(`Fetch failed with status ${response.status}: ${response.statusText}`),
-        { responseHeaders },
+        new Error(
+          `Fetch failed with status ${response.status}: ${response.statusText}${bodySuffix}`,
+        ),
+        { responseHeaders, responseBody },
       );
       tagError(httpError, {
         http_status: response.status,
@@ -85,3 +105,29 @@ function httpStatusCategory(status: number): ErrorCategory {
   if (status === 401 || status === 403) return "auth";
   return "figma_api";
 }
+
+async function readErrorBody(
+  response: Response,
+  redactSecrets: string[],
+): Promise<string | undefined> {
+  // Body read can fail if the connection is killed mid-response; we'd rather
+  // surface the status/headers we already have than mask it with a body-read
+  // error.
+  let text: string;
+  try {
+    text = await response.text();
+  } catch {
+    return undefined;
+  }
+  if (!text) return undefined;
+
+  // Collapse whitespace so HTML error pages read as one line in error messages.
+  let result = text.replace(/\s+/g, " ").trim();
+  for (const secret of redactSecrets) {
+    result = result.replaceAll(secret, "[REDACTED]");
+  }
+  if (result.length > MAX_ERROR_BODY_CHARS) {
+    result = result.slice(0, MAX_ERROR_BODY_CHARS) + "… [truncated]";
+  }
+  return result;
+}

src/utils/fetch-json.ts

@@ -0,0 +1,28 @@
+/**
+ * Which dispatcher is installed on the global fetch. `env` means
+ * EnvHttpProxyAgent is routing, but a specific request may still go direct
+ * when NO_PROXY matches — treat this as configuration state, not as
+ * "was this request proxied."
+ */
+export type ProxyMode = "none" | "explicit" | "env";
+
+const PROXY_ENV_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY"];
+
+/**
+ * Whether the host environment has any HTTP proxy var set (case-insensitive).
+ * Shared so server.ts, telemetry/client.ts, and figma.ts agree on what counts
+ * as "proxy env" — don't inline this check.
+ */
+export function hasProxyEnv(): boolean {
+  return PROXY_ENV_VARS.some((n) => process.env[n] || process.env[n.toLowerCase()]);
+}
+
+let currentMode: ProxyMode = "none";
+
+export function setProxyMode(mode: ProxyMode): void {
+  currentMode = mode;
+}
+
+export function proxyMode(): ProxyMode {
+  return currentMode;
+}