@stigmer/cli 3.1.6 → 3.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/cli",
-  "version": "3.1.6",
+  "version": "3.1.7",
   "description": "Stigmer command-line interface — manage agents, workflows, MCP servers, skills, and executions from the terminal",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,10 +35,10 @@
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.1.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@stigmer/ink": "3.1.6",
-    "@stigmer/mcp-server": "3.1.6",
-    "@stigmer/protos": "3.1.6",
-    "@stigmer/sdk": "3.1.6",
+    "@stigmer/ink": "3.1.7",
+    "@stigmer/mcp-server": "3.1.7",
+    "@stigmer/protos": "3.1.7",
+    "@stigmer/sdk": "3.1.7",
     "commander": "^12.1.0",
     "fflate": "^0.8.3",
     "ink": "^7.0.0",

package/resources/connect/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../../src/resources/connect/connect.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AAExF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2DAA2D,CAAC;AAExG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAO1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC1D,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBpG"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../../src/resources/connect/connect.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AAExF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2DAA2D,CAAC;AAExG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC1D,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA+BpG"}

package/resources/connect/connect.js

@@ -12,6 +12,7 @@ import { create } from "@bufbuild/protobuf";
 import { ConnectInputSchema, GetOAuthGrantStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { UsageError } from "../../errors/index.js";
 import { defaultRegistry } from "../../registry/index.js";
+import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 import { buildRuntimeEnv } from "../mcp/runtime-env.js";
 import { parseReference } from "../reference.js";
 import { localDiscover } from "./discover.js";
@@ -21,8 +22,23 @@ export async function connectMcpServer(client, opts) {
     if (opts.dryRun) {
         if (server.spec === undefined)
             throw new UsageError("MCP server has no spec; cannot discover capabilities");
-        const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
-        return { server, capabilities, updated: undefined };
+        // An oauth_only endpoint rejects static tokens, and the OAuth token lives in
+        // the backend's managed environment — never on the caller's machine. So local
+        // discovery cannot authenticate it; say so plainly instead of failing on a 401.
+        if (isOAuthOnly(server))
+            throw oauthOnlyDryRunError(server, opts.reference);
+        try {
+            const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
+            return { server, capabilities, updated: undefined };
+        }
+        catch (err) {
+            // A ${VAR} placeholder that could not be resolved is a configuration
+            // problem, not a discovery failure — surface it as actionable guidance
+            // instead of a raw resolver error or a cryptic subprocess crash.
+            if (err instanceof PlaceholderResolutionError)
+                throw unresolvedEnvError(server, err);
+            throw err;
+        }
     }
     await ensureOAuthSatisfied(client, server, opts);
     const updated = await client.mcpServer.connect(create(ConnectInputSchema, {
@@ -46,8 +62,18 @@ async function resolveMcpServer(client, reference, org) {
 // flow and wait for the grant; otherwise stop with actionable guidance so
 // scripted callers get a clean, stable failure instead of a 5-minute block.
 async function ensureOAuthSatisfied(client, server, opts) {
-    if (!oauthRequired(server) || opts.envOverrides.length > 0)
+    if (!oauthRequired(server))
         return;
+    const oauthOnly = isOAuthOnly(server);
+    // A manually supplied token is a valid bypass for a normal OAuth server (many
+    // vendors also accept a PAT), but an oauth_only endpoint rejects static tokens
+    // outright — so --env cannot connect it. Fail with guidance rather than push a
+    // token the endpoint will reject.
+    if (opts.envOverrides.length > 0) {
+        if (!oauthOnly)
+            return;
+        throw oauthOnlyEnvError(server, opts.reference);
+    }
     const status = await client.mcpServer.getOAuthGrantStatus(create(GetOAuthGrantStatusInputSchema, {
         resourceId: server.metadata?.id ?? "",
         org: opts.org,
@@ -55,18 +81,60 @@ async function ensureOAuthSatisfied(client, server, opts) {
     if (status.connected)
         return;
     if (!opts.interactive)
-        throw oauthGuidanceError(server, opts.reference);
+        throw oauthGuidanceError(server, opts.reference, oauthOnly);
     const { runOAuthFlow } = await import("./oauth.js");
     await runOAuthFlow({ client, server, org: opts.org, backendType: opts.backendType });
 }
-function oauthGuidanceError(server, reference) {
+// Turn a strict-resolution failure into actionable guidance. A declared-but-unset
+// variable is the user's to provide; an undeclared one is a bug in the server
+// definition. Both are far clearer than the cryptic subprocess crash (ENOENT on a
+// literal "${VAR}" path) that motivated issue #141.
+function unresolvedEnvError(server, err) {
+    const slug = server.metadata?.slug ?? server.metadata?.name ?? server.metadata?.id ?? "this server";
+    const decl = server.spec?.env?.[err.variableName];
+    if (decl) {
+        const hint = decl.description !== "" ? ` (${decl.description})` : "";
+        return new UsageError(`MCP server '${slug}' needs environment variable ${err.variableName}${hint}, but it is not set.\n` +
+            `Provide it with --env ${err.variableName}=<value> or export it in your shell before running --dry-run.`);
+    }
+    const where = err.context !== undefined ? ` in its ${err.context}` : "";
+    return new UsageError(`MCP server '${slug}' references \${${err.variableName}}${where} but does not declare ${err.variableName} under spec.env.\n` +
+        `This is a problem with the server definition — declare ${err.variableName} in the server's env, or remove the placeholder.`);
+}
+function oauthGuidanceError(server, reference, oauthOnly) {
     const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+    const choices = [
+        "  - Re-run this command in an interactive terminal to complete OAuth in your browser",
+    ];
+    // Only offer the manual-token route for servers that actually accept one.
+    // Suggesting it for an oauth_only endpoint would send the user down a dead end.
+    if (!oauthOnly) {
+        choices.push(`  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`);
+    }
     return new UsageError(`MCP server '${slug}' requires OAuth authentication, which needs an interactive terminal.\n\n` +
-        "To connect, choose one of:\n" +
-        "  - Re-run this command in an interactive terminal to complete OAuth in your browser\n" +
-        `  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`);
+        `To connect${oauthOnly ? "" : ", choose one of"}:\n` +
+        choices.join("\n"));
+}
+// An oauth_only server whose endpoint rejects static tokens was given a manual
+// token via --env. Explain that OAuth is the only path rather than pushing a
+// credential the endpoint will reject with an opaque 401.
+function oauthOnlyEnvError(server, reference) {
+    const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+    return new UsageError(`MCP server '${slug}' requires OAuth and rejects manually-entered tokens, so --env cannot connect it.\n` +
+        `Re-run without --env in an interactive terminal to sign in: stigmer connect mcp-server ${slug}`);
+}
+// --dry-run discovers locally, but an oauth_only endpoint needs an OAuth token
+// that only the backend can obtain and store — there is nothing valid to send
+// from the caller's machine. Say so plainly instead of attempting a doomed 401.
+function oauthOnlyDryRunError(server, reference) {
+    const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+    return new UsageError(`MCP server '${slug}' requires OAuth, so --dry-run cannot discover it locally — its endpoint only accepts an OAuth token that the connected backend obtains for you.\n` +
+        `Run it for real and sign in when prompted: stigmer connect mcp-server ${slug}`);
 }
 function oauthRequired(server) {
     return (server.spec?.auth?.targetEnvVar ?? "") !== "";
 }
+function isOAuthOnly(server) {
+    return server.spec?.auth?.oauthOnly === true;
+}
 //# sourceMappingURL=connect.js.map

package/resources/connect/connect.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../../src/resources/connect/connect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../../src/resources/connect/connect.ts"],"names":[],"mappings":"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"}

package/resources/connect/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/resources/connect/discover.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yDAAyD,CAAC;AAC7F,OAAO,EACL,KAAK,sBAAsB,EAI5B,MAAM,2DAA2D,CAAC;AAMnE,uFAAuF;AACvF,wBAAsB,aAAa,CACjC,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,CAAC,CA0CjC"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/resources/connect/discover.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yDAAyD,CAAC;AAC7F,OAAO,EACL,KAAK,sBAAsB,EAI5B,MAAM,2DAA2D,CAAC;AAOnE,uFAAuF;AACvF,wBAAsB,aAAa,CACjC,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,CAAC,CA0CjC"}

package/resources/connect/discover.js

@@ -12,7 +12,8 @@
 import { create } from "@bufbuild/protobuf";
 import { DiscoveredCapabilitiesSchema, DiscoveredResourceTemplateSchema, DiscoveredToolSchema, } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { mergeProcessEnv } from "../mcp/runtime-env.js";
+import { mergeProcessEnv, resolveDeclaredEnvValues } from "../mcp/runtime-env.js";
+import { resolveHeaders, resolvePlaceholders } from "../mcp/placeholder-resolver.js";
 /** Discover an MCP server's capabilities locally without persisting to the backend. */
 export async function localDiscover(spec, envOverrides, timeoutMs) {
     const { transport, readStderr } = await buildTransport(spec, envOverrides);
@@ -53,14 +54,21 @@ export async function localDiscover(spec, envOverrides, timeoutMs) {
     }
 }
 async function buildTransport(spec, envOverrides) {
+    // ${VAR} placeholders in args/headers resolve against the exact same env the
+    // backend hands the runner for real connect (declared keys from the OS env +
+    // --env overrides) — so dry-run is a faithful preview. Resolution is strict:
+    // an unresolved placeholder throws before any subprocess is spawned, matching
+    // the proto contract (never pass a literal "${VAR}" to the server).
+    const resolutionEnv = resolveDeclaredEnvValues(spec.env ?? {}, envOverrides);
     if (spec.serverType?.case === "stdio") {
         const { command, args, workingDir } = spec.serverType.value;
         if (command === "")
             throw new Error("stdio transport requires a command");
+        const resolvedArgs = args.map((arg, i) => resolvePlaceholders(arg, resolutionEnv, `stdio arg[${i}]`));
         const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
         const transport = new StdioClientTransport({
             command,
-            args: [...args],
+            args: resolvedArgs,
             cwd: workingDir !== "" ? workingDir : undefined,
             env: mergeProcessEnv([...envOverrides, ...goRunEnvOverrides(command, args)]),
             // "pipe" exposes the child stderr as a PassThrough immediately, so we can
@@ -78,8 +86,8 @@ async function buildTransport(spec, envOverrides) {
         if (url === "")
             throw new Error("HTTP transport requires a URL");
         const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
-        const requestInit = Object.keys(headers).length > 0 ? { headers: { ...headers } } : undefined;
-        const transport = new StreamableHTTPClientTransport(new URL(url), requestInit ? { requestInit } : undefined);
+        const resolvedHeaders = Object.keys(headers).length > 0 ? resolveHeaders(headers, resolutionEnv) : undefined;
+        const transport = new StreamableHTTPClientTransport(new URL(url), resolvedHeaders ? { requestInit: { headers: resolvedHeaders } } : undefined);
         return { transport, readStderr: () => "" };
     }
     throw new Error("MCP server has no transport configured (expected stdio or http)");

package/resources/connect/discover.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/resources/connect/discover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/resources/connect/discover.ts"],"names":[],"mappings":"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"}

package/resources/mcp/placeholder-resolver.d.ts

@@ -0,0 +1,19 @@
+export declare class PlaceholderResolutionError extends Error {
+    readonly variableName: string;
+    readonly context?: string | undefined;
+    constructor(variableName: string, context?: string | undefined);
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export declare function resolvePlaceholders(template: string, envVars: Record<string, string>, context?: string): string;
+/**
+ * Resolve placeholders in every value of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export declare function resolveHeaders(headers: Record<string, string>, envVars: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=placeholder-resolver.d.ts.map

package/resources/mcp/placeholder-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-resolver.d.ts","sourceRoot":"","sources":["../../../src/resources/mcp/placeholder-resolver.ts"],"names":[],"mappings":"AAeA,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,YAAY,EAAE,MAAM;aACpB,OAAO,CAAC,EAAE,MAAM;gBADhB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,YAAA;CASnC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}

package/resources/mcp/placeholder-resolver.js

@@ -0,0 +1,52 @@
+// Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+//
+// The MCP server spec (StdioServerConfig.args, HttpServerConfig.headers) allows
+// values to reference declared env vars with ${VAR_NAME}. The proto contract is
+// explicit that resolution is strict: a missing variable must produce a clear
+// error rather than passing a literal "${VAR}" to the subprocess/server.
+//
+// This mirrors the runner's shared resolver (backend/services/runner/src/shared/
+// placeholder-resolver.ts) so `connect --dry-run` (which discovers locally)
+// behaves identically to real connect (which resolves on the runner). Kept
+// intentionally dependency-free and semantically identical so the two can be
+// collapsed into one shared package later without any behavior change.
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+export class PlaceholderResolutionError extends Error {
+    variableName;
+    context;
+    constructor(variableName, context) {
+        const where = context ? ` in ${context}` : "";
+        super(`Unresolved placeholder \${${variableName}}${where}: ` +
+            `variable is not present in the execution environment`);
+        this.variableName = variableName;
+        this.context = context;
+        this.name = "PlaceholderResolutionError";
+    }
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(template, envVars, context) {
+    return template.replace(PLACEHOLDER_RE, (_match, varName) => {
+        if (varName in envVars) {
+            return envVars[varName];
+        }
+        throw new PlaceholderResolutionError(varName, context);
+    });
+}
+/**
+ * Resolve placeholders in every value of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(headers, envVars) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(headers)) {
+        resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=placeholder-resolver.js.map

package/resources/mcp/placeholder-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-resolver.js","sourceRoot":"","sources":["../../../src/resources/mcp/placeholder-resolver.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,2EAA2E;AAC3E,6EAA6E;AAC7E,uEAAuE;AAEvE,MAAM,cAAc,GAAG,iCAAiC,CAAC;AAEzD,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAEjC;IACA;IAFlB,YACkB,YAAoB,EACpB,OAAgB;QAEhC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,KAAK,CACH,6BAA6B,YAAY,IAAI,KAAK,IAAI;YACpD,sDAAsD,CACzD,CAAC;QAPc,iBAAY,GAAZ,YAAY,CAAQ;QACpB,YAAO,GAAP,OAAO,CAAS;QAOhC,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,OAA+B,EAC/B,OAAgB;IAEhB,OAAO,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE;QAClE,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,IAAI,0BAA0B,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA+B,EAC/B,OAA+B;IAE/B,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,QAAQ,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,GAAG,GAAG,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/resources/mcp/runtime-env.d.ts

@@ -8,6 +8,22 @@ type ExecutionValue = ReturnType<typeof create<typeof ExecutionValueSchema>>;
  * clear usage error rather than a silently-ignored credential.
  */
 export declare function parseEnvOverrides(overrides: readonly string[]): Record<string, string>;
+/**
+ * Resolve the values behind a server's declared env vars: declared keys pulled
+ * from the OS environment (non-empty only), with `--env` overrides layered on
+ * top (override wins; an undeclared override is still included).
+ *
+ * This is the single source of truth for "which env value is in play". It backs
+ * both the runtime_env sent to the backend (buildRuntimeEnv) and the ${VAR}
+ * placeholder resolution done locally for `--dry-run` (discover.ts), so the two
+ * can never drift: dry-run resolves against the exact same map the backend hands
+ * the runner (minus platform-injected infra vars, which a local machine cannot
+ * know).
+ *
+ * `declarations` is the server's `spec.env` map; only its keys (the declared
+ * variable names) are read, so any map keyed by those names is accepted.
+ */
+export declare function resolveDeclaredEnvValues(declarations: Record<string, unknown>, envOverrides?: readonly string[]): Record<string, string>;
 /**
  * Build the runtime_env map for the Connect RPC from the OS environment and the
  * supplied --env overrides. Only keys with a non-empty value are emitted.

package/resources/mcp/runtime-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-env.d.ts","sourceRoot":"","sources":["../../../src/resources/mcp/runtime-env.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AAGxF,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUtF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAiBhC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvF"}
+{"version":3,"file":"runtime-env.d.ts","sourceRoot":"","sources":["../../../src/resources/mcp/runtime-env.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AAGxF,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUtF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAUhC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvF"}

package/resources/mcp/runtime-env.js

@@ -30,21 +30,42 @@ export function parseEnvOverrides(overrides) {
     }
     return result;
 }
+/**
+ * Resolve the values behind a server's declared env vars: declared keys pulled
+ * from the OS environment (non-empty only), with `--env` overrides layered on
+ * top (override wins; an undeclared override is still included).
+ *
+ * This is the single source of truth for "which env value is in play". It backs
+ * both the runtime_env sent to the backend (buildRuntimeEnv) and the ${VAR}
+ * placeholder resolution done locally for `--dry-run` (discover.ts), so the two
+ * can never drift: dry-run resolves against the exact same map the backend hands
+ * the runner (minus platform-injected infra vars, which a local machine cannot
+ * know).
+ *
+ * `declarations` is the server's `spec.env` map; only its keys (the declared
+ * variable names) are read, so any map keyed by those names is accepted.
+ */
+export function resolveDeclaredEnvValues(declarations, envOverrides = []) {
+    const values = {};
+    for (const key of Object.keys(declarations)) {
+        const value = process.env[key];
+        if (value !== undefined && value !== "")
+            values[key] = value;
+    }
+    for (const [key, value] of Object.entries(parseEnvOverrides(envOverrides))) {
+        values[key] = value;
+    }
+    return values;
+}
 /**
  * Build the runtime_env map for the Connect RPC from the OS environment and the
  * supplied --env overrides. Only keys with a non-empty value are emitted.
  */
 export function buildRuntimeEnv(server, envOverrides = []) {
     const declarations = server.spec?.env ?? {};
-    const overrides = parseEnvOverrides(envOverrides);
+    const values = resolveDeclaredEnvValues(declarations, envOverrides);
     const runtime = {};
-    for (const [key, decl] of Object.entries(declarations)) {
-        const value = process.env[key];
-        if (value !== undefined && value !== "") {
-            runtime[key] = create(ExecutionValueSchema, { value, isSecret: decl.isSecret });
-        }
-    }
-    for (const [key, value] of Object.entries(overrides)) {
+    for (const [key, value] of Object.entries(values)) {
         runtime[key] = create(ExecutionValueSchema, { value, isSecret: declarations[key]?.isSecret ?? false });
     }
     return runtime;

package/resources/mcp/runtime-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../../../src/resources/mcp/runtime-env.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,gDAAgD;AAChD,0EAA0E;AAC1E,uEAAuE;AACvE,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAE3E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AAEtG,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAInD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA4B;IAC5D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,wBAAwB,KAAK,uBAAuB,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAiB,EACjB,eAAkC,EAAE;IAEpC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAClD,MAAM,OAAO,GAAmC,EAAE,CAAC;IAEnD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,oBAAoB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,oBAAoB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,QAAQ,IAAI,KAAK,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,YAA+B;IAC7D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../../../src/resources/mcp/runtime-env.ts"],"names":[],"mappings":"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"}

package/src/resources/connect/__fixtures__/stdio-server.mjs

@@ -3,8 +3,9 @@
 // Spawned as a subprocess by discover.ts via StdioClientTransport. Advertises a
 // single tool and a single resource template using the low-level Server API
 // (the most version-stable surface of @modelcontextprotocol/sdk). It also echoes
-// an --env-provided value through the tool description so tests can assert env
-// propagation when needed.
+// an --env-provided value AND the CLI args it received (process.argv beyond the
+// script path) through the tool description, so tests can assert env propagation
+// and ${VAR} argument expansion.
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -18,11 +19,15 @@ const server = new Server(
   { capabilities: { tools: {}, resources: {} } },
 );
 
+const receivedArgs = process.argv.slice(2);
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "echo",
-      description: `echo a message (token=${process.env.FIXTURE_TOKEN ?? "unset"})`,
+      description:
+        `echo a message (token=${process.env.FIXTURE_TOKEN ?? "unset"}) ` +
+        `(args=${JSON.stringify(receivedArgs)})`,
       inputSchema: { type: "object", properties: { text: { type: "string" } } },
     },
     { name: "noop", description: "", inputSchema: { type: "object" } },

package/src/resources/connect/connect.integration.test.ts

@@ -168,6 +168,66 @@ describe("OAuth guidance gate", () => {
   });
 });
 
+describe("oauth_only servers reject the manual-token routes", () => {
+  beforeEach(() => {
+    servedSpec.spec!.auth = create(McpServerAuthSchema, {
+      targetEnvVar: "GITHUB_TOKEN",
+      oauthOnly: true,
+    });
+  });
+
+  it("rejects --env (which cannot satisfy an OAuth-only endpoint) instead of pushing a doomed token", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: ["GITHUB_TOKEN=ghp-x"],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).toMatch(/requires OAuth/i);
+    // The guidance must NOT recommend the manual-token route for an oauth_only server.
+    expect((err as UsageError).message).not.toContain("--env TOKEN=");
+    expect(connectCalls).toHaveLength(0);
+  });
+
+  it("omits the --env suggestion from the non-interactive OAuth guidance", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).not.toContain("--env TOKEN=");
+    expect(connectCalls).toHaveLength(0);
+  });
+
+  it("refuses --dry-run local discovery (no locally-obtainable OAuth token) with a clear message", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 10_000,
+      dryRun: true,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).toMatch(/requires OAuth/i);
+    expect((err as UsageError).message).toContain("--dry-run");
+    expect(connectCalls).toHaveLength(0);
+  });
+});
+
 describe("dry-run path", () => {
   it("discovers locally and never calls the Connect RPC", async () => {
     const result = await connectMcpServer(client, {
@@ -192,4 +252,35 @@ describe("dry-run path", () => {
     expect(text).toContain("Tools (2):");
     expect(text).toContain("Dry run — results not saved");
   }, 15_000);
+
+  it("maps an unresolved ${VAR} arg to actionable guidance and never calls Connect", async () => {
+    // Server references a declared env var in its args, but it is not set.
+    delete process.env.NEEDED_DIR;
+    servedSpec = create(McpServerSchema, {
+      metadata: { id: "mcp_1", name: "filesystem", slug: "filesystem", org: "acme" },
+      spec: {
+        serverType: {
+          case: "stdio",
+          value: { command: process.execPath, args: [FIXTURE, "${NEEDED_DIR}"] },
+        },
+        env: { NEEDED_DIR: { isSecret: false, description: "Root directory the server may access" } },
+      },
+    });
+
+    const err = await connectMcpServer(client, {
+      reference: "filesystem",
+      org: "acme",
+      timeoutMs: 10_000,
+      dryRun: true,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    const message = (err as UsageError).message;
+    expect(message).toContain("NEEDED_DIR");
+    expect(message).toContain("--env");
+    expect(connectCalls).toHaveLength(0);
+  }, 15_000);
 });

package/src/resources/connect/connect.ts

@@ -18,6 +18,7 @@ import type { Stigmer } from "@stigmer/sdk";
 import type { BackendType } from "../../config/config.js";
 import { UsageError } from "../../errors/index.js";
 import { defaultRegistry } from "../../registry/index.js";
+import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 import { buildRuntimeEnv } from "../mcp/runtime-env.js";
 import { parseReference } from "../reference.js";
 import { localDiscover } from "./discover.js";
@@ -47,8 +48,20 @@ export async function connectMcpServer(client: Stigmer, opts: ConnectOptions): P
 
   if (opts.dryRun) {
     if (server.spec === undefined) throw new UsageError("MCP server has no spec; cannot discover capabilities");
-    const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
-    return { server, capabilities, updated: undefined };
+    // An oauth_only endpoint rejects static tokens, and the OAuth token lives in
+    // the backend's managed environment — never on the caller's machine. So local
+    // discovery cannot authenticate it; say so plainly instead of failing on a 401.
+    if (isOAuthOnly(server)) throw oauthOnlyDryRunError(server, opts.reference);
+    try {
+      const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
+      return { server, capabilities, updated: undefined };
+    } catch (err) {
+      // A ${VAR} placeholder that could not be resolved is a configuration
+      // problem, not a discovery failure — surface it as actionable guidance
+      // instead of a raw resolver error or a cryptic subprocess crash.
+      if (err instanceof PlaceholderResolutionError) throw unresolvedEnvError(server, err);
+      throw err;
+    }
   }
 
   await ensureOAuthSatisfied(client, server, opts);
@@ -77,7 +90,18 @@ async function resolveMcpServer(client: Stigmer, reference: string, org: string)
 // flow and wait for the grant; otherwise stop with actionable guidance so
 // scripted callers get a clean, stable failure instead of a 5-minute block.
 async function ensureOAuthSatisfied(client: Stigmer, server: McpServer, opts: ConnectOptions): Promise<void> {
-  if (!oauthRequired(server) || opts.envOverrides.length > 0) return;
+  if (!oauthRequired(server)) return;
+
+  const oauthOnly = isOAuthOnly(server);
+
+  // A manually supplied token is a valid bypass for a normal OAuth server (many
+  // vendors also accept a PAT), but an oauth_only endpoint rejects static tokens
+  // outright — so --env cannot connect it. Fail with guidance rather than push a
+  // token the endpoint will reject.
+  if (opts.envOverrides.length > 0) {
+    if (!oauthOnly) return;
+    throw oauthOnlyEnvError(server, opts.reference);
+  }
 
   const status = await client.mcpServer.getOAuthGrantStatus(
     create(GetOAuthGrantStatusInputSchema, {
@@ -87,22 +111,76 @@ async function ensureOAuthSatisfied(client: Stigmer, server: McpServer, opts: Co
   );
   if (status.connected) return;
 
-  if (!opts.interactive) throw oauthGuidanceError(server, opts.reference);
+  if (!opts.interactive) throw oauthGuidanceError(server, opts.reference, oauthOnly);
 
   const { runOAuthFlow } = await import("./oauth.js");
   await runOAuthFlow({ client, server, org: opts.org, backendType: opts.backendType });
 }
 
-function oauthGuidanceError(server: McpServer, reference: string): UsageError {
+// Turn a strict-resolution failure into actionable guidance. A declared-but-unset
+// variable is the user's to provide; an undeclared one is a bug in the server
+// definition. Both are far clearer than the cryptic subprocess crash (ENOENT on a
+// literal "${VAR}" path) that motivated issue #141.
+function unresolvedEnvError(server: McpServer, err: PlaceholderResolutionError): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? server.metadata?.id ?? "this server";
+  const decl = server.spec?.env?.[err.variableName];
+  if (decl) {
+    const hint = decl.description !== "" ? ` (${decl.description})` : "";
+    return new UsageError(
+      `MCP server '${slug}' needs environment variable ${err.variableName}${hint}, but it is not set.\n` +
+        `Provide it with --env ${err.variableName}=<value> or export it in your shell before running --dry-run.`,
+    );
+  }
+  const where = err.context !== undefined ? ` in its ${err.context}` : "";
+  return new UsageError(
+    `MCP server '${slug}' references \${${err.variableName}}${where} but does not declare ${err.variableName} under spec.env.\n` +
+      `This is a problem with the server definition — declare ${err.variableName} in the server's env, or remove the placeholder.`,
+  );
+}
+
+function oauthGuidanceError(server: McpServer, reference: string, oauthOnly: boolean): UsageError {
   const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  const choices = [
+    "  - Re-run this command in an interactive terminal to complete OAuth in your browser",
+  ];
+  // Only offer the manual-token route for servers that actually accept one.
+  // Suggesting it for an oauth_only endpoint would send the user down a dead end.
+  if (!oauthOnly) {
+    choices.push(`  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`);
+  }
   return new UsageError(
     `MCP server '${slug}' requires OAuth authentication, which needs an interactive terminal.\n\n` +
-      "To connect, choose one of:\n" +
-      "  - Re-run this command in an interactive terminal to complete OAuth in your browser\n" +
-      `  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`,
+      `To connect${oauthOnly ? "" : ", choose one of"}:\n` +
+      choices.join("\n"),
+  );
+}
+
+// An oauth_only server whose endpoint rejects static tokens was given a manual
+// token via --env. Explain that OAuth is the only path rather than pushing a
+// credential the endpoint will reject with an opaque 401.
+function oauthOnlyEnvError(server: McpServer, reference: string): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  return new UsageError(
+    `MCP server '${slug}' requires OAuth and rejects manually-entered tokens, so --env cannot connect it.\n` +
+      `Re-run without --env in an interactive terminal to sign in: stigmer connect mcp-server ${slug}`,
+  );
+}
+
+// --dry-run discovers locally, but an oauth_only endpoint needs an OAuth token
+// that only the backend can obtain and store — there is nothing valid to send
+// from the caller's machine. Say so plainly instead of attempting a doomed 401.
+function oauthOnlyDryRunError(server: McpServer, reference: string): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  return new UsageError(
+    `MCP server '${slug}' requires OAuth, so --dry-run cannot discover it locally — its endpoint only accepts an OAuth token that the connected backend obtains for you.\n` +
+      `Run it for real and sign in when prompted: stigmer connect mcp-server ${slug}`,
   );
 }
 
 function oauthRequired(server: McpServer): boolean {
   return (server.spec?.auth?.targetEnvVar ?? "") !== "";
 }
+
+function isOAuthOnly(server: McpServer): boolean {
+  return server.spec?.auth?.oauthOnly === true;
+}

package/src/resources/connect/discover.test.ts

@@ -8,8 +8,9 @@
 import { create } from "@bufbuild/protobuf";
 import { McpServerSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { localDiscover } from "./discover.js";
+import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 
 const FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-server.mjs", import.meta.url));
 const CRASH_FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-crash.mjs", import.meta.url));
@@ -20,6 +21,15 @@ function stdioSpec(scriptPath: string) {
   });
 }
 
+// A spec whose args reference ${ALLOWED_DIR}, declared under spec.env — the shape
+// the seedpack filesystem server uses (issue #141).
+function stdioSpecWithPlaceholderArg(scriptPath: string) {
+  return create(McpServerSpecSchema, {
+    serverType: { case: "stdio", value: { command: process.execPath, args: [scriptPath, "${ALLOWED_DIR}"] } },
+    env: { ALLOWED_DIR: { isSecret: false, description: "Directory the server may access" } },
+  });
+}
+
 describe("localDiscover (stdio subprocess)", () => {
   it("discovers tools and resource templates and converts them to proto", async () => {
     const caps = await localDiscover(stdioSpec(FIXTURE), [], 10_000);
@@ -43,3 +53,32 @@ describe("localDiscover (stdio subprocess)", () => {
     await expect(localDiscover(stdioSpec(CRASH_FIXTURE), [], 10_000)).rejects.toThrow(/fixture boom: missing CONFIG/);
   }, 15_000);
 });
+
+describe("localDiscover (${VAR} argument expansion — issue #141)", () => {
+  const original = process.env;
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("expands a declared ${VAR} arg from --env into the spawned subprocess", async () => {
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), ["ALLOWED_DIR=/tmp/allowed"], 10_000);
+    // The fixture echoes the argv it actually received; the resolved value must
+    // reach the subprocess, never the literal placeholder.
+    expect(caps.tools[0].description).toContain('args=["/tmp/allowed"]');
+    expect(caps.tools[0].description).not.toContain("${ALLOWED_DIR}");
+  }, 15_000);
+
+  it("expands a declared ${VAR} arg from the exported shell environment", async () => {
+    process.env = { ...original, ALLOWED_DIR: "/tmp/from-shell" };
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000);
+    expect(caps.tools[0].description).toContain('args=["/tmp/from-shell"]');
+  }, 15_000);
+
+  it("rejects with a placeholder error before spawning when the declared var is unset", async () => {
+    process.env = { ...original };
+    delete process.env.ALLOWED_DIR;
+    await expect(localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000)).rejects.toBeInstanceOf(
+      PlaceholderResolutionError,
+    );
+  }, 15_000);
+});

package/src/resources/connect/discover.ts

@@ -21,7 +21,8 @@ import {
 import type { JsonObject } from "@bufbuild/protobuf";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { mergeProcessEnv } from "../mcp/runtime-env.js";
+import { mergeProcessEnv, resolveDeclaredEnvValues } from "../mcp/runtime-env.js";
+import { resolveHeaders, resolvePlaceholders } from "../mcp/placeholder-resolver.js";
 
 /** Discover an MCP server's capabilities locally without persisting to the backend. */
 export async function localDiscover(
@@ -79,13 +80,21 @@ interface BuiltTransport {
 }
 
 async function buildTransport(spec: McpServerSpec, envOverrides: readonly string[]): Promise<BuiltTransport> {
+  // ${VAR} placeholders in args/headers resolve against the exact same env the
+  // backend hands the runner for real connect (declared keys from the OS env +
+  // --env overrides) — so dry-run is a faithful preview. Resolution is strict:
+  // an unresolved placeholder throws before any subprocess is spawned, matching
+  // the proto contract (never pass a literal "${VAR}" to the server).
+  const resolutionEnv = resolveDeclaredEnvValues(spec.env ?? {}, envOverrides);
+
   if (spec.serverType?.case === "stdio") {
     const { command, args, workingDir } = spec.serverType.value;
     if (command === "") throw new Error("stdio transport requires a command");
+    const resolvedArgs = args.map((arg, i) => resolvePlaceholders(arg, resolutionEnv, `stdio arg[${i}]`));
     const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
     const transport = new StdioClientTransport({
       command,
-      args: [...args],
+      args: resolvedArgs,
       cwd: workingDir !== "" ? workingDir : undefined,
       env: mergeProcessEnv([...envOverrides, ...goRunEnvOverrides(command, args)]),
       // "pipe" exposes the child stderr as a PassThrough immediately, so we can
@@ -104,8 +113,11 @@ async function buildTransport(spec: McpServerSpec, envOverrides: readonly string
     const { url, headers } = spec.serverType.value;
     if (url === "") throw new Error("HTTP transport requires a URL");
     const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
-    const requestInit = Object.keys(headers).length > 0 ? { headers: { ...headers } } : undefined;
-    const transport = new StreamableHTTPClientTransport(new URL(url), requestInit ? { requestInit } : undefined);
+    const resolvedHeaders = Object.keys(headers).length > 0 ? resolveHeaders(headers, resolutionEnv) : undefined;
+    const transport = new StreamableHTTPClientTransport(
+      new URL(url),
+      resolvedHeaders ? { requestInit: { headers: resolvedHeaders } } : undefined,
+    );
     return { transport, readStderr: () => "" };
   }
 

package/src/resources/mcp/placeholder-resolver.test.ts

@@ -0,0 +1,71 @@
+// Unit tests for the strict ${VAR} placeholder resolver.
+
+import { describe, expect, it } from "vitest";
+import { PlaceholderResolutionError, resolveHeaders, resolvePlaceholders } from "./placeholder-resolver.js";
+
+describe("resolvePlaceholders", () => {
+  it("returns a string with no placeholders unchanged", () => {
+    expect(resolvePlaceholders("/tmp/data.sqlite", {})).toBe("/tmp/data.sqlite");
+  });
+
+  it("resolves a single placeholder from the env map", () => {
+    expect(resolvePlaceholders("${DIR}", { DIR: "/home/me" })).toBe("/home/me");
+  });
+
+  it("resolves a placeholder embedded in surrounding text", () => {
+    expect(resolvePlaceholders("${DB_PATH}/data.sqlite", { DB_PATH: "/var/lib" })).toBe("/var/lib/data.sqlite");
+  });
+
+  it("resolves multiple and adjacent placeholders", () => {
+    expect(resolvePlaceholders("${A}${B}-${A}", { A: "x", B: "y" })).toBe("xy-x");
+  });
+
+  it("resolves to an empty string when the value is empty", () => {
+    // An empty-but-present value is a resolved value, not a missing variable.
+    expect(resolvePlaceholders("[${X}]", { X: "" })).toBe("[]");
+  });
+
+  it("ignores $VAR without braces (only ${VAR} is a placeholder)", () => {
+    expect(resolvePlaceholders("$HOME/bin", { HOME: "/root" })).toBe("$HOME/bin");
+  });
+
+  it("throws PlaceholderResolutionError for an unresolved variable, carrying name + context", () => {
+    let caught: unknown;
+    try {
+      resolvePlaceholders("${MISSING}", { OTHER: "1" }, "stdio arg[2]");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    const e = caught as PlaceholderResolutionError;
+    expect(e.variableName).toBe("MISSING");
+    expect(e.context).toBe("stdio arg[2]");
+    expect(e.message).toContain("${MISSING}");
+    expect(e.message).toContain("stdio arg[2]");
+  });
+
+  it("throws on the first unresolved variable even when others resolve", () => {
+    expect(() => resolvePlaceholders("${A}-${B}", { A: "ok" })).toThrow(PlaceholderResolutionError);
+  });
+});
+
+describe("resolveHeaders", () => {
+  it("resolves placeholders in every header value", () => {
+    const resolved = resolveHeaders(
+      { Authorization: "Bearer ${TOKEN}", "X-Static": "v1" },
+      { TOKEN: "abc123" },
+    );
+    expect(resolved).toEqual({ Authorization: "Bearer abc123", "X-Static": "v1" });
+  });
+
+  it("throws with the offending header name in the context", () => {
+    let caught: unknown;
+    try {
+      resolveHeaders({ Authorization: "Bearer ${API_KEY}" }, {});
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    expect((caught as PlaceholderResolutionError).message).toContain('header "Authorization"');
+  });
+});

package/src/resources/mcp/placeholder-resolver.ts

@@ -0,0 +1,63 @@
+// Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+//
+// The MCP server spec (StdioServerConfig.args, HttpServerConfig.headers) allows
+// values to reference declared env vars with ${VAR_NAME}. The proto contract is
+// explicit that resolution is strict: a missing variable must produce a clear
+// error rather than passing a literal "${VAR}" to the subprocess/server.
+//
+// This mirrors the runner's shared resolver (backend/services/runner/src/shared/
+// placeholder-resolver.ts) so `connect --dry-run` (which discovers locally)
+// behaves identically to real connect (which resolves on the runner). Kept
+// intentionally dependency-free and semantically identical so the two can be
+// collapsed into one shared package later without any behavior change.
+
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export class PlaceholderResolutionError extends Error {
+  constructor(
+    public readonly variableName: string,
+    public readonly context?: string,
+  ) {
+    const where = context ? ` in ${context}` : "";
+    super(
+      `Unresolved placeholder \${${variableName}}${where}: ` +
+        `variable is not present in the execution environment`,
+    );
+    this.name = "PlaceholderResolutionError";
+  }
+}
+
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(
+  template: string,
+  envVars: Record<string, string>,
+  context?: string,
+): string {
+  return template.replace(PLACEHOLDER_RE, (_match, varName: string) => {
+    if (varName in envVars) {
+      return envVars[varName];
+    }
+    throw new PlaceholderResolutionError(varName, context);
+  });
+}
+
+/**
+ * Resolve placeholders in every value of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(
+  headers: Record<string, string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+  }
+  return resolved;
+}

package/src/resources/mcp/runtime-env.test.ts

@@ -4,12 +4,18 @@ import { create } from "@bufbuild/protobuf";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { UsageError } from "../../errors/index.js";
-import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides } from "./runtime-env.js";
+import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides, resolveDeclaredEnvValues } from "./runtime-env.js";
 
 function serverWithEnv(env: Record<string, { isSecret: boolean }>) {
   return create(McpServerSchema, { metadata: { id: "mcp_1" }, spec: { env } });
 }
 
+// resolveDeclaredEnvValues takes the raw declarations map; the tests only rely on
+// keys being present, so a minimal declaration object is sufficient.
+function decls(...keys: string[]) {
+  return Object.fromEntries(keys.map((k) => [k, { isSecret: false }]));
+}
+
 describe("parseEnvOverrides", () => {
   it("parses KEY=VALUE pairs, preserving '=' in the value", () => {
     expect(parseEnvOverrides(["A=1", "B=x=y"])).toEqual({ A: "1", B: "x=y" });
@@ -66,3 +72,31 @@ describe("mergeProcessEnv", () => {
     expect(merged.NEW).toBe("1");
   });
 });
+
+describe("resolveDeclaredEnvValues", () => {
+  const original = process.env;
+  beforeEach(() => {
+    process.env = { ...original, ALLOWED_DIR: "/from-os", EMPTY_VAR: "" };
+  });
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("pulls declared keys from the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"))).toEqual({ ALLOWED_DIR: "/from-os" });
+  });
+
+  it("skips declared keys that are unset or empty in the environment", () => {
+    expect(resolveDeclaredEnvValues(decls("EMPTY_VAR", "MISSING"))).toEqual({});
+  });
+
+  it("lets --env overrides win over the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"), ["ALLOWED_DIR=/override"])).toEqual({
+      ALLOWED_DIR: "/override",
+    });
+  });
+
+  it("includes an --env override even when the key is undeclared (matches buildRuntimeEnv)", () => {
+    expect(resolveDeclaredEnvValues(decls(), ["EXTRA=1"])).toEqual({ EXTRA: "1" });
+  });
+});

package/src/resources/mcp/runtime-env.ts

@@ -36,6 +36,39 @@ export function parseEnvOverrides(overrides: readonly string[]): Record<string,
   return result;
 }
 
+/**
+ * Resolve the values behind a server's declared env vars: declared keys pulled
+ * from the OS environment (non-empty only), with `--env` overrides layered on
+ * top (override wins; an undeclared override is still included).
+ *
+ * This is the single source of truth for "which env value is in play". It backs
+ * both the runtime_env sent to the backend (buildRuntimeEnv) and the ${VAR}
+ * placeholder resolution done locally for `--dry-run` (discover.ts), so the two
+ * can never drift: dry-run resolves against the exact same map the backend hands
+ * the runner (minus platform-injected infra vars, which a local machine cannot
+ * know).
+ *
+ * `declarations` is the server's `spec.env` map; only its keys (the declared
+ * variable names) are read, so any map keyed by those names is accepted.
+ */
+export function resolveDeclaredEnvValues(
+  declarations: Record<string, unknown>,
+  envOverrides: readonly string[] = [],
+): Record<string, string> {
+  const values: Record<string, string> = {};
+
+  for (const key of Object.keys(declarations)) {
+    const value = process.env[key];
+    if (value !== undefined && value !== "") values[key] = value;
+  }
+
+  for (const [key, value] of Object.entries(parseEnvOverrides(envOverrides))) {
+    values[key] = value;
+  }
+
+  return values;
+}
+
 /**
  * Build the runtime_env map for the Connect RPC from the OS environment and the
  * supplied --env overrides. Only keys with a non-empty value are emitted.
@@ -45,17 +78,10 @@ export function buildRuntimeEnv(
   envOverrides: readonly string[] = [],
 ): Record<string, ExecutionValue> {
   const declarations = server.spec?.env ?? {};
-  const overrides = parseEnvOverrides(envOverrides);
+  const values = resolveDeclaredEnvValues(declarations, envOverrides);
   const runtime: Record<string, ExecutionValue> = {};
 
-  for (const [key, decl] of Object.entries(declarations)) {
-    const value = process.env[key];
-    if (value !== undefined && value !== "") {
-      runtime[key] = create(ExecutionValueSchema, { value, isSecret: decl.isSecret });
-    }
-  }
-
-  for (const [key, value] of Object.entries(overrides)) {
+  for (const [key, value] of Object.entries(values)) {
     runtime[key] = create(ExecutionValueSchema, { value, isSecret: declarations[key]?.isSecret ?? false });
   }