feat: keep upstream proxy credentials out of transcripts (#22, #23) (#24)

* redact credentials from upstream success messages

proxy_set_upstream and proxy_set_host_upstream echoed proxy_url verbatim, writing the upstream password into the MCP client transcript.

* add redactProxyUrl() in utils: replaces the password with ***, keeps scheme, username, host and port so the confirmation stays useful
* username preserved deliberately: for some providers it is configuration rather than a secret (Apify Proxy encodes group, country and session id there)
* splices the original string rather than re-serializing, so an authority-only URL does not gain a trailing slash
* unparseable input returns a placeholder, never the raw value

* take the upstream password from the environment

An authenticated upstream had to carry its password in the tool call, which the
MCP client persists in the transcript.

mergeUpstreamPassword() fills the password slot from
PROXY_MCP_UPSTREAM_PASSWORD when the URL has a username but no password. The
value can only land in the password slot — the field redaction masks — so no
echo-back path exists by construction, and URL serialization percent-encodes
it, so a password containing "@" or "/" cannot re-point the upstream at
another host.

One credential for all upstreams; per-provider secrets can wait for a second
provider. A URL with no username, or one that already carries a password, is
untouched, so existing calls are unaffected.

Redaction also masks query values now, covering a pac+http:// token, and
re-serializes the URL so a password duplicated into the query cannot survive.

* redact upstream credentials in status output

getStatus() returned globalUpstream and hostUpstreams as stored, and both callers serialized them raw: proxy_status (tools/lifecycle.ts) and the proxy://status resource, which clients read unprompted. Status is read far more often than a set-upstream call, so this was the larger writer of credentials into a transcript and left the redaction added earlier only half done.

* redact on the way out inside getStatus(), the one place both callers route through
* the stored configs keep their real credentials; resolveProxyConfig() reads proxyUrl to route, so mutating them would break proxying
* test pins both halves: status carries no raw password, and the stored config still does
* getGlobalUpstream()/getHostUpstreams() intentionally still return raw values; they have no callers today, and a future routing consumer needs the real thing

* document the upstream password env var

The env-sourced password and the redaction behaviour existed only in tool descriptions.

* README upstream section: how to keep the password out of the transcript, what redaction covers, and that the username is deliberately not redacted
* mobile section: cross-reference, since proxy_mobile_setup honours the same variable
* README:601 needed no change; its "process environment is not exposed" claim is scoped to Camoufox launch/list/info responses, which this does not touch

* pin the real limits of upstream password delivery

The round-trip test used a secret containing ":" and asserted losslessness, but it only checked url.parse().auth. socks-proxy-agent@7 then does auth.split(":") and takes [1] (mockttp/node_modules/socks-proxy-agent/dist/index.js:78-81), so "pa:ss" authenticates as "pa" — the test passed while giving false assurance for a socks upstream.

* drop ":" from the lossless-round-trip secret; it holds for everything else
* add a test through the https-proxy-agent path, where ":" is safe
* add a test pinning the socks truncation, so the restriction is visible and the test fails if socks-proxy-agent ever honours the full password
* README: note the socks restriction next to the env var

Not a regression: a literal socks5://user:pa%3Ass@host:1080 truncates identically, with no merge involved.

* drop a needless generic and a non-null assertion

* redactUpstreamConfig: plain function over UpstreamProxyConfig instead of a generic with a conditional return type and two "as never" casts; the null case falls out of && at the call site
* mobile: branch on resolvedUpstream rather than upstream_proxy_url, so the non-null assertion goes away

* respond to review: encode the env password, report which credential was used

1. mergeUpstreamPassword() assigned the env value to url.password raw. That
   setter escapes "@" and "/" but not "%", while mockttp reads the credential
   back through url.parse().auth, which decodeURIComponent()s it — so a
   password of "100%pass" made that decode throw URIError, and "p%20ss"
   silently authenticated as "p ss". encodeURIComponent() first is lossless:
   the setter escapes nothing encodeURIComponent leaves alone. Pinned by a
   round-trip test over "100%pass", "p%20ss" and "%".

2. Omitting the password when the server has no PROXY_MCP_UPSTREAM_PASSWORD
   was a silent no-op reported as success, surfacing later as unexplained 407s.
   The set-upstream responses now carry passwordSource: env | url | none.

3. README: the env var has to be in the spawned server's environment, so the
   'export' example could not work for a stdio server. Replaced with
   'claude mcp add -e' and an .mcp.json "env" block.

* bind the env password to one host, and mask every field that can carry a token

Second review round.

The env-sourced password was merged on "username present, password absent"
alone, so a caller could name any host and have the credential delivered
there — the proxy sends it on the first request, and the transcript shows only
"***". That is the same exfiltration class that got the ${VAR} design
withdrawn, by delivery rather than echo-back, which redaction cannot see. The
merge now also requires PROXY_MCP_UPSTREAM_HOST to match the URL's hostname
(case-insensitive, exact, port-independent), and fails closed when that
variable is unset so a half-configuration cannot become an unbound credential.

redactProxyUrl() masked userinfo and query values but left the path and
fragment verbatim, so a PAC provider carrying its token in the path — the one
scheme the README singles out — had it echoed in full by proxy_set_upstream,
proxy_status and the proxy://status resource. Path segments and the fragment
are now masked for every scheme; an upstream URL's path is never the useful
part of a confirmation message.

A proxy_url the code cannot parse no longer reports success. Redaction had
removed the echo that used to make a typo self-evident, and nothing downstream
validates it either. No scheme allowlist — an unsupported-but-parseable scheme
failing per request is pre-existing and unrelated to these issues.

passwordSource is omitted for a URL with no username, where the question does
not arise, instead of reporting "none" at a correctly unauthenticated
upstream. Username-only auth is a real credential, so "none" stays a success
rather than an error; the README documents that it cannot be expressed at the
pinned host while the password variable is set.

Also: proxy_mobile_setup's field renamed password_source -> passwordSource for
parity with the other two tools, docblocks trimmed where the PR body and README
already carry the rationale, and a stale review-round label dropped from a
test.

* refuse a socks upstream that would truncate the password

Third review round.

socks-proxy-agent splits the credential on the first ":" and keeps only what
follows, so an env password of "pa:ss" authenticated as "pa" — silently. The
README documented it and a test pinned it, but a caveat is thin protection
against a failure that looks like a provider outage. mergeUpstreamPassword()
now throws for a socks* upstream when the password contains ":", naming the
variable and the remedy. The literal-URL form still truncates; nothing can
guard that, and the test says so.

Also: isParseableUrl() replaced by URL.canParse(), available since Node 20 and
the engines floor is >=20; and the README now says PROXY_MCP_UPSTREAM_HOST must
be a bare hostname, since copying the host:port pair out of the proxy URL fails
closed and the fail-closed path cannot explain why.

* drop the query when redacting a proxy URL

Masking query values still echoed a bare token. "?SECRETTOKEN" has no "=", so it parses as a key with an empty value and came back as "?SECRETTOKEN=***" — the token in full, wearing the mask that is supposed to mean it is gone, so nobody would spot it. It reached the set-upstream message, proxy_status and the proxy://status resource.

* drop url.search instead of masking values, matching how the fragment is already handled
* less code than masking keys as well, and nothing in a proxy URL query is worth echoing in a confirmation
* tests cover the bare-token forms, including one mixed with a normal pair

* correct the tool descriptions and match IPv6 upstream hosts

Two gaps between what the code does and what a caller is told.

* the three proxy_url/upstream_proxy_url descriptions still said the password comes from PROXY_MCP_UPSTREAM_PASSWORD alone. Since the host pinning landed, PROXY_MCP_UPSTREAM_HOST must also be set and match, or nothing is merged — an agent reading the old text would expect a merge that silently does not happen. They now state both conditions and mention passwordSource. The README already documented this correctly; the tool descriptions are what an agent actually reads.
* url.hostname keeps the brackets on an IPv6 literal, so a bare "::1" — the form the README documents — never matched and the merge failed closed. Strip brackets from both sides before comparing. A different IPv6 host is still refused.

* stop leaking the upstream password into spawned processes

interceptor_spawn and the camoufox launcher both spread ...process.env into the child. Since this PR puts PROXY_MCP_UPSTREAM_PASSWORD in the server environment, any caller could read it straight back:

  interceptor_spawn { command: "sh", args: ["-c", "env"] }

That defeats the point of the variable — the premise is that the caller cannot see the password, only have it merged into a URL on their behalf. Verified against a running server before and after.

* delete the password from the child environment in terminal.ts and camoufox.ts
* export UPSTREAM_PASSWORD_ENV rather than restating the literal in three places
* PROXY_MCP_UPSTREAM_HOST stays: it is configuration, not a secret, and a spawned tool may legitimately need to know where traffic goes

* refuse a ':' username on every scheme, redact opaque-path URLs

Two ways a credential still slipped through, plus a docblock fix.

* a ":" in the username was guarded only for socks. Basic auth splits the decoded pair at the first colon too (RFC 7617), so "gro:ups" + "s3cret" reaches an http proxy as user "gro", password "ups:s3cret" — the merged password discarded while the response still says passwordSource: env. The guard is now scheme-agnostic. Checking url.parse().auth alone made http look harmless, which is one layer short of what the proxy reads.
* redactProxyUrl left an opaque-path URL untouched: "pac+http:host/TOKEN.pac" has no authority, so assigning pathname is a silent no-op and the token was echoed verbatim. Such a URL is not a usable upstream, so it is reduced to its scheme.
* stripBrackets had been inserted between mergeUpstreamPassword and its docblock, so the 15-line comment documented the helper instead. Moved above.

* fix(upstream): accept '%' usernames, tighten claims, add spawn coverage

Review round 4.

* mergeUpstreamPassword() called decodeURIComponent(url.username), which throws URIError on a bare "%" — "http://100%pass@pinned/" failed with "URI malformed" and no mention of the username. The WHATWG parser always encodes a literal ":" in userinfo as "%3A", so /%3a/i is total and cannot throw. Same failure the password path fixed earlier, reintroduced one field over.
* README overstated the spawn fix: interceptor_spawn runs arbitrary commands as the server user and can read the client config the password lives in, so removing it from the child environment is defence-in-depth, not a boundary. Says so now.
* README claimed exporting in your own shell does not reach the server. CLI clients pass their environment through, so it can; the advice to use the client config stands, the absolute did not.
* mobile: password_source to match its snake_case siblings, and the last non-null assertion is gone.
* dropped a socks paragraph that had been pasted above the username guard, where it does not apply.
* unit coverage for the spawn scrub, per AGENTS.md. Mutation-checked: removing the delete fails it.

* refactor(interceptors): share one spawn-env scrub, document password_source

Review round 5.

* the camoufox scrub was the only behaviour in the diff no test could kill — deleting it left the suite green. terminal.ts and camoufox.ts were building the same child env and repeating the same delete, so both now go through spawnEnv() in utils. One pure function, unit-tested, and removing the scrub now fails three tests instead of none.
* proxy_mobile_setup emits password_source (snake_case, matching its siblings) while the README said passwordSource. Both are now stated, and the mobile tool description mentions the field at all — it was the only one of the three that did not, so an agent had no in-band way to learn the key.
* dropped the CHANGELOG entry and the 3.4.0 bump. src/index.ts hardcodes the server version separately and I had left it at 3.3.2, so the bump would have shipped a server advertising the old version. Choosing minor-vs-patch for someone else s release cadence is the maintainer s call anyway; the precedent commit cited for it was their own.

* test(utils): pin empty-password (user:@host) redaction

#22's acceptance criteria list this case for redactProxyUrl; the behavior
was already correct — the WHATWG parser erases the empty password — but
untested.

---------

Co-authored-by: yfe404 <yfe.github@protonmail.com>

Author: MatousMarik

README.md

@@ -71,6 +71,10 @@ node dist/index.js --transport http --port 3001
 
 `--transport` and `--port` also accept env vars `TRANSPORT` and `PORT`.
 
+`PROXY_MCP_UPSTREAM_PASSWORD` and `PROXY_MCP_UPSTREAM_HOST` keep an upstream
+proxy password out of the transcript — see
+[Keeping the upstream password out of the transcript](#keeping-the-upstream-password-out-of-the-transcript).
+
 ### Manual MCP configuration
 
 The configured server alias controls Claude's generated tool prefix. The examples below use `proxy-mcp`, so Claude Code exposes tools as `mcp__proxy-mcp__<tool_name>`. If you rename the server key to `proxy`, use `mcp__proxy__<tool_name>` instead.
@@ -185,6 +189,122 @@ proxy_set_upstream --proxy_url "socks5://user:pass@upstream.example:1080"
 
 Supported upstream URL schemes: `socks4://`, `socks5://`, `http://`, `https://`, `pac+http://`.
 
+#### Keeping the upstream password out of the transcript
+
+Tool calls and tool results are both persisted by the MCP client. To avoid
+writing an upstream password there on every call, set it in the server's
+environment and pass a URL with a username but no password.
+
+Two variables are required, and both have to be in the environment of the
+**server process**, which the MCP client spawns. Exporting them in the shell you
+launch the client from may reach it — CLI clients pass their own environment
+through — but that depends on the client and is lost the moment the server is
+started any other way. Put them in the client's server config:
+
+| variable | meaning |
+|---|---|
+| `PROXY_MCP_UPSTREAM_PASSWORD` | the password to fill in |
+| `PROXY_MCP_UPSTREAM_HOST` | the only hostname it may be sent to — a bare hostname, no scheme, port or path |
+
+```bash
+claude mcp add proxy-mcp \
+  -e PROXY_MCP_UPSTREAM_PASSWORD=s3cret \
+  -e PROXY_MCP_UPSTREAM_HOST=upstream.example \
+  -- npx -y proxy-mcp@latest
+```
+
+```json
+{
+  "mcpServers": {
+    "proxy-mcp": {
+      "command": "npx",
+      "args": ["-y", "proxy-mcp@latest"],
+      "env": {
+        "PROXY_MCP_UPSTREAM_PASSWORD": "s3cret",
+        "PROXY_MCP_UPSTREAM_HOST": "upstream.example"
+      }
+    }
+  }
+}
+```
+
+Then omit the password from the call:
+
+```bash
+proxy_set_upstream --proxy_url "http://user@upstream.example:1080"
+# routes as http://user:s3cret@upstream.example:1080
+```
+
+**Why the host variable exists.** Without it, a caller who cannot read the
+password could still name any host and have the password delivered there — the
+proxy sends it on the first request, and the transcript would show only `***`.
+The hostname is matched case-insensitively and exactly, with no wildcards; the
+port is not part of the match, so one variable covers a provider offering
+several. A URL naming any other host is left alone. If
+`PROXY_MCP_UPSTREAM_PASSWORD` is set and `PROXY_MCP_UPSTREAM_HOST` is not,
+nothing is merged at all: a half-configuration fails closed rather than
+becoming an unbound credential.
+
+> **This keeps the password out of tool arguments and responses, not out of
+> reach.** `interceptor_spawn` runs an arbitrary command as the server user, so
+> a caller can read the client config file the password is configured in — and
+> on Linux `/proc/<pid>/environ`. The variable removes the routine exposure of
+> writing a credential into every tool call; it is not a sandbox, and anyone who
+> can call `interceptor_spawn` should be treated as able to obtain the password.
+
+The response reports which credential was used — `passwordSource` is `env`,
+`url` or `none`. `proxy_mobile_setup` spells it `password_source`, matching the
+snake_case of the rest of that tool's response. `none` means no password was applied to a URL that names a
+user: either the credential is genuinely username-only, or the server does not
+have both variables set for this host. The field is omitted for a URL with no
+username, where the question does not arise.
+
+Applies to `proxy_set_upstream`, `proxy_set_host_upstream` and
+`proxy_mobile_setup`. A URL that already carries a password is used as-is, so
+existing calls are unaffected. One credential covers all upstreams at the
+pinned host; a URL without a username is left alone.
+
+> **Username-only credentials at the pinned host cannot be expressed.** A URL
+> with a username and no password is exactly the syntax that requests the
+> merge, and `user:@host` cannot signal otherwise — the URL parser erases the
+> empty password before the server sees it. If the pinned host authenticates on
+> the username alone, unset `PROXY_MCP_UPSTREAM_PASSWORD` for that server.
+
+> **`socks*://` upstreams: no `:` in the password.** socks-proxy-agent splits
+> the credential on the first `:` and keeps only what follows, so `pa:ss` would
+> authenticate as `pa`. Rather than deliver half a password silently, a socks
+> upstream is **refused** with an error when `PROXY_MCP_UPSTREAM_PASSWORD`
+> contains `:`. The truncation itself is a toolchain limitation, not something
+> this introduces — a literal `socks5://user:pa%3Ass@host:1080` truncates the
+> same way, and nothing can guard that. `http://`, `https://` and `pac+http://`
+> upstreams take the whole password.
+
+> **A `:` in the *username* is refused on every scheme.** Basic auth splits the
+> decoded pair at the first colon (RFC 7617), and socks-proxy-agent does the
+> same, so a username of `gro:ups` with password `s3cret` reaches the proxy as
+> user `gro`, password `ups:s3cret` — the merged password silently discarded.
+> No scheme can carry it, so the merge refuses rather than guess. Put the whole
+> credential in `proxy_url` instead.
+
+Responses redact credentials — the password in userinfo, with path segments
+masked and the query and fragment dropped, since a `pac+http://` token may live
+in any of those:
+
+```
+Global upstream set to http://user:***@upstream.example:1080/
+Global upstream set to pac+http://pac.example.com/***
+```
+
+`proxy_status` and the `proxy://status` resource are redacted the same way. A
+PAC URL's filename is masked along with the rest of the path, so a confirmation
+message shows the host and nothing else.
+
+**The username is not redacted.** For several providers it is configuration
+rather than a secret — Apify Proxy encodes proxy group, country and
+sticky-session id there — and showing it is what makes the confirmation useful.
+If your provider puts a secret in the username field, do not rely on these
+messages being safe to share.
+
 Typical geo-routing examples:
 
 ```bash
@@ -368,6 +488,10 @@ proxy_mobile_setup \
 
 Applies to BOTH listeners. Use `proxy_set_upstream` after the fact to change it without restarting.
 
+As with `proxy_set_upstream`, omit the password and set
+`PROXY_MCP_UPSTREAM_PASSWORD` and `PROXY_MCP_UPSTREAM_HOST` in the server's
+environment to keep it out of the call.
+
 ### Verifying each step
 
 | Check | Command | Expected |

src/interceptors/camoufox.ts

@@ -30,6 +30,7 @@ import { join } from "node:path";
 import type {
   Interceptor, InterceptorMetadata, ActivateOptions, ActivateResult, ActiveTarget,
 } from "./types.js";
+import { spawnEnv } from "../utils.js";
 
 type CamoufoxOs = "windows" | "macos" | "linux";
 
@@ -189,14 +190,12 @@ export class CamoufoxInterceptor implements Interceptor {
     const scriptPath = join(launcherDir, "launch.py");
     await writeFile(scriptPath, buildLauncherScript(params, wsEndpointFile), "utf-8");
 
+    const childEnv = spawnEnv({ NO_COLOR: "1", PYTHONIOENCODING: "utf-8" });
+
     const proc = spawn(pythonExe, [scriptPath], {
       stdio: ["ignore", "pipe", "pipe"],
       cwd: launcherDir,
-      env: {
-        ...process.env,
-        NO_COLOR: "1",
-        PYTHONIOENCODING: "utf-8",
-      },
+      env: childEnv,
     });
 
     let handshake: WsHandshake;

src/interceptors/terminal.ts

@@ -9,6 +9,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { writeCertTempFile } from "./cert-utils.js";
 import type { Interceptor, InterceptorMetadata, ActivateOptions, ActivateResult, ActiveTarget } from "./types.js";
+import { spawnEnv } from "../utils.js";
 
 const MAX_OUTPUT_BUFFER = 8192;
 
@@ -84,7 +85,7 @@ export class TerminalInterceptor implements Interceptor {
 
     const child = spawn(command, args ?? [], {
       cwd,
-      env: proxyEnv,
+      env: spawnEnv(proxyEnv),
       stdio: ["ignore", "pipe", "pipe"],
       detached: false,
     });

src/state.ts

@@ -13,7 +13,7 @@ import type * as mockttp from "mockttp";
 import type { CompletedRequest, CompletedResponse, ProxyConfig } from "mockttp";
 import { randomUUID } from "node:crypto";
 import { gunzipSync, inflateSync, brotliDecompressSync } from "node:zlib";
-import { serializeHeaders, capString } from "./utils.js";
+import { serializeHeaders, capString, redactProxyUrl } from "./utils.js";
 import { enableServerTlsCapture, type ServerTlsCapture } from "./tls-utils.js";
 import { spoofedRequest, shutdownSpoofContainer, stripHopByHopHeaders } from "./tls-spoof.js";
 import { applyFingerprintHeaderOverrides } from "./spoof-headers.js";
@@ -342,6 +342,11 @@ function rewriteReplayUrl(originalUrl: string, targetBaseUrl?: string): string {
   return new URL(`${original.pathname}${original.search}`, base).toString();
 }
 
+/** Copy an upstream config with its proxy URL redacted, for status output. */
+function redactUpstreamConfig(config: UpstreamProxyConfig): UpstreamProxyConfig {
+  return { ...config, proxyUrl: redactProxyUrl(config.proxyUrl) };
+}
+
 // ── ProxyManager ──
 
 let nextRuleId = 1;
@@ -502,8 +507,12 @@ export class ProxyManager {
       port: this.port,
       url: this.server?.url ?? null,
       certFingerprint: this.cert?.fingerprint ?? null,
-      globalUpstream: this.globalUpstream,
-      hostUpstreams: Object.fromEntries(this.hostUpstreams),
+      // Redacted on the way out only: resolveProxyConfig() reads the stored
+      // proxyUrl to actually route, so those must keep their real credentials.
+      globalUpstream: this.globalUpstream && redactUpstreamConfig(this.globalUpstream),
+      hostUpstreams: Object.fromEntries(
+        [...this.hostUpstreams].map(([host, config]) => [host, redactUpstreamConfig(config)]),
+      ),
       ruleCount: this.rules.size,
       trafficCount: this.traffic.length,
       transparentProxy: this.getTransparentStatus(),

src/tools/mobile.ts

@@ -24,6 +24,7 @@ import { join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { proxyManager } from "../state.js";
 import { interceptorManager } from "../interceptors/manager.js";
+import { mergeUpstreamPassword, upstreamPasswordSource } from "../utils.js";
 
 function errorToString(e: unknown): string {
   if (e instanceof Error) return e.message;
@@ -198,7 +199,7 @@ export function registerMobileTools(server: McpServer): void {
       explicit_port: z.number().optional().default(8080).describe("Port for the explicit HTTP proxy (default: 8080)."),
       transparent_port: z.number().optional().default(8443).describe("Port for the transparent HTTPS listener (default: 8443)."),
       block_quic: z.boolean().optional().default(true).describe("Drop UDP/443 on the AP iface so apps fall back to TCP/TLS (capturable). Default: true."),
-      upstream_proxy_url: z.string().optional().describe("Optional upstream proxy URL (socks5://user:pass@host:port or http://...). Sets the global upstream for BOTH listeners."),
+      upstream_proxy_url: z.string().optional().describe("Optional upstream proxy URL (socks5://user:pass@host:port or http://...). Sets the global upstream for BOTH listeners. If it has a username but no password, the password is filled in from PROXY_MCP_UPSTREAM_PASSWORD, but only when PROXY_MCP_UPSTREAM_HOST is also set and matches this URL's hostname. The response reports password_source: env | url | none."),
       android_serial: z.string().optional().describe("ADB serial of an Android device to inject the CA on. If omitted, no cert injection is attempted."),
       inject_cert: z.boolean().optional().default(true).describe("Inject the CA into the Android device's system store. Ignored if android_serial is omitted."),
     },
@@ -215,6 +216,18 @@ export function registerMobileTools(server: McpServer): void {
       inject_cert,
     }) => {
       try {
+        // Validate and resolve the upstream before starting anything, so a
+        // typo'd URL cannot leave both listeners running behind an error.
+        if (upstream_proxy_url && !URL.canParse(upstream_proxy_url)) {
+          throw new Error("upstream_proxy_url is not a parseable URL — check the scheme, e.g. socks5://host:1080");
+        }
+        let resolvedUpstream: string | undefined;
+        let passwordSource: ReturnType<typeof upstreamPasswordSource> = null;
+        if (upstream_proxy_url) {
+          resolvedUpstream = mergeUpstreamPassword(upstream_proxy_url);
+          passwordSource = upstreamPasswordSource(upstream_proxy_url, resolvedUpstream);
+        }
+
         // 1. Resolve AP iface.
         let apIface = ap_iface;
         let ifaceReason = "user-provided";
@@ -254,8 +267,8 @@ export function registerMobileTools(server: McpServer): void {
 
         // 5. Upstream (optional).
         let upstreamSet = false;
-        if (upstream_proxy_url) {
-          await proxyManager.setGlobalUpstream({ proxyUrl: upstream_proxy_url });
+        if (resolvedUpstream) {
+          await proxyManager.setGlobalUpstream({ proxyUrl: resolvedUpstream });
           upstreamSet = true;
         }
 
@@ -306,6 +319,7 @@ export function registerMobileTools(server: McpServer): void {
               transparent_port: transparentPortUsed,
               block_quic,
               upstream_set: upstreamSet,
+              ...(passwordSource ? { password_source: passwordSource } : {}),
               cert_injected: certInjected,
               android_target_id: androidTargetId,
               sudo_script: scriptPath,

src/tools/upstream.ts

@@ -5,24 +5,46 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { proxyManager } from "../state.js";
+import { mergeUpstreamPassword, redactProxyUrl, upstreamPasswordSource } from "../utils.js";
+
+/**
+ * A proxy_url the code cannot parse must not report success: redaction removed
+ * the echo that used to make a typo self-evident, and nothing downstream
+ * validates it either. The value is not repeated back — it may hold a password.
+ */
+function unparseable() {
+  return {
+    content: [{
+      type: "text" as const,
+      text: JSON.stringify({
+        status: "error",
+        error: "proxy_url is not a parseable URL — check the scheme, e.g. socks5://host:1080",
+      }),
+    }],
+  };
+}
 
 export function registerUpstreamTools(server: McpServer): void {
   server.tool(
     "proxy_set_upstream",
     "Set a global upstream proxy for all outgoing traffic. Supports socks4://, socks5://, http://, https://, and pac+http:// URLs.",
     {
-      proxy_url: z.string().describe("Upstream proxy URL (e.g., socks5://user:pass@host:port)"),
+      proxy_url: z.string().describe("Upstream proxy URL (e.g., socks5://user:pass@host:port). If the URL has a username but no password, and the server has both PROXY_MCP_UPSTREAM_PASSWORD and PROXY_MCP_UPSTREAM_HOST set with the host matching this URL's hostname, the password is filled in from the environment so it need not appear in this call. Otherwise the URL is used as given; the response reports passwordSource: env | url | none."),
       no_proxy: z.array(z.string()).optional().describe("Hostnames to bypass the upstream proxy"),
     },
     async ({ proxy_url, no_proxy }) => {
       try {
-        await proxyManager.setGlobalUpstream({ proxyUrl: proxy_url, noProxy: no_proxy });
+        if (!URL.canParse(proxy_url)) return unparseable();
+        const resolved = mergeUpstreamPassword(proxy_url);
+        const passwordSource = upstreamPasswordSource(proxy_url, resolved);
+        await proxyManager.setGlobalUpstream({ proxyUrl: resolved, noProxy: no_proxy });
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
               status: "success",
-              message: `Global upstream set to ${proxy_url}`,
+              message: `Global upstream set to ${redactProxyUrl(resolved)}`,
+              ...(passwordSource ? { passwordSource } : {}),
               noProxy: no_proxy || [],
             }),
           }],
@@ -57,18 +79,22 @@ export function registerUpstreamTools(server: McpServer): void {
     "Set a per-host upstream proxy override. Traffic to this hostname will use the specified proxy instead of the global one.",
     {
       hostname: z.string().describe("Hostname to override (e.g., api.example.com)"),
-      proxy_url: z.string().describe("Upstream proxy URL for this host"),
+      proxy_url: z.string().describe("Upstream proxy URL for this host. If it has a username but no password, the password is filled in from PROXY_MCP_UPSTREAM_PASSWORD, but only when PROXY_MCP_UPSTREAM_HOST is also set and matches this URL's hostname. The response reports passwordSource: env | url | none."),
       no_proxy: z.array(z.string()).optional().describe("Hostnames to bypass this proxy"),
     },
     async ({ hostname, proxy_url, no_proxy }) => {
       try {
-        await proxyManager.setHostUpstream(hostname, { proxyUrl: proxy_url, noProxy: no_proxy });
+        if (!URL.canParse(proxy_url)) return unparseable();
+        const resolved = mergeUpstreamPassword(proxy_url);
+        const passwordSource = upstreamPasswordSource(proxy_url, resolved);
+        await proxyManager.setHostUpstream(hostname, { proxyUrl: resolved, noProxy: no_proxy });
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
               status: "success",
-              message: `Upstream for '${hostname}' set to ${proxy_url}`,
+              message: `Upstream for '${hostname}' set to ${redactProxyUrl(resolved)}`,
+              ...(passwordSource ? { passwordSource } : {}),
             }),
           }],
         };