@stigmer/cli 3.1.5 → 3.1.7

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/commands/apply.ts

@@ -184,7 +184,7 @@ async function runFileApply(
     if (outcome.appliedMcpServer !== undefined) appliedMcpServers.push(outcome.appliedMcpServer);
   }
 
-  await discoverAppliedMcpServers(client.stigmer, appliedMcpServers, (line) => process.stderr.write(`${line}\n`));
+  await discoverAppliedMcpServers(client.stigmer, appliedMcpServers, org, (line) => process.stderr.write(`${line}\n`));
 }
 
 function buildAtomicGuidance(): CommandResult {

package/src/commands/connect.test.ts

@@ -0,0 +1,73 @@
+// Command-level contract for the `connect mcp-server` org guard (issue #140).
+//
+// Connecting pushes to the backend, which requires an org. Rather than let the
+// backend reject the request with the cryptic "org value length must be at least
+// 1" validation error, the command fails fast with actionable guidance — but
+// only when it is actually going to push. `--dry-run` discovers locally and must
+// stay usable with no org configured.
+//
+// Runs in standalone mode so `load()` returns the default (local, org-less)
+// config without reading the user's real config file. The guard runs before any
+// network call, so the non-dry-run case is fully deterministic and offline.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { buildProgram } from "../program.js";
+
+interface RunOutcome {
+  readonly exitCode: number;
+  readonly message: string;
+}
+
+// Runs `connect mcp-server <ref> [flags]` in standalone mode with output
+// suppressed, returning the thrown error's classified exit code and message (or
+// a success sentinel). `--standalone` is a program-global flag, so it must
+// precede the subcommand (commander's enablePositionalOptions).
+async function runConnect(ref: string, ...flags: string[]): Promise<RunOutcome> {
+  const program = buildProgram();
+  program.exitOverride();
+  const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+  const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+  try {
+    await program.parseAsync(["node", "stigmer", "--standalone", "connect", "mcp-server", ref, ...flags]);
+    return { exitCode: ExitCode.Success, message: "" };
+  } catch (err) {
+    return { exitCode: classify(err)?.exitCode ?? -1, message: err instanceof Error ? err.message : String(err) };
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+  }
+}
+
+let savedOrg: string | undefined;
+let savedApiKey: string | undefined;
+
+beforeEach(() => {
+  savedOrg = process.env.STIGMER_ORG_ID;
+  savedApiKey = process.env.STIGMER_API_KEY;
+  delete process.env.STIGMER_ORG_ID;
+  delete process.env.STIGMER_API_KEY;
+});
+
+afterEach(() => {
+  if (savedOrg === undefined) delete process.env.STIGMER_ORG_ID;
+  else process.env.STIGMER_ORG_ID = savedOrg;
+  if (savedApiKey === undefined) delete process.env.STIGMER_API_KEY;
+  else process.env.STIGMER_API_KEY = savedApiKey;
+});
+
+describe("connect mcp-server org guard", () => {
+  it("fails fast with actionable guidance when no org is set (non-dry-run)", async () => {
+    const outcome = await runConnect("mcp_test");
+    expect(outcome.message).toContain("organization not set");
+    expect(outcome.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("does not apply the org guard in dry-run mode (offline dry-run stays usable)", async () => {
+    // Dry-run skips the push, so the guard must not fire even with no org. The
+    // command proceeds past the guard and fails later for an unrelated reason
+    // (no reachable backend) — never with the org guidance error.
+    const outcome = await runConnect("mcp_test", "--dry-run");
+    expect(outcome.message).not.toContain("organization not set");
+  });
+});

package/src/commands/connect.ts

@@ -49,6 +49,20 @@ async function runConnect(reference: string, options: ConnectFlags, command: Com
   ensureAuthenticated(client.config);
   const org = resolveOrganization(client.config, globalOrg(command));
 
+  // Connecting pushes to the backend, which requires an org for credential
+  // resolution. Fail with actionable guidance instead of the backend's cryptic
+  // "org value length must be at least 1" validation error. Dry-run discovers
+  // locally (no backend push) and needs no org for an id reference, so it is
+  // exempt — mirrors the org guard in run/draft/resume.
+  if (options.dryRun !== true && org === "") {
+    throw new UsageError(
+      "organization not set\n\n" +
+        "Set it with:\n" +
+        "  stigmer config context set --org <org>\n" +
+        "  stigmer connect mcp-server <server> --org <org>",
+    );
+  }
+
   const result = await connectMcpServer(client.stigmer, {
     reference,
     org,

package/src/resources/apply/declarative.ts

@@ -311,7 +311,7 @@ export async function reconcileProjectMembers(
     }
   }
 
-  await discoverAppliedMcpServers(deps.stigmer, appliedMcpServers, deps.info);
+  await discoverAppliedMcpServers(deps.stigmer, appliedMcpServers, deps.org, deps.info);
 
   injectOrg(project, deps.org);
   if (project.spec === undefined) project.spec = create(ProjectSpecSchema, {});

package/src/resources/apply/discovery.integration.test.ts

@@ -0,0 +1,99 @@
+// In-process integration test for post-apply MCP discovery.
+//
+// Stands up a Connect backend serving McpServerCommandController.connect, points
+// an SDK node client at it, and drives discoverAppliedMcpServers. The mock
+// mirrors the backend's protovalidate rule (org min_len=1) by rejecting an empty
+// org, so a regression that drops org from ConnectInput is caught here rather
+// than silently passing (issue #140: the CLI used to omit org entirely).
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import type { ConnectInput } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { discoverAppliedMcpServers } from "./discovery.js";
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+let connectCalls: ConnectInput[] = [];
+
+beforeEach(() => {
+  connectCalls = [];
+});
+
+// A stdio MCP server with no env declarations, so discovery does not skip it and
+// buildRuntimeEnv stays empty (no local process needed — connect is mocked).
+function stdioServer(id: string, org: string) {
+  return create(McpServerSchema, {
+    metadata: { id, name: id, slug: id, org },
+    spec: { serverType: { case: "stdio", value: { command: "noop" } } },
+  });
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(McpServerCommandController, {
+      connect: (req) => {
+        if (req.org === "") {
+          throw new ConnectError("org – value length must be at least 1 characters", Code.InvalidArgument);
+        }
+        connectCalls.push(req);
+        return create(McpServerSchema, { metadata: { id: req.mcpServerId } });
+      },
+    });
+  };
+
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+  client = createNodeClient({ baseUrl: normalizeEndpoint(`127.0.0.1:${port}`) });
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("discoverAppliedMcpServers", () => {
+  it("forwards the resolved org on ConnectInput for each applied stdio server", async () => {
+    const lines: string[] = [];
+    await discoverAppliedMcpServers(client, [stdioServer("mcp_1", "acme")], "acme", (l) => lines.push(l));
+
+    expect(connectCalls).toHaveLength(1);
+    expect(connectCalls[0].mcpServerId).toBe("mcp_1");
+    expect(connectCalls[0].org).toBe("acme");
+    expect(lines.join("\n")).toContain("Discovered capabilities for mcp_1");
+  });
+
+  it("surfaces the backend's org validation as a per-server warning when org is empty (regression guard)", async () => {
+    const lines: string[] = [];
+    await discoverAppliedMcpServers(client, [stdioServer("mcp_1", "acme")], "", (l) => lines.push(l));
+
+    // Best-effort: an empty org must never crash the apply — it degrades to a
+    // warning. This proves the mock (and thus the backend) rejects empty org, so
+    // the happy-path org assertion above is a real guard, not a tautology.
+    expect(connectCalls).toHaveLength(0);
+    expect(lines.join("\n")).toContain("Discovery failed for mcp_1");
+  });
+
+  it("skips non-stdio servers without calling connect", async () => {
+    const httpServer = create(McpServerSchema, {
+      metadata: { id: "mcp_http", name: "http", slug: "http", org: "acme" },
+      spec: { serverType: { case: "http", value: { url: "https://example.com/mcp" } } },
+    });
+    await discoverAppliedMcpServers(client, [httpServer], "acme");
+    expect(connectCalls).toHaveLength(0);
+  });
+});

package/src/resources/apply/discovery.ts

@@ -15,10 +15,18 @@ import { buildRuntimeEnv } from "../mcp/runtime-env.js";
 /** A sink for human progress/warning lines (discovery output is not parity). */
 export type DiscoverySink = (line: string) => void;
 
-/** Connect each applied stdio MCP server to trigger capability discovery. */
+/**
+ * Connect each applied stdio MCP server to trigger capability discovery.
+ *
+ * `org` is the resolved apply organization. The backend requires it on every
+ * ConnectInput, and it is guaranteed non-empty here: `applyMessage` injects org
+ * into each resource and the backend rejects an org-less MCP server apply, so
+ * any server that reached `servers` was applied under this org.
+ */
 export async function discoverAppliedMcpServers(
   client: Stigmer,
   servers: readonly McpServer[],
+  org: string,
   sink?: DiscoverySink,
 ): Promise<void> {
   if (servers.length === 0) return;
@@ -40,6 +48,7 @@ export async function discoverAppliedMcpServers(
       await client.mcpServer.connect(
         create(ConnectInputSchema, {
           mcpServerId: server.metadata?.id ?? "",
+          org,
           runtimeEnv: buildRuntimeEnv(server),
         }),
       );

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

@@ -6,7 +6,7 @@
 // guidance gate, and the dry-run path (local discovery, no Connect RPC).
 
 import { create } from "@bufbuild/protobuf";
-import type { ConnectRouter } from "@connectrpc/connect";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
@@ -69,7 +69,14 @@ beforeAll(async () => {
       getOAuthGrantStatus: () => create(GetOAuthGrantStatusOutputSchema, { connected: grantConnected }),
     });
     router.service(McpServerCommandController, {
-      connect: (req) => (connectCalls.push(req), updatedServer),
+      // Mirror the backend's protovalidate rule (org min_len=1): reject an empty
+      // org so a regression that drops org fails loudly here instead of silently
+      // passing (the mock adapter does not run protovalidate on its own).
+      connect: (req) => {
+        if (req.org === "") throw new ConnectError("org – value length must be at least 1 characters", Code.InvalidArgument);
+        connectCalls.push(req);
+        return updatedServer;
+      },
     });
   };
 
@@ -102,6 +109,9 @@ describe("connect push path", () => {
 
     expect(connectCalls).toHaveLength(1);
     expect(connectCalls[0].mcpServerId).toBe("mcp_1");
+    // The org resolved by the command must ride along on ConnectInput — the
+    // backend requires it (issue #140: the CLI used to drop it entirely).
+    expect(connectCalls[0].org).toBe("acme");
     expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.value).toBe("ghp-override");
     expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.isSecret).toBe(true);
 
@@ -158,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, {
@@ -182,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);
@@ -56,6 +69,7 @@ export async function connectMcpServer(client: Stigmer, opts: ConnectOptions): P
   const updated = await client.mcpServer.connect(
     create(ConnectInputSchema, {
       mcpServerId: server.metadata?.id ?? "",
+      org: opts.org,
       runtimeEnv: buildRuntimeEnv(server, opts.envOverrides),
     }),
   );
@@ -76,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, {
@@ -86,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;
+}