@commonlyai/cli 0.1.53 → 0.1.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/lib/adapters/codex.js

@@ -98,6 +98,11 @@ const buildPrompt = buildMemoryPreamble;
 // Codex-specific constraints:
 //   - stdio/command servers only (no url transport here); url-only entries
 //     are skipped rather than half-wired.
+//   - Only entries that DECLARE stdio (or name no transport) are emitted, even
+//     when they also carry a `command`. `auditDeclaredMcp` classifies by
+//     `transport` and never judges the command of an entry that declared an
+//     http one, so emitting it here executes a command the guard did not
+//     approve — the case Vera measured on 2026-09-18 (Connectors 69774).
 //   - Token-bearing values ride through `env_vars`, never a `-c ...env=...`
 //     argv override. Command lines are visible to other same-user processes
 //     unless the OS sandbox blocks process inspection; keeping bearer tokens
@@ -126,7 +131,9 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
   const flags = [];
   const forwardedEnv = {};
   for (const server of mcpServers || []) {
-    if (!server?.name || !Array.isArray(server.command) || !server.command.length) continue;
+    const transport = typeof server?.transport === 'string' ? server.transport.trim().toLowerCase() : 'stdio';
+    if (!server?.name || transport !== 'stdio'
+      || !Array.isArray(server.command) || !server.command.length) continue;
     const [command, ...rest] = server.command.map((a) => substitutePlaceholders(a, ctx));
     flags.push('-c', `mcp_servers.${server.name}.command=${toml(command)}`);
     // The user opted into every server present in the environment spec.

package/src/lib/adapters/pi-commonly-mcp.mjs

@@ -1,14 +1,19 @@
 /**
- * pi extension: Commonly's tools for a pi seat, over MCP stdio.
+ * pi extension: Commonly's tools for a pi seat, over MCP.
  *
  * Loaded by adapters/pi.js with `-e`. Reads COMMONLY_PI_MCP — a JSON list of
- * `{ name, command: [...], env: {...} }` — starts each server on stdio, asks
- * it for its tools, and registers every one with pi under its own name, so a
- * pi seat calls `commonly_post_message` exactly as a claude or codex seat
+ * `{ name, command: [...], env: {...} }` for stdio servers and
+ * `{ name, url, headers: {...} }` for Streamable HTTP ones — connects to each,
+ * asks it for its tools, and registers every one with pi under its own name, so
+ * a pi seat calls `commonly_post_message` exactly as a claude or codex seat
  * does. Tool calls are forwarded as MCP `tools/call`; results come back as
  * text. The client lives in pi-mcp-client.mjs (jest-tested); this file only
  * binds it to pi's `registerTool`. `typebox` resolves through pi's extension
  * loader, which aliases its bundled copy — it is not a CLI dependency.
+ *
+ * pi ships no MCP support of its own (its README: "No MCP. … build an
+ * extension that adds MCP support"), so this file is the whole transport story
+ * for a pi seat: a server that is not reachable from here is not reachable.
  */
 
 import { Type } from 'typebox';

package/src/lib/adapters/pi-mcp-client.mjs

@@ -1,15 +1,72 @@
 /**
- * A minimal MCP stdio client for the pi bridge (pi-commonly-mcp.mjs).
+ * A minimal MCP client for the pi bridge (pi-commonly-mcp.mjs), over both
+ * transports the environment spec admits: stdio (newline-delimited JSON-RPC)
+ * and Streamable HTTP.
  *
- * The stdio transport is newline-delimited JSON-RPC; a client for four
- * methods (initialize, tools/list, tools/call, the initialized notification)
- * is smaller than a dependency, and keeping it in a file with no pi imports
- * means the CLI's own jest can test it — `typebox` only resolves inside pi's
- * extension loader, so the extension file stays thin and untested by jest.
+ * A client for four methods (initialize, tools/list, tools/call, the
+ * initialized notification) is smaller than a dependency, and keeping it in a
+ * file with no pi imports means the CLI's own jest can test it — `typebox`
+ * only resolves inside pi's extension loader, so the extension file stays thin
+ * and untested by jest.
+ *
+ * pi itself has no MCP support by design (its README: "No MCP. … build an
+ * extension that adds MCP support"); this bridge IS that extension, so an
+ * HTTP MCP server reaches a pi seat only through the client below. A
+ * `url`-only entry used to be dropped by the two filters here and in pi.js,
+ * which is how a granted pi seat ended up holding the grant broker — a
+ * Streamable HTTP server — and getting nothing, silently.
  */
 
 import { spawn } from 'node:child_process';
 
+/**
+ * The grant broker's path. wren's ruling for the daemon-side half of TASK-063:
+ * pi confines on no host — `pi.js assertNoSandboxDeclared` refuses a DECLARED
+ * sandbox and nothing ever derives one — so a grant broker must not reach a pi
+ * seat by ANY route: not the server's projection (the backend refuses it there
+ * too), and not an older backend that still projects it, which is this layer's
+ * job. Keyed on the PATH and not on the entry's `name`, because the name is
+ * whatever the declaration says while the path is the broker's. A url that does
+ * not parse is not this predicate's business — the origin rule in
+ * `pi.js resolveMcpServers` refuses those before they are carried.
+ */
+export const GRANT_BROKER_PATH = '/api/mcp/grants/';
+
+/**
+ * The reason string BOTH halves of this refusal use, verbatim from the server's
+ * typed refusal (`backend/services/grantBrokerConfinement.ts`: code
+ * `grant_broker_unconfined`, reason `adapter_cannot_confine`). wren's ruling
+ * (69829): "Same reason string on both halves" — so a daemon log line and the
+ * server's `grantBrokerRefusal` field can be read side by side, and neither
+ * layer grows a vocabulary the other one does not have. Mirrored rather than
+ * imported: this package does not depend on the backend, so the literal is
+ * pinned by a test instead.
+ */
+export const GRANT_BROKER_REFUSAL = 'grant_broker_unconfined: adapter_cannot_confine';
+
+/**
+ * Is this url the instance's grant broker? Path-keyed, and the comparison is
+ * case-INSENSITIVE because the route it mirrors is: express matches paths
+ * case-insensitively unless `caseSensitive` is set, so the live API answers
+ * `/API/MCP/GRANTS/x` from the same handler as `/api/mcp/grants/x` (measured
+ * 2026-09-19: POST both → 401, POST `/api/nothing/x` → 404, i.e. the control is
+ * what distinguishes a matched route from a missing one). A case-sensitive
+ * predicate therefore refuses the spelled-canonically broker and hands pi the
+ * uppercased spelling of it — the real runtime token included. Vera measured
+ * exactly that against the running instance (69839).
+ *
+ * Case is the only spelling the router forgives: `%67rants`, `//`, `./` and
+ * `GRANTS%2F` all 404 on the live API, and a trailing slash is already inside
+ * the prefix.
+ */
+export const isGrantBrokerUrl = (url) => {
+  try {
+    return new URL(url).pathname.toLowerCase().startsWith(GRANT_BROKER_PATH);
+  } catch {
+    return false;
+  }
+};
+
 const PROTOCOL_VERSION = '2024-11-05';
 const MAX_TEXT = 50 * 1024;
 
@@ -17,8 +74,19 @@ const truncate = (text) => (text.length <= MAX_TEXT
   ? text
   : `${text.slice(0, MAX_TEXT)}\n… [truncated ${text.length - MAX_TEXT} bytes]`);
 
+/**
+ * Connect to one declared server, stdio or Streamable HTTP. `resolveMcpServers`
+ * emits exactly one of `command`/`url` per entry, and `readServers` keeps that
+ * invariant, so the shape decides; `url` wins if a hand-built entry still
+ * carries both, because a server that advertises an endpoint is not a command
+ * to spawn.
+ */
+export const connectMcp = (server, opts = {}) => (typeof server?.url === 'string' && server.url
+  ? connectHttpMcp(server, opts)
+  : connectStdioMcp(server, opts));
+
 /** A minimal MCP stdio client: initialize, tools/list, tools/call. */
-export const connectMcp = ({ name, command, env }, { spawnImpl = spawn, timeoutMs = 60_000 } = {}) => {
+export const connectStdioMcp = ({ name, command, env }, { spawnImpl = spawn, timeoutMs = 60_000 } = {}) => {
   const [cmd, ...args] = command;
   const proc = spawnImpl(cmd, args, { env: { ...process.env, ...(env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
   const pending = new Map();
@@ -71,6 +139,137 @@ export const connectMcp = ({ name, command, env }, { spawnImpl = spawn, timeoutM
   return { initialize, listTools, callTool, close, proc };
 };
 
+/**
+ * Split an SSE body into its `data:` payloads. Streamable HTTP lets a server
+ * answer a POST either with one JSON object or with an event stream holding
+ * the JSON-RPC messages, so both shapes are parsed.
+ */
+const ssePayloads = (text) => text.split(/\r?\n\r?\n/)
+  .map((block) => block.split(/\r?\n/)
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice(5).trimStart())
+    .join('\n'))
+  .filter(Boolean);
+
+const parseMessages = (text, contentType) => {
+  const body = text.trim();
+  if (!body) return [];
+  if (contentType.includes('text/event-stream')) return ssePayloads(body);
+  // A server MAY answer a request with plain JSON regardless of the request's
+  // `accept`, so the body decides before the header does.
+  if (body.startsWith('{') || body.startsWith('[')) return [body];
+  return ssePayloads(body);
+};
+
+/**
+ * A minimal MCP Streamable HTTP client: initialize, tools/list, tools/call.
+ *
+ * `headers` is where a declared `Authorization` arrives, already substituted
+ * with the seat's runtime token by the adapter. The token therefore rides in an
+ * HTTP header built from the JSON list the bridge takes out of its own
+ * environment (see takeServers) and never on argv. NOT on argv is the whole of
+ * that guarantee: deleting the variable from the bridge's own process scrubs
+ * Node's copy, not the kernel's, so a same-user child of this process can still
+ * read the parent's environment (`ps eww $PPID`, `/proc/$PPID/environ`) and find
+ * both the token and the server list. Treat this as "not in argv" and not as a
+ * secrecy boundary; the fix is to hand the list over a 0600 file the bridge
+ * unlinks on load (row filed against the bridge's env channel, Vera, Connectors).
+ */
+export const connectHttpMcp = ({ name, url, headers }, { fetchImpl = globalThis.fetch, timeoutMs = 60_000 } = {}) => {
+  if (typeof fetchImpl !== 'function') throw new Error(`${name}: no fetch implementation for the HTTP MCP transport`);
+  const declared = headers || {};
+  let nextId = 1;
+  let sessionId = null;
+  let protocolVersion = PROTOCOL_VERSION;
+  let negotiated = false;
+  const requestHeaders = () => ({
+    'content-type': 'application/json',
+    // Both, per the spec: a server may answer with JSON or with an event stream.
+    accept: 'application/json, text/event-stream',
+    ...declared,
+    ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+    // The version header follows NEGOTIATION, not the session. Our own broker is
+    // stateless (`mcpGrants.ts` sets `sessionIdGenerator: undefined`), so it
+    // never mints a session id — gating this on one meant the only broker we
+    // have never received the version it negotiated (Vera, Connectors).
+    ...(negotiated ? { 'mcp-protocol-version': protocolVersion } : {}),
+  });
+  const post = async (payload) => {
+    const controller = new AbortController();
+    let timer;
+    // Race an explicit timer as well as aborting: a client whose fetch ignores
+    // the signal must not leave a seat waiting forever on a dead endpoint.
+    const expired = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new Error(`${name}: timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+    try {
+      const res = await Promise.race([fetchImpl(url, {
+        method: 'POST',
+        headers: requestHeaders(),
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+        // These requests carry the seat token in a header. A redirect is
+        // allowed to point at another origin, and whether undici strips an
+        // Authorization header when it follows one is not something a seat may
+        // rely on — so no redirect is followed at all.
+        redirect: 'error',
+      }), expired]);
+      const text = await res.text();
+      const header = res.headers?.get?.('mcp-session-id');
+      if (header && !sessionId) sessionId = header;
+      return { res, text, contentType: res.headers?.get?.('content-type') || '' };
+    } catch (error) {
+      if (error?.message?.startsWith(`${name}:`)) throw error;
+      throw new Error(`${name}: ${error?.name === 'AbortError' ? `timed out after ${timeoutMs}ms` : `${payload?.method || 'request'} failed: ${error?.message || error}`}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  const request = async (method, params) => {
+    const id = nextId++;
+    const { res, text, contentType } = await post({ jsonrpc: '2.0', id, method, params: params || {} });
+    if (!res.ok) throw new Error(`${name}: ${method} failed with HTTP ${res.status}${text ? `: ${truncate(text)}` : ''}`);
+    const messages = parseMessages(text, contentType)
+      .map((raw) => { try { return JSON.parse(raw); } catch { return null; } })
+      .filter(Boolean);
+    const answer = messages.find((m) => m.id === id);
+    if (!answer) throw new Error(`${name}: ${method} returned no JSON-RPC answer (HTTP ${res.status})`);
+    if (answer.error) throw new Error(`${name}: ${answer.error.message || JSON.stringify(answer.error)}`);
+    return answer.result;
+  };
+  const notify = async (method, params) => {
+    const { res, text } = await post({ jsonrpc: '2.0', method, params: params || {} });
+    // The spec answers a notification with 202 and no body; anything else is
+    // an error the seat should see rather than a silent drop.
+    if (!res.ok) throw new Error(`${name}: ${method} failed with HTTP ${res.status}${text ? `: ${truncate(text)}` : ''}`);
+  };
+  const initialize = async () => {
+    const result = await request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'commonly-pi-bridge', version: '1.0.0' },
+    });
+    // The server's answer is authoritative; echo what it negotiated from here on.
+    if (result && typeof result.protocolVersion === 'string') protocolVersion = result.protocolVersion;
+    negotiated = true;
+    await notify('notifications/initialized');
+    return result;
+  };
+  const listTools = async () => (await request('tools/list')).tools || [];
+  const callTool = (toolName, args) => request('tools/call', { name: toolName, arguments: args || {} });
+  const close = () => {
+    if (!sessionId) return;
+    try {
+      const pending = fetchImpl(url, { method: 'DELETE', headers: requestHeaders(), redirect: 'error' });
+      if (pending && typeof pending.catch === 'function') pending.catch(() => {});
+    } catch { /* best effort: the session expires on its own */ }
+  };
+  return { initialize, listTools, callTool, close, sessionId: () => sessionId };
+};
+
 /** MCP `{ content, isError }` → pi tool result. Non-text parts are named, not dropped silently. */
 export const toPiResult = (result) => {
   const parts = (result?.content || []).map((c) => (c?.type === 'text' ? String(c.text ?? '') : `[${c?.type || 'content'} omitted]`));
@@ -79,11 +278,18 @@ export const toPiResult = (result) => {
 };
 
 /**
- * Read the server list and REMOVE it from the environment. The list carries each
- * server's substituted env — the seat's bearer token among it — and pi's `bash`
+ * Read the server list and REMOVE it from the environment. The list carries every
+ * server's substituted secrets — a stdio server's env and an HTTP server's
+ * `Authorization` header, the seat's bearer token among them — and pi's `bash`
  * tool spawns with `{ ...process.env }` (pi's getShellEnv), so leaving it in place
- * lets one `env` from the model print the token. The MCP children already hold
- * their own env from spawn time; nothing else reads this variable.
+ * lets one `env` from the model print the token. The clients already hold what
+ * they need from spawn time; nothing else reads this variable.
+ *
+ * What this does NOT do is hide the value from a process that reads the parent's
+ * environment directly: `delete` removes the key from this process's own copy,
+ * while the kernel keeps the copy this process was started with, so
+ * `ps eww $PPID` on macOS and `/proc/$PPID/environ` on Linux still show it to a
+ * same-user child. This closes the accidental vector, not a determined one.
  */
 export const takeServers = (env = process.env) => {
   const servers = readServers(env.COMMONLY_PI_MCP);
@@ -91,8 +297,30 @@ export const takeServers = (env = process.env) => {
   return servers;
 };
 
+/**
+ * Entries with a non-empty `command` and no `url` are stdio; entries with a
+ * non-empty `url` and no `command` are Streamable HTTP. The two are mutually
+ * exclusive on purpose: `resolveMcpServers` emits exactly one field per entry
+ * (the transport decides which), so an entry carrying BOTH did not come from it
+ * and is dropped rather than spawned — the adapter is the layer that executes,
+ * and a shape it cannot classify is not one it should run. Both the adapter
+ * (pi.js resolveMcpServers) and this filter have to agree, or a server reaches
+ * the bridge as an unstartable entry.
+ */
+export const isStdioServer = (s) => Array.isArray(s?.command) && s.command.length > 0
+  && !(typeof s?.url === 'string' && s.url.length > 0);
+export const isHttpServer = (s) => typeof s?.url === 'string' && s.url.length > 0
+  && !(Array.isArray(s?.command) && s.command.length > 0);
+
 export const readServers = (raw) => {
   if (!raw) return [];
-  try { return JSON.parse(raw).filter((s) => s?.name && Array.isArray(s.command) && s.command.length); } catch { return []; }
+  try {
+    // The broker is dropped here as well as in pi.js (same reason string, see
+    // GRANT_BROKER_REFUSAL): this is the last layer before a client is started,
+    // and the two filters have to agree or a server reaches the bridge as an
+    // entry the adapter would not have carried.
+    return JSON.parse(raw).filter((s) => s?.name
+      && (isStdioServer(s) || (isHttpServer(s) && !isGrantBrokerUrl(s.url))));
+  } catch { return []; }
 };
 

package/src/lib/adapters/pi.js

@@ -39,6 +39,7 @@ import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { buildMemoryPreamble } from '../memory-bridge.js';
+import { GRANT_BROKER_REFUSAL, isGrantBrokerUrl } from './pi-mcp-client.mjs';
 
 const DEFAULT_TIMEOUT_MS = (() => {
   const fallback = 15 * 60 * 1000;
@@ -79,14 +80,135 @@ const substitutePlaceholders = (value, ctx) => {
   return value.replace(PLACEHOLDER_RE, (whole, key) => (SUBSTITUTION_KEYS.includes(key) && subs[key] ? subs[key] : whole));
 };
 
-/** stdio MCP servers from the environment spec, placeholders filled; url-only entries are skipped. */
-export const resolveMcpServers = (mcpServers, ctx = {}) => (mcpServers || [])
-  .filter((server) => server?.name && Array.isArray(server.command) && server.command.length)
-  .map((server) => ({
-    name: server.name,
-    command: server.command.map((a) => substitutePlaceholders(a, ctx)),
-    env: Object.fromEntries(Object.entries(server.env || {}).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
-  }));
+/**
+ * The daemon's own predicate, applied verbatim: `auditDeclaredMcp` reads
+ * `server.transport || 'stdio'` and compares it as an exact string. It is
+ * deliberately not friendlier than the guard's — a normalized `'HTTP'` or a
+ * padded `' http '` is a shape the guard refuses as an unknown transport, and an
+ * adapter that accepted one would be running something the guard never judged
+ * (Vera, Connectors 69776). The schema admits `http`/`stdio`/`sse`
+ * (environment.js:236) and admits an ABSENT transport, which the guard reads as
+ * stdio; that is what this reads too.
+ */
+const transportOf = (server) => server.transport || 'stdio';
+
+const originOf = (value) => {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Declared MCP servers from the environment spec, placeholders filled. Both
+ * transports the spec admits are carried through: stdio (`command` + `env`) and
+ * Streamable HTTP (`url` + `headers`). An entry with neither is skipped — there
+ * is nothing to start.
+ *
+ * The HTTP half matters beyond a user-declared remote server: the grant broker
+ * is a Streamable HTTP server (`agentBinding.ts` grantBrokerServer), so before
+ * this pi dropped the one entry that carries a grant to a seat, silently.
+ * Filling the headers here reuses the same substitution as the stdio env, and
+ * the result rides in COMMONLY_PI_MCP — which the bridge removes from its own
+ * process environment at load (see takeServers). That closes the direct vector
+ * (pi's `bash` spawns with `{ ...process.env }`, so a bare `env` used to print
+ * the token); it is not a secrecy boundary, because deleting the variable
+ * scrubs Node's copy and not the kernel's — a same-user child of the bridge can
+ * still read this process's environment via `ps eww` / `/proc/$PPID/environ`.
+ * The durable fix is to hand the list over a 0600 file the bridge unlinks on
+ * load, which is a row against this env channel, not against this PR (Vera,
+ * Connectors).
+ *
+ * WHICH shape an entry becomes is decided by `transport` — the same field, read
+ * with the same default and the same exact comparison the daemon's
+ * `auditDeclaredMcp` judges it by — and the field that transport does not select
+ * is dropped unsent. Classifying by which field is PRESENT instead is a bypass,
+ * not a shorthand: an entry declaring `transport: 'http'` with the instance's own
+ * url passes the guard (its http rule checks only the url origin, and
+ * `${COMMONLY_AGENT_TOKEN}` in the command is one of the known placeholders), and
+ * a presence-classifier then ran that command as stdio with the real token
+ * substituted. The guard's judgement and the adapter's disagreed, and the adapter
+ * is what executes (Vera, Connectors 69774).
+ *
+ * The http half also enforces the guard's own origin rule, so the HTTP half does
+ * not depend on a guard that may not be on the machine: `auditDeclaredMcp`
+ * admits a declared http server only when its url resolves to the INSTANCE's
+ * origin, because the seat token rides its headers. Everything else — an
+ * off-instance host, an unparseable url, an instance url we do not know — is
+ * refused here as well. A transport pi cannot speak (`sse`, which the schema and
+ * the guard both admit) is refused rather than reinterpreted as one it can.
+ *
+ * The grant broker is refused outright, by PATH rather than by entry name: it is
+ * the one http entry that carries authority rather than data, and pi confines on
+ * no host. wren's ruling for TASK-063 (`isGrantBrokerUrl` in pi-mcp-client.mjs),
+ * the daemon-side half of the same refusal the server makes at the projection —
+ * this is the half that holds on deploy skew, when the row names no adapter for
+ * the server to key on, and in any backend older than the refusal.
+ *
+ * The stdio half does NOT have that property and must not be read as if it did:
+ * a declared stdio command is executed with no allowlist check, here and in both
+ * sibling adapters, so it depends entirely on the guard — `auditDeclaredMcp`
+ * admits only the shipped commonly MCP server or a command already present in the
+ * local record, and that rule exists nowhere else (Vera, 69778; TASK-069).
+ */
+export const resolveMcpServers = (mcpServers, ctx = {}) => {
+  const carried = [];
+  for (const server of mcpServers || []) {
+    if (!server?.name || typeof server.name !== 'string') continue;
+    const transport = transportOf(server);
+    if (transport === 'http') {
+      if (typeof server.url !== 'string' || !server.url) continue;
+      const url = substitutePlaceholders(server.url, ctx);
+      const origin = originOf(url);
+      const instanceOrigin = originOf(ctx.instanceUrl);
+      if (!origin || !instanceOrigin || origin !== instanceOrigin) {
+        // eslint-disable-next-line no-console
+        console.warn(`[pi] declared MCP server '${server.name}' points at ${origin || '(unparseable)'}, not this instance (${instanceOrigin || 'unknown'}) — not starting it`);
+        continue;
+      }
+      // The grant broker is the one http entry that carries AUTHORITY rather
+      // than data: a granted seat acts on external systems as the granter. A pi
+      // seat cannot be confined on any host (see assertNoSandboxDeclared), so
+      // the reach is refused here as well as at the server's projection — this
+      // layer is what holds when the backend predates that refusal, when the
+      // row names no adapter for the server to key on, or when a deploy leaves
+      // the two on different clocks.
+      if (isGrantBrokerUrl(url)) {
+        // eslint-disable-next-line no-console
+        console.warn(`[pi] ${GRANT_BROKER_REFUSAL} — refusing the grant broker '${server.name}': pi has no enforced sandbox, so this seat must not act with a granter's authority — move the seat to the claude or codex adapter, or remove the grant`);
+        continue;
+      }
+      carried.push({
+        name: server.name,
+        url,
+        headers: Object.fromEntries(Object.entries(server.headers || {}).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
+      });
+      continue;
+    }
+    if (transport === 'stdio') {
+      if (!Array.isArray(server.command) || !server.command.length) {
+        // The url-only record that names no transport lands here: the guard reads
+        // an absent transport as stdio too, and refuses it for having no command,
+        // so the daemon never adopts it and this drop matches that judgement.
+        if (typeof server.url === 'string' && server.url) {
+          // eslint-disable-next-line no-console
+          console.warn(`[pi] declared MCP server '${server.name}' names no transport, so it is judged stdio, and has no command — not starting it`);
+        }
+        continue;
+      }
+      carried.push({
+        name: server.name,
+        command: server.command.map((a) => substitutePlaceholders(a, ctx)),
+        env: Object.fromEntries(Object.entries(server.env || {}).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
+      });
+      continue;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[pi] declared MCP server '${server.name}' asks for transport '${transport}', which this adapter cannot speak — not starting it`);
+  }
+  return carried;
+};
 
 /** The provider block for models.json: the env spec's `provider` over the LiteLLM default. */
 export const resolveProvider = (environment = {}) => {