@yagni-app/code-staging 1.0.5-staging.1239.1 → 1.0.5-staging.1241.1

package/dist/cli.js

@@ -516,6 +516,10 @@ export const HELP_TEXT = [
     "  yagni connect claude-code  Route Claude Code through the YAGNI model proxy",
     "                           (--project scopes to this repo; --off disconnects).",
     "  yagni connect codex      Route Codex CLI through the YAGNI model proxy.",
+    "  yagni mcp <subcommand>    Manage MCP servers: add, remove, list, get,",
+    "                           add-from-claude, and more — run `yagni mcp` for",
+    "                           details. OAuth servers authenticate via the",
+    "                           /mcp panel in a session.",
     "  yagni token              Output the active environment's API token (for helpers).",
     "  yagni use <name>         Switch the active environment (sticky).",
     "                           Presets: prod, local. Others need --base-url <url>.",
@@ -537,6 +541,7 @@ export const HELP_TEXT = [
     "  /mode plan|review|auto   Hold writes for planning, or confirm each change.",
     "  /todos                   Show the agent's live task list.",
     "  /cost                    Session usage and credit headroom.",
+    "  /mcp                     Manage MCP servers; authenticate OAuth servers.",
     "",
     "The active environment is sticky; `use` switches it (prod is the default).",
     "Set YAGNI_BASE_URL to override the base URL for a single run.",

package/dist/extension/mcp/auth.d.ts

@@ -91,6 +91,7 @@ export declare class YagniAuthProvider implements OAuthClientProvider {
 export declare function authenticate(serverName: string, config: McpHttpServerConfig, deps?: AuthDeps, opts?: {
     signal?: AbortSignal;
     timeoutMs?: number;
+    serverUrl?: string;
 }): Promise<OAuthResult>;
 /** Find a free loopback port (OS-assigned). */
 export declare function findFreePort(): Promise<number>;

package/dist/extension/mcp/auth.js

@@ -21,10 +21,12 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 import { auth as sdkAuth, discoverOAuthServerInfo } from "@modelcontextprotocol/sdk/client/auth.js";
+import { expandServerEnv } from "./config.js";
 import { runningUnderTest } from "../crashReport.js";
 import { getStoredOAuthEntry, updateStoredOAuthEntry } from "./authStore.js";
 import { deleteStoredOAuthEntry as clearStoredOAuthEntry } from "./authStore.js";
 import { logMcpEvent, redactSensitiveUrlParams } from "./log.js";
+import { renderAuthErrorPage, renderAuthStateMismatchPage, renderAuthSuccessPage, } from "./callbackPage.js";
 /** Cancellation via an AbortSignal (Ctrl-C / Esc in the /mcp panel). */
 export class AuthenticationCancelledError extends Error {
     constructor(message = "OAuth cancelled") {
@@ -269,6 +271,10 @@ function traceOutcomeFromError(err) {
 export async function authenticate(serverName, config, deps = {}, opts = {}) {
     const openUrl = deps.openUrl ?? defaultOpenUrl;
     const timeoutMs = opts.timeoutMs ?? OAuthFlowTimeoutMs;
+    // Discovery and the token exchange go to the ${VAR}-expanded URL when the
+    // caller provides one; the provider below keeps the RAW config so the
+    // auth-store key (sha256 of type+url+headers) is stable across env changes.
+    const serverUrl = opts.serverUrl ?? config.url;
     // Bind the loopback port FIRST so redirect_uri and the listener agree.
     const fixedPort = config.oauth?.callbackPort;
     const port = fixedPort ?? (await findFreePort());
@@ -280,7 +286,7 @@ export async function authenticate(serverName, config, deps = {}, opts = {}) {
     // command handler hostage.
     let first;
     try {
-        first = await sdkAuthPhase("discovery", provider, { serverUrl: config.url }, { signal: opts.signal, timeoutMs });
+        first = await sdkAuthPhase("discovery", provider, { serverUrl }, { signal: opts.signal, timeoutMs });
     }
     catch (err) {
         if (err instanceof AuthenticationCancelledError)
@@ -327,7 +333,7 @@ export async function authenticate(serverName, config, deps = {}, opts = {}) {
     // Bounded like discovery: a hung token endpoint must fail, not wedge.
     let result;
     try {
-        result = await sdkAuthPhase("token exchange", provider, { serverUrl: config.url, authorizationCode: code }, { signal: opts.signal, timeoutMs });
+        result = await sdkAuthPhase("token exchange", provider, { serverUrl, authorizationCode: code }, { signal: opts.signal, timeoutMs });
     }
     catch (err) {
         if (err instanceof AuthenticationCancelledError)
@@ -424,20 +430,23 @@ function waitForCode(port, expectedState, opts = {}) {
                 // The provider-controlled values are HTML-escaped: any local process
                 // can hit the loopback with a crafted ?error=<script> payload, and the
                 // page must never reflect it (same spot Claude Code sanitizes).
-                res.end(`<h1>Authentication Error</h1><p>${escapeHtml(error)}${errorDescription ? `: ${escapeHtml(errorDescription)}` : ""}</p><p>You can close this window.</p>`);
+                res.end(renderAuthErrorPage({
+                    error: escapeHtml(error),
+                    errorDescription: errorDescription ? escapeHtml(errorDescription) : undefined,
+                }));
                 finish(undefined);
                 return;
             }
             if (state !== expectedState) {
                 onEvent?.("oauth_callback_state_mismatch", {});
                 res.writeHead(400, { "Content-Type": "text/html" });
-                res.end("<h1>Authentication Error</h1><p>Invalid state parameter. Please try again.</p>");
+                res.end(renderAuthStateMismatchPage());
                 fail(new Error("OAuth state mismatch - possible CSRF attack"));
                 return;
             }
             onEvent?.("oauth_callback_code", {});
             res.writeHead(200, { "Content-Type": "text/html" });
-            res.end("<h1>Authentication Successful</h1><p>You can close this window and return to YAGNI Code.</p>");
+            res.end(renderAuthSuccessPage());
             finish(code);
         });
         server.on("error", () => {
@@ -528,7 +537,11 @@ async function defaultOpenUrl(url) {
  */
 export async function revokeTokensOnRemove(serverName, config, deps = {}) {
     try {
-        const info = await discoverOAuthServerInfo(config.url, { fetchFn: deps.fetch });
+        // Discovery needs the resolvable (${VAR}-expanded) URL; store operations
+        // below key off the raw config. Best-effort: an unresolvable var leaves
+        // the raw URL, discovery fails, and the local entry is still cleared.
+        const discoveryUrl = expandServerEnv(config).config.url;
+        const info = await discoverOAuthServerInfo(discoveryUrl, { fetchFn: deps.fetch });
         const metadata = info.authorizationServerMetadata;
         const entry = getStoredOAuthEntry(serverName, config);
         if (metadata && entry?.clientId) {

package/dist/extension/mcp/callbackPage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The loopback OAuth callback page — the only surface a user ever sees served
+ * from the local `127.0.0.1:<port>/callback` listener. Rendered with the same
+ * Glass & Print language as the app: tinted blue field, floating glass card,
+ * one blue accent, three type voices (Instrument Sans interface / Newsreader
+ * authored / IBM Plex Mono fact).
+ *
+ * Self-contained: no external assets, fonts, or network calls — the page must
+ * render offline and never phone home. Tokens are inlined from
+ * packages/frontend/src/styles/tokens.css so this module can't drift a runtime
+ * dependency on the frontend build; token names are kept in comments so a
+ * re-derivation stays mechanical.
+ *
+ * `escapeHtml` is applied by the caller to every provider-controlled value
+ * before interpolation (a local process can hit the loopback with a crafted
+ * ?error=<script> payload — the page never reflects raw input).
+ */
+/** The success page shown after the provider redirects back with a code. */
+export declare function renderAuthSuccessPage(): string;
+/**
+ * The error page shown when the provider bounces the flow. `error` and
+ * `errorDescription` are provider-controlled and already HTML-escaped by the
+ * caller.
+ */
+export declare function renderAuthErrorPage(opts: {
+    error?: string;
+    errorDescription?: string;
+}): string;
+/** The state-mismatch page — a hard failure, shown before the flow aborts. */
+export declare function renderAuthStateMismatchPage(): string;
+//# sourceMappingURL=callbackPage.d.ts.map

package/dist/extension/mcp/callbackPage.js

@@ -0,0 +1,222 @@
+/**
+ * The loopback OAuth callback page — the only surface a user ever sees served
+ * from the local `127.0.0.1:<port>/callback` listener. Rendered with the same
+ * Glass & Print language as the app: tinted blue field, floating glass card,
+ * one blue accent, three type voices (Instrument Sans interface / Newsreader
+ * authored / IBM Plex Mono fact).
+ *
+ * Self-contained: no external assets, fonts, or network calls — the page must
+ * render offline and never phone home. Tokens are inlined from
+ * packages/frontend/src/styles/tokens.css so this module can't drift a runtime
+ * dependency on the frontend build; token names are kept in comments so a
+ * re-derivation stays mechanical.
+ *
+ * `escapeHtml` is applied by the caller to every provider-controlled value
+ * before interpolation (a local process can hit the loopback with a crafted
+ * ?error=<script> payload — the page never reflects raw input).
+ */
+const CSS = `
+  :root {
+    /* tokens.css — field, ink, accent, materials */
+    --field-base: #f4f6fc;
+    --field-tint-blue: #dfe8ff;
+    --field-tint-violet: #e8e4ff;
+    --field-tint-cyan: #e3f0f6;
+    --ink: #23252e;
+    --ink-strong: #181a22;
+    --text-secondary: #565b72;
+    --text-quiet: #8b90a5;
+    --text-label: #7b8098;
+    --accent: #2f56d3;
+    --accent-muted: rgba(47, 86, 211, 0.12);
+    --accent-border: rgba(47, 86, 211, 0.3);
+    --error: #b4452f;
+    --error-muted: rgba(180, 69, 47, 0.07);
+    --glass-bg: rgba(255, 255, 255, 0.55);
+    --glass-border: rgba(255, 255, 255, 0.85);
+    --glass-blur: 18px;
+    --radius-pane: 16px;
+    --shadow-staged: 0 1px 2px rgba(24, 34, 64, 0.07), 0 18px 40px -30px rgba(38, 52, 110, 0.35);
+    --shadow-staged-high: 0 1px 2px rgba(24, 34, 64, 0.08), 0 28px 60px -28px rgba(38, 52, 110, 0.42);
+    --body: "Instrument Sans Variable", "Instrument Sans", system-ui, sans-serif;
+    --prose: "Newsreader", ui-serif, Georgia, serif;
+    --mono: "IBM Plex Mono", ui-monospace, monospace;
+  }
+
+  * { box-sizing: border-box; }
+
+  html, body { height: 100%; }
+
+  body {
+    margin: 0;
+    min-height: 100%;
+    display: grid;
+    place-items: center;
+    padding: 24px;
+    font-family: var(--body);
+    color: var(--ink);
+    background:
+      radial-gradient(1200px 700px at 8% -5%, var(--field-tint-blue) 0, rgba(223, 232, 255, 0) 60%),
+      radial-gradient(900px 600px at 95% 0%, var(--field-tint-violet) 0, rgba(232, 228, 255, 0) 55%),
+      radial-gradient(900px 700px at 60% 100%, var(--field-tint-cyan) 0, rgba(227, 240, 246, 0) 60%),
+      var(--field-base);
+  }
+
+  .card {
+    width: 100%;
+    max-width: 400px;
+    text-align: center;
+    padding: 40px 32px 32px;
+    background: var(--glass-bg);
+    -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(1.15);
+    backdrop-filter: blur(var(--glass-blur)) saturate(1.15);
+    border: 1px solid var(--glass-border);
+    border-radius: var(--radius-pane);
+    box-shadow: var(--shadow-staged-high);
+    animation: rise 420ms cubic-bezier(0.22, 1, 0.36, 1) both;
+  }
+
+  @keyframes rise {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: none; }
+  }
+
+  .wordmark {
+    font-family: var(--mono);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: var(--text-label);
+    margin: 0 0 28px;
+  }
+
+  .badge {
+    width: 52px;
+    height: 52px;
+    margin: 0 auto 20px;
+    display: grid;
+    place-items: center;
+    border-radius: 14px;
+    background: var(--accent-muted);
+    border: 1px solid var(--accent-border);
+    color: var(--accent);
+  }
+
+  .card--error .badge {
+    background: var(--error-muted);
+    border-color: rgba(180, 69, 47, 0.28);
+    color: var(--error);
+  }
+
+  h1 {
+    font-family: var(--prose);
+    font-size: 30px;
+    font-weight: 600;
+    line-height: 1.15;
+    letter-spacing: -0.01em;
+    color: var(--ink-strong);
+    margin: 0 0 10px;
+  }
+
+  .lede {
+    font-size: 14px;
+    line-height: 1.55;
+    color: var(--text-secondary);
+    margin: 0 0 24px;
+  }
+
+  .detail {
+    font-family: var(--mono);
+    font-size: 12px;
+    line-height: 1.5;
+    color: var(--error);
+    background: var(--error-muted);
+    border: 1px solid rgba(180, 69, 47, 0.2);
+    border-radius: 8px;
+    padding: 8px 10px;
+    margin: 0 0 24px;
+    word-break: break-word;
+  }
+
+  .divider {
+    height: 1px;
+    margin: 0 0 20px;
+    background: linear-gradient(90deg, transparent, var(--accent-border), transparent);
+  }
+
+  .hint {
+    font-size: 12.5px;
+    color: var(--text-quiet);
+    margin: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .card { animation: none; }
+  }
+`;
+const CHECK_ICON = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg>`;
+const ERROR_ICON = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="9"/><line x1="12" y1="8" x2="12" y2="13"/><line x1="12" y1="16.5" x2="12.01" y2="16.5"/></svg>`;
+function shell(opts) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light">
+<title>${opts.title} — YAGNI Code</title>
+<style>${CSS}</style>
+</head>
+<body>
+  <main class="card${opts.error ? " card--error" : ""}">
+    <p class="wordmark">YAGNI Code</p>
+    <div class="badge">${opts.error ? ERROR_ICON : CHECK_ICON}</div>
+    <h1>${opts.heading}</h1>
+    <p class="lede">${opts.lede}</p>
+    ${opts.detail ? `<p class="detail">${opts.detail}</p>` : ""}
+    <div class="divider"></div>
+    <p class="hint">${opts.hint}</p>
+  </main>
+</body>
+</html>`;
+}
+/** The success page shown after the provider redirects back with a code. */
+export function renderAuthSuccessPage() {
+    return shell({
+        title: "Connected",
+        heading: "Connected to YAGNI Code",
+        lede: "Your MCP server is authorized and ready to use.",
+        hint: "You can close this window and return to your session.",
+    });
+}
+/**
+ * The error page shown when the provider bounces the flow. `error` and
+ * `errorDescription` are provider-controlled and already HTML-escaped by the
+ * caller.
+ */
+export function renderAuthErrorPage(opts) {
+    const detail = opts.error
+        ? opts.errorDescription
+            ? `${opts.error}: ${opts.errorDescription}`
+            : opts.error
+        : undefined;
+    return shell({
+        title: "Connection failed",
+        error: true,
+        heading: "Authentication didn't complete",
+        lede: "The provider didn't finish the sign-in flow.",
+        detail,
+        hint: "You can close this window and try again from YAGNI Code.",
+    });
+}
+/** The state-mismatch page — a hard failure, shown before the flow aborts. */
+export function renderAuthStateMismatchPage() {
+    return shell({
+        title: "Connection failed",
+        error: true,
+        heading: "Authentication didn't complete",
+        lede: "The sign-in response didn't match the request, so it was rejected.",
+        hint: "You can close this window and try again from YAGNI Code.",
+    });
+}
+//# sourceMappingURL=callbackPage.js.map

package/dist/extension/mcp/config.d.ts

@@ -58,7 +58,8 @@ export declare function expandEnvVarsInString(value: string, env?: NodeJS.Proces
     expanded: string;
     missingVars: string[];
 };
-/** Where env expansion applies within one server config (command, args, env values). */
+/** Where env expansion applies within one server config (stdio: command,
+ * args, env values; http/sse: url and header values). */
 export declare function expandServerEnv(config: McpServerConfig, env?: NodeJS.ProcessEnv): {
     config: McpServerConfig;
     missingVars: string[];

package/dist/extension/mcp/config.js

@@ -38,7 +38,8 @@ export function expandEnvVarsInString(value, env = process.env) {
     });
     return { expanded, missingVars };
 }
-/** Where env expansion applies within one server config (command, args, env values). */
+/** Where env expansion applies within one server config (stdio: command,
+ * args, env values; http/sse: url and header values). */
 export function expandServerEnv(config, env = process.env) {
     const missingVars = [];
     if (config.type === "stdio" || config.type === undefined) {
@@ -60,6 +61,28 @@ export function expandServerEnv(config, env = process.env) {
             missingVars: [...new Set(missingVars)],
         };
     }
+    // http/sse: url + header values. Used as a load-time gate (missing vars
+    // → server skipped with a clear error) and at connect time to build the
+    // actual transport. The stored config keeps the raw ${VAR} references —
+    // display and the OAuth auth-store key (sha256 of type+url+headers) must
+    // see the raw form, so env changes never orphan stored tokens.
+    if (config.type === "http" || config.type === "sse") {
+        const url = expandEnvVarsInString(config.url, env);
+        missingVars.push(...url.missingVars);
+        const headerEntries = Object.entries(config.headers ?? {}).map(([k, v]) => {
+            const r = expandEnvVarsInString(v, env);
+            missingVars.push(...r.missingVars);
+            return [k, r.expanded];
+        });
+        return {
+            config: {
+                ...config,
+                url: url.expanded,
+                headers: headerEntries.length > 0 ? Object.fromEntries(headerEntries) : config.headers,
+            },
+            missingVars: [...new Set(missingVars)],
+        };
+    }
     return { config, missingVars };
 }
 /** Test seam: point the state home at a tmpdir, mirroring errorSink's pattern. */
@@ -223,6 +246,18 @@ export function loadMcpServers(cwd, env = process.env) {
     for (const [name, value] of Object.entries(userServers)) {
         const validation = validateServerConfig(value);
         if (validation.ok) {
+            // Gate: a ${VAR} reference with no matching env var (and no default)
+            // skips the server with a clear error, rather than sending a literal
+            // "${VAR}" header on the wire. The pushed config stays raw.
+            const expanded = expandServerEnv(value, env);
+            if (expanded.missingVars.length > 0) {
+                errors.push({
+                    sourcePath: mcpConfigPath(),
+                    serverName: name,
+                    message: `missing environment variable(s): ${expanded.missingVars.join(", ")} — server skipped`,
+                });
+                continue;
+            }
             byScope.user.push({ name, config: value, scope: "user", sourcePath: mcpConfigPath() });
         }
         else {
@@ -249,6 +284,15 @@ export function loadMcpServers(cwd, env = process.env) {
     for (const [name, value] of Object.entries(localServers)) {
         const validation = validateServerConfig(value);
         if (validation.ok) {
+            const expanded = expandServerEnv(value, env);
+            if (expanded.missingVars.length > 0) {
+                errors.push({
+                    sourcePath: mcpConfigPath(),
+                    serverName: name,
+                    message: `missing environment variable(s): ${expanded.missingVars.join(", ")} — server skipped`,
+                });
+                continue;
+            }
             byScope.local.push({ name, config: value, scope: "local", sourcePath: mcpConfigPath() });
         }
         else {

package/dist/extension/mcp/manager.d.ts

@@ -36,6 +36,8 @@ export interface ManagerEvents {
 export interface ManagerOpts {
     connectTimeoutMs?: number;
     events?: ManagerEvents;
+    /** Environment for ${VAR} expansion at connect time (default: process.env). */
+    env?: NodeJS.ProcessEnv;
 }
 export declare function connectTimeoutFromEnv(env: NodeJS.ProcessEnv, fallback?: number): number;
 export declare function toolTimeoutFromEnv(env: NodeJS.ProcessEnv): number | undefined;
@@ -43,6 +45,7 @@ export declare class McpManager {
     private servers;
     private events;
     private connectTimeoutMs;
+    private env;
     private closed;
     constructor(opts?: ManagerOpts);
     list(): ManagedServer[];
@@ -87,6 +90,7 @@ export interface McpHealthResult {
  */
 export declare function probeServer(name: string, config: McpStdioServerConfig | McpHttpServerConfig, opts?: {
     connectTimeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
 }): Promise<McpHealthResult>;
 /** 401/403 → needs_auth; everything else → failed. */
 export declare function classifyFailure(message: string): "needs_auth" | "failed";

package/dist/extension/mcp/manager.js

@@ -12,6 +12,7 @@
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { expandServerEnv } from "./config.js";
 import { DEFAULT_CONNECT_TIMEOUT_MS, transportFor } from "./transports.js";
 import { authenticate, authProviderForServer, instrumentOAuthFetch, AuthenticationCancelledError } from "./auth.js";
 export function connectTimeoutFromEnv(env, fallback = DEFAULT_CONNECT_TIMEOUT_MS) {
@@ -32,10 +33,12 @@ export class McpManager {
     servers = new Map();
     events;
     connectTimeoutMs;
+    env;
     closed = false;
     constructor(opts = {}) {
         this.events = opts.events ?? {};
         this.connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+        this.env = opts.env ?? process.env;
     }
     list() {
         return [...this.servers.values()];
@@ -61,18 +64,33 @@ export class McpManager {
         if (server.status === "connected")
             return server;
         this.setStatus(server, "connecting");
+        // Expand ${VAR} at connect time only: the stored config (panel display,
+        // OAuth auth-store keys) stays raw; the wire gets the resolved values.
+        // A missing var fails fast with a clear error instead of sending a
+        // literal "${VAR}" header (which the SDK retries until timeout).
+        const expanded = expandServerEnv(server.config, this.env);
+        if (expanded.missingVars.length > 0) {
+            server.error = `missing environment variable(s): ${expanded.missingVars.join(", ")} — set ${expanded.missingVars.join(", ")} and reconnect via /mcp`;
+            this.setStatus(server, "failed");
+            return server;
+        }
         const oauth = isOAuthServer(server.config);
         const authProvider = oauth ? authProviderForServer(name, server.config) : undefined;
         const fetchImpl = oauth ? instrumentOAuthFetch(name, fetch) : undefined;
-        const transport = transportFor(server.config, authProvider, fetchImpl);
         const client = new Client({ name: "yagni-code", version: "1.0" });
+        let transport;
         try {
+            // Inside the try: an expanded URL that is not a valid URL throws from
+            // `new URL()` in transportFor and must land in `failed`, not escape the
+            // manager. Errors are sanitized before display — an expanded value that
+            // an SDK error echoes back must never reach the panel verbatim.
+            transport = transportFor(expanded.config, authProvider, fetchImpl);
             await withTimeout(client.connect(transport), this.connectTimeoutMs, `connect timed out after ${this.connectTimeoutMs}ms`);
         }
         catch (err) {
             await safeClose(client);
             const message = err instanceof Error ? err.message : String(err);
-            server.error = message;
+            server.error = sanitizeError(message);
             this.setStatus(server, err instanceof UnauthorizedError ? "needs_auth" : classifyFailure(message));
             return server;
         }
@@ -130,8 +148,21 @@ export class McpManager {
             this.setStatus(server, "failed");
             return server;
         }
+        // OAuth discovery + token exchange must hit the ${VAR}-expanded URL (the
+        // literal reference is not a resolvable endpoint); the raw config is still
+        // what authenticate() keys the auth store with. Missing vars fail here the
+        // same way connect() does — names only.
+        const expanded = expandServerEnv(server.config, this.env);
+        if (expanded.missingVars.length > 0) {
+            server.error = `missing environment variable(s): ${expanded.missingVars.join(", ")} — set ${expanded.missingVars.join(", ")} and reconnect via /mcp`;
+            this.setStatus(server, "failed");
+            return server;
+        }
         try {
-            await authenticate(name, server.config, authDeps, { signal });
+            await authenticate(name, server.config, authDeps, {
+                signal,
+                serverUrl: expanded.config.url,
+            });
         }
         catch (err) {
             if (err instanceof AuthenticationCancelledError) {
@@ -176,12 +207,21 @@ export class McpManager {
  */
 export async function probeServer(name, config, opts = {}) {
     const timeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    const expanded = expandServerEnv(config, opts.env ?? process.env);
+    if (expanded.missingVars.length > 0) {
+        return {
+            status: "failed",
+            error: `missing environment variable(s): ${expanded.missingVars.join(", ")} — set ${expanded.missingVars.join(", ")} and try again`,
+        };
+    }
     const oauth = isOAuthServer(config);
     const authProvider = oauth ? authProviderForServer(name, config) : undefined;
     const fetchImpl = oauth ? instrumentOAuthFetch(name, fetch) : undefined;
-    const transport = transportFor(config, authProvider, fetchImpl);
     const client = new Client({ name: "yagni-code", version: "1.0" });
     try {
+        // transportFor inside the try: `new URL()` on a bad expanded URL must
+        // report `failed`, not throw out of the probe.
+        const transport = transportFor(expanded.config, authProvider, fetchImpl);
         await withTimeout(client.connect(transport), timeoutMs, `connect timed out after ${timeoutMs}ms`);
         return { status: "connected" };
     }

package/dist/extension/mcp/startup.js

@@ -34,6 +34,7 @@ export async function startMcp(pi, opts) {
     const outcome = {
         manager: new McpManager({
             events: { onLog: appendMcpLogLine },
+            env,
         }),
         connectedServers: [],
         failedServers: [],

package/dist/mcpCommand.d.ts

@@ -23,7 +23,9 @@ export interface McpDeps {
     /** Test seam: the extension module to import (defaults to the built copy). */
     loadMcpModule?: () => Promise<McpCliModule>;
     /** Test seam: health probe override (defaults to mod.probeServer). */
-    probeServer?: (name: string, config: unknown) => Promise<{
+    probeServer?: (name: string, config: unknown, opts?: {
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
         status: "connected" | "needs_auth" | "failed";
         error?: string;
     }>;
@@ -60,10 +62,16 @@ export interface McpCliModule {
     } | undefined;
     probeServer(name: string, config: unknown, opts?: {
         connectTimeoutMs?: number;
+        env?: NodeJS.ProcessEnv;
     }): Promise<{
         status: "connected" | "needs_auth" | "failed";
         error?: string;
     }>;
+    /** ${VAR} expansion over a full server config (url, headers, command, args, env values). */
+    expandServerEnv?(config: unknown, env?: NodeJS.ProcessEnv): {
+        config: unknown;
+        missingVars: string[];
+    };
 }
 export interface McpLoadResult {
     servers: {

package/dist/mcpCommand.js

@@ -598,7 +598,7 @@ async function healthLine(mod, server, io) {
         if (decision === "undecided")
             return `  Status: ! not yet approved — run /mcp to approve it\n`;
     }
-    const result = await (io.probeServer ?? mod.probeServer)(server.name, server.config);
+    const result = await (io.probeServer ?? mod.probeServer)(server.name, server.config, { env: io.env });
     if (result.status === "connected")
         return `  Status: ✓ connected\n`;
     if (result.status === "needs_auth")
@@ -642,7 +642,7 @@ async function listHealthLine(mod, server, io) {
         if (decision === "undecided")
             return "! not approved";
     }
-    const result = await (io.probeServer ?? mod.probeServer)(server.name, server.config);
+    const result = await (io.probeServer ?? mod.probeServer)(server.name, server.config, { env: io.env });
     if (result.status === "connected")
         return "✓ connected";
     if (result.status === "needs_auth")
@@ -685,6 +685,29 @@ function mcpAddFromClaude(mod, parsed, io) {
     }
     let imported = 0;
     const skipped = [];
+    const warned = [];
+    /**
+     * An imported config may reference ${VAR} env vars that Claude Code expanded
+     * in its own shell. We import verbatim (the raw reference is the correct
+     * stored form) but warn when a var is not set in THIS shell, with the export
+     * line to fix it — the var may legitimately be set only in the shell that
+     * runs sessions. The canonical expandServerEnv walks every expandable field
+     * (url, headers, stdio command/args/env), so the warning can never diverge
+     * from what the session will actually fail on.
+     */
+    const warnUnsetEnvVars = (name, config) => {
+        if (typeof config !== "object" || config === null)
+            return;
+        if (typeof mod.expandServerEnv !== "function")
+            return;
+        const { missingVars } = mod.expandServerEnv(config, process.env);
+        if (missingVars.length > 0) {
+            const names = missingVars.join(", ");
+            io.stderr(`Note: ${name} references ${names} — not currently set in this shell. ` +
+                `It will expand at connect time; export it (e.g. export ${missingVars[0]}=... in your shell profile) before your next session, or the server will report a missing-variable error.\n`);
+            warned.push(name);
+        }
+    };
     // Claude Code's user scope maps to yagni user scope (unless -s local is
     // explicit); its per-project entries map to yagni local scope for this cwd.
     const claudeUserTarget = parsed.scopeExplicit && parsed.scope === "local" ? "local" : "user";
@@ -695,6 +718,7 @@ function mcpAddFromClaude(mod, parsed, io) {
         }
         try {
             writeServerToScope(mod, name, config, claudeUserTarget, io.cwd);
+            warnUnsetEnvVars(name, config);
             io.stdout(`Imported ${name} (Claude Code user scope → ${claudeUserTarget})\n`);
             imported++;
         }
@@ -710,6 +734,7 @@ function mcpAddFromClaude(mod, parsed, io) {
         }
         try {
             writeServerToScope(mod, name, config, "local", io.cwd);
+            warnUnsetEnvVars(name, config);
             io.stdout(`Imported ${name} (this project, from Claude Code → local)\n`);
             imported++;
         }
@@ -720,7 +745,7 @@ function mcpAddFromClaude(mod, parsed, io) {
     }
     if (skipped.length > 0)
         io.stderr(`Skipped (unsupported config shape): ${skipped.join(", ")}\n`);
-    io.stdout(`Imported ${imported} server(s) from Claude Code.\n`);
+    io.stdout(`Imported ${imported} server(s) from Claude Code${warned.length > 0 ? ` (${warned.length} with env-var notes)` : ""}.\n`);
     return imported > 0 ? 0 : 1;
 }
 function isImportable(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.5-staging.1239.1",
+  "version": "1.0.5-staging.1241.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -42,5 +42,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "56fce757cff3be4c0f2ae824cd40e8b2e8da50b2"
+  "yagniSourceSha": "9328192141ab3d96cbeb324d748df1e571fe5eb2"
 }