pi-mcp-adapter 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-07-25
+
+### Added
+- Added native `rmcp-mux` Unix-socket connections for explicitly sharing external MCP server processes across Pi sessions. Thanks j0e1 (@pWoLiAn) for issue #76.
+- Added connection-time command resolution for HTTP bearer tokens and headers, OAuth client secrets, and stdio environment values, with `!!` escaping and fail-closed execution. Thanks @estrizhok for issue #221.
+
+### Fixed
+- Treated null optional server URLs as absent and cleaned unpublished runtimes after initialization failures, preventing `not_initialized` sessions with surviving MCP children. Thanks @autopeasant for the diagnosis in issue #222.
+- Registered env-selected direct MCP tools before child `agent_start` when their metadata cache must be populated first. Thanks @peedrr for the original report in pi-subagents issue #638 and issue #219.
+
+## [2.14.0] - 2026-07-25
+
+### Added
+- Added the global `settings.showStatusIcon` opt-out for plain `MCP: ...` status and connection text while keeping the plug icon enabled by default. Thanks @vaultboy001 for issue #216.
+
+### Fixed
+- Deferred implicit OAuth credential-store access until an HTTP server actually challenges for authentication, so unauthenticated remote Streamable HTTP servers work in headless environments. Thanks @vdom-1 for issue #218.
+- Accepted draft-07 tool output schemas alongside JSON Schema 2020-12 while preserving structured-content validation. Thanks Daniel Marbach (@danielmarbach) for issue #217.
+
 ## [2.13.0] - 2026-07-25
 
 ### Added

package/README.md

@@ -172,21 +172,22 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 
 | Field | Description |
 |-------|-------------|
-| `command` | Executable for stdio transport |
+| `command` | Executable for stdio transport; mutually exclusive with `url` and `socket` |
 | `args` | Command arguments |
-| `env` | Environment variables; supports `${VAR}` and `$env:VAR` interpolation |
+| `socket` | Explicit `rmcp-mux` Unix-domain socket path; supports `${VAR}`, `$env:VAR`, and `~` expansion and is mutually exclusive with `command` and `url` |
+| `env` | Environment variables; supports `${VAR}` and `$env:VAR` interpolation. A value beginning with `!` runs a command when the stdio server connects; use `!!` for a literal leading `!`. |
 | `cwd` | Working directory; supports `${VAR}`, `$env:VAR`, and `~` expansion |
 | `url` | HTTP endpoint (StreamableHTTP with SSE fallback); supports raw `${VAR}` and `$env:VAR` interpolation, and missing URL variables fail before any request is sent |
-| `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation |
+| `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation. A value beginning with `!` runs a command when the HTTP server connects or OAuth authenticates; use `!!` for a literal leading `!`. |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
 | `oauth.clientId` | Pre-registered OAuth client ID; dynamic registration is used when omitted |
-| `oauth.clientSecret` | OAuth client secret for confidential clients |
+| `oauth.clientSecret` | OAuth client secret for confidential clients; a value beginning with `!` runs a command when OAuth authenticates, while `!!` escapes a literal leading `!` |
 | `oauth.scope` | Requested OAuth scopes |
 | `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
 | `oauth.clientName` | Client display name advertised during dynamic registration |
 | `oauth.clientUri` | Client homepage URI advertised during dynamic registration |
-| `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation |
+| `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation. A leading `!` in `bearerToken` runs a command when the HTTP server connects; use `!!` for a literal leading `!`. |
 | `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, or `"lazy-keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
 | `requestTimeoutMs` | Request timeout in milliseconds for live MCP calls (overrides global; if omitted or `<= 0`, the MCP SDK default timeout is used) |
@@ -200,6 +201,24 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
 
+Secret values in `headers`, `bearerToken`, `oauth.clientSecret`, and stdio `env` may use a leading `!command` to obtain their value at connection or authentication time. The command runs with stdin and stderr suppressed, stdout is limited to 1 MiB and trimmed, and it must finish within 10 seconds with non-empty output; failures stop the connection or authentication flow. Commands are not run during OAuth discovery or while reading, merging, previewing, hashing, or rendering configuration. Use `!!` to escape a literal leading `!`; ordinary and escaped values retain environment interpolation.
+
+### Shared MCP processes with rmcp-mux
+
+To share one stdio MCP server across Pi sessions, run it under [`rmcp-mux`](https://github.com/VetCoders/rmcp-mux) and point each session at the service socket:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "socket": "~/.rmcp-servers/rmcp-mux/sockets/memory.sock"
+    }
+  }
+}
+```
+
+The adapter owns only its client socket and closes that connection when the Pi runtime stops. `rmcp-mux` owns the upstream process, request routing, initialization cache, restart policy, client limits, and socket permissions. Start and configure the mux separately; the adapter never discovers, starts, adopts, or stops its daemon. A socket is an explicit trusted local endpoint, so do not point unrelated projects or users at a mux service unless its tools, state, credentials, and filesystem access are intended to be shared.
+
 ### Remote/headless OAuth
 
 If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable:
@@ -237,6 +256,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "toolPrefix": "server",
     "idleTimeout": 10,
     "requestTimeoutMs": 30000,
+    "showStatusIcon": true,
     "hostConfigDiscovery": "off",
     "oauthDir": ".pi/mcp-oauth",
     "trace": {
@@ -255,6 +275,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `toolPrefix` | `"server"` (default), `"short"` (strips `-mcp` suffix), `"none"`, or `"mcp"` (prefixes with `mcp__`, using server-mode normalization) |
 | `idleTimeout` | Global idle timeout in minutes (default: 10, 0 to disable) |
 | `requestTimeoutMs` | Global request timeout in milliseconds for live MCP calls (if omitted or `<= 0`, the MCP SDK default timeout is used) |
+| `showStatusIcon` | Show the plug icon in MCP status and connection text (default: `true`). Set to `false` for plain `MCP: ...` text. |
 | `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
@@ -522,6 +543,10 @@ If `settings.autoAuth` is `true`, `mcp({ connect: ... })`, `mcp({ tool: ... })`,
 
 In interactive sessions, you can also authenticate from `/mcp` with `ctrl+a` or Enter on a server that needs auth. In remote/headless sessions, use the proxy tool's `auth-start` and `auth-complete` actions to copy the authorization URL locally and paste the redirect URL back into Pi. `/mcp-auth` without a server only opens a picker in the interactive UI.
 
+### MCP output schemas
+
+Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12. Unstamped schemas use the SDK's 2020-12 default. Returned `structuredContent` is validated against the advertised schema for both proxy and direct-tool calls.
+
 ## How It Works
 
 - One `mcp` tool in context (~200 tokens) instead of hundreds

package/config.ts

@@ -409,8 +409,20 @@ function mergeServerMaps(
     // applies (it is spread last). Behaviour is unchanged when the url is
     // identical or the override omits `url` (partial overrides still inherit).
     let baseEntry: ServerEntry = existing ?? {};
-    if (existing && typeof definition.url === "string" && definition.url !== existing.url) {
+    if (existing && typeof definition.socket === "string") {
+      baseEntry = { ...existing };
+      for (const field of [
+        "command", "args", "env", "cwd", "url", "headers", "auth",
+        "bearerToken", "bearerTokenEnv", "oauth",
+      ] as const) {
+        delete baseEntry[field];
+      }
+    } else if (existing?.socket && (typeof definition.command === "string" || typeof definition.url === "string")) {
       baseEntry = { ...existing };
+      delete baseEntry.socket;
+    }
+    if (existing && typeof definition.url === "string" && definition.url !== existing.url) {
+      if (baseEntry === existing) baseEntry = { ...existing };
       for (const field of URL_BOUND_AUTH_FIELDS) {
         delete baseEntry[field];
       }

package/direct-tools.ts

@@ -5,7 +5,7 @@ import type { DirectToolSpec, McpConfig, McpContent, ToolPrefix } from "./types.
 import type { MetadataCache } from "./metadata-cache.ts";
 import { lazyConnect, getFailureAgeSeconds, clearFailure } from "./init.ts";
 import { abortable, throwIfAborted } from "./abort.ts";
-import { isServerCacheValid } from "./metadata-cache.ts";
+import { isServerCacheValid, parseDirectToolSelectors } from "./metadata-cache.ts";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.ts";
 import { formatSchema } from "./tool-metadata.ts";
 import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.ts";
@@ -114,25 +114,7 @@ export function resolveDirectTools(
 
   const seenNames = new Set<string>();
 
-  const envServers = new Set<string>();
-  const envTools = new Map<string, Set<string>>();
-  if (envOverride) {
-    for (let item of envOverride) {
-      item = item.replace(/\/+$/, "");
-      if (item.includes("/")) {
-        const [server, tool] = item.split("/", 2);
-        if (server && tool) {
-          if (!envTools.has(server)) envTools.set(server, new Set());
-          envTools.get(server)!.add(tool);
-        } else if (server) {
-          envServers.add(server);
-        }
-      } else if (item) {
-        envServers.add(item);
-      }
-    }
-  }
-
+  const envSelection = envOverride ? parseDirectToolSelectors(envOverride) : null;
   const globalDirect = config.settings?.directTools;
 
   for (const [serverName, definition] of Object.entries(config.mcpServers)) {
@@ -142,11 +124,11 @@ export function resolveDirectTools(
 
     let toolFilter: true | string[] | false = false;
 
-    if (envOverride) {
-      if (envServers.has(serverName)) {
+    if (envSelection) {
+      if (envSelection.servers.has(serverName)) {
         toolFilter = true;
-      } else if (envTools.has(serverName)) {
-        toolFilter = [...envTools.get(serverName)!];
+      } else if (envSelection.tools.has(serverName)) {
+        toolFilter = [...envSelection.tools.get(serverName)!];
       }
     } else {
       if (definition.directTools !== undefined) {

package/index.ts

@@ -254,7 +254,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     type: "string",
   });
 
-  function startInitialization(ctx: ExtensionContext, owner: McpRuntimeOwner, oauthRuntime: McpOAuthRuntime, generation: number, staleReason: string): void {
+  function startInitialization(ctx: ExtensionContext, owner: McpRuntimeOwner, oauthRuntime: McpOAuthRuntime, generation: number, staleReason: string): Promise<void> {
     const promise = initializeMcp(pi, ctx, owner, {
       ...(programmaticConfig || options.configPath !== undefined
         ? { configPath: earlyConfigPath, config: sessionConfig }
@@ -264,7 +264,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     });
     initPromise = promise;
 
-    promise.then(async (nextState) => {
+    return promise.then(async (nextState) => {
       if (!owner.isActive() || generation !== lifecycleGeneration || initPromise !== promise) {
         try {
           await shutdownState(nextState, staleReason);
@@ -284,7 +284,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       syncToolSurface(ctx);
       updateStatusBar(nextState);
       initPromise = null;
-    }).catch(err => {
+    }).catch(async err => {
       if (!owner.isActive() || generation !== lifecycleGeneration) {
         return;
       }
@@ -293,6 +293,16 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
       console.error(`MCP initialization failed: ${formatTerminalError(err)}`);
       initPromise = null;
+      if (state) return;
+
+      try {
+        await Promise.all([
+          owner.stop("MCP initialization failed"),
+          shutdownOAuth(oauthRuntime),
+        ]);
+      } catch (error) {
+        console.error(`MCP: failed to clean rejected initialization: ${formatTerminalError(error)}`);
+      }
     });
   }
 
@@ -347,7 +357,17 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
     if (generation !== lifecycleGeneration || !owner.isActive()) return;
 
-    startInitialization(ctx, owner, oauthRuntime, generation, "stale_session_start");
+    const initialization = startInitialization(ctx, owner, oauthRuntime, generation, "stale_session_start");
+    if (envRaw !== undefined && envRaw !== "__none__") {
+      const missingEnvDirectTools = getMissingConfiguredDirectToolServers(
+        earlyConfig,
+        loadMetadataCache(),
+        envDirectToolOverride,
+      );
+      if (missingEnvDirectTools.length > 0) {
+        await initialization;
+      }
+    }
   });
 
   pi.on("session_shutdown", async () => {
@@ -726,7 +746,11 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   }
 
   function syncProxyTool(config: McpConfig, cache: MetadataCache | null, directSpecs: DirectToolSpec[]): void {
-    const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(config, cache);
+    const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(
+      config,
+      cache,
+      envRaw === undefined || envRaw === "__none__" ? undefined : envDirectToolOverride,
+    );
     const shouldRegisterProxyTool =
       config.settings?.disableProxyTool !== true
       || directSpecs.length === 0

package/init.ts

@@ -22,7 +22,7 @@ import {
 import { McpServerManager } from "./server-manager.ts";
 import { buildToolMetadata, totalToolCount } from "./tool-metadata.ts";
 import { UiResourceHandler } from "./ui-resource-handler.ts";
-import { openUrl, parallelLimit, sanitizeTerminalText } from "./utils.ts";
+import { formatMcpStatus, openUrl, parallelLimit, sanitizeTerminalText } from "./utils.ts";
 import { logger } from "./logger.ts";
 import { throwIfAborted } from "./abort.ts";
 import { getAuthStorageOptions } from "./mcp-auth.ts";
@@ -261,7 +261,7 @@ export async function initializeMcp(
       });
 
   if (ui && startupServers.length > 0) {
-    ui.setStatus("mcp", `🔌 MCP: connecting to ${startupServers.length} servers...`);
+    ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${startupServers.length} servers...`));
   }
 
   const results = await parallelLimit(startupServers, 10, async ([name, definition]) => {
@@ -334,7 +334,8 @@ export async function initializeMcp(
   const envDirect = process.env.MCP_DIRECT_TOOLS;
   if (envDirect !== "__none__") {
     const currentCache = loadMetadataCache();
-    const missingCacheServers = getMissingConfiguredDirectToolServers(config, currentCache);
+    const envDirectToolOverride = envDirect?.split(",").map(selector => selector.trim()).filter(Boolean);
+    const missingCacheServers = getMissingConfiguredDirectToolServers(config, currentCache, envDirectToolOverride);
 
     if (missingCacheServers.length > 0) {
       const bootstrapResults = await parallelLimit(
@@ -523,10 +524,11 @@ export function updateStatusBar(state: McpExtensionState): void {
     const definition = state.config.mcpServers[name];
     return connection.status === "connected" && definition !== undefined && !isServerDisabled(definition);
   }).length;
-  let status = `🔌 MCP: ${enabledCount} ${enabledCount === 1 ? "server" : "servers"} enabled`;
+  let status = `${enabledCount} ${enabledCount === 1 ? "server" : "servers"} enabled`;
   if (connectedCount > 0) status += ` (${connectedCount} connected)`;
   if (disabledCount > 0) status += ` (${disabledCount} disabled)`;
-  ui.setStatus("mcp", ui.theme ? ui.theme.fg("accent", status) : status);
+  const formattedStatus = formatMcpStatus(state.config, status);
+  ui.setStatus("mcp", ui.theme ? ui.theme.fg("accent", formattedStatus) : formattedStatus);
 }
 
 export function getFailureAgeSeconds(state: McpExtensionState, serverName: string): number | null {
@@ -563,7 +565,7 @@ export async function lazyConnect(state: McpExtensionState, serverName: string,
 
   try {
     if (state.ui) {
-      state.ui.setStatus("mcp", `🔌 MCP: connecting to ${serverName}...`);
+      state.ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
     }
     const newConnection = await state.manager.connect(serverName, definition, ownedSignal);
     if (newConnection.status === "needs-auth") {

package/json-schema-validator.ts

@@ -0,0 +1,55 @@
+import {
+  Ajv,
+  AjvJsonSchemaValidator,
+  addFormats,
+} from "@modelcontextprotocol/client/validators/ajv";
+import type {
+  JsonSchemaType,
+  JsonSchemaValidator,
+  jsonSchemaValidator as JsonSchemaValidatorProvider,
+} from "@modelcontextprotocol/client";
+
+type SchemaDialect =
+  | { status: "unstamped" }
+  | { status: "stamped"; uri: string };
+
+const DRAFT_07_SCHEMA_URIS: ReadonlySet<string> = new Set([
+  "http://json-schema.org/draft-07/schema",
+  "https://json-schema.org/draft-07/schema",
+]);
+
+function schemaDialect(schema: JsonSchemaType): SchemaDialect {
+  if (!("$schema" in schema) || typeof schema.$schema !== "string") {
+    return { status: "unstamped" };
+  }
+  return {
+    status: "stamped",
+    uri: schema.$schema.endsWith("#") ? schema.$schema.slice(0, -1) : schema.$schema,
+  };
+}
+
+export function createJsonSchemaValidator(): JsonSchemaValidatorProvider {
+  const defaultValidator = new AjvJsonSchemaValidator();
+  let draft07Validator: AjvJsonSchemaValidator | undefined;
+
+  return {
+    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+      const dialect = schemaDialect(schema);
+      if (dialect.status !== "stamped" || !DRAFT_07_SCHEMA_URIS.has(dialect.uri)) {
+        return defaultValidator.getValidator<T>(schema);
+      }
+
+      draft07Validator ??= (() => {
+        const ajv = new Ajv({
+          strict: false,
+          validateFormats: true,
+          validateSchema: false,
+          allErrors: true,
+        });
+        addFormats(ajv);
+        return new AjvJsonSchemaValidator(ajv);
+      })();
+      return draft07Validator.getValidator<T>(schema);
+    },
+  };
+}

package/mcp-auth-flow.ts

@@ -154,7 +154,10 @@ export function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
   }
   if (definition.oauth?.clientSecret !== undefined) {
     if (typeof definition.oauth.clientSecret !== "string") throw new Error("OAuth clientSecret must be a string")
-    config.clientSecret = interpolateEnvVars(definition.oauth.clientSecret)
+    // Preserve command expressions for the provider; interpolation remains eager for ordinary values.
+    config.clientSecret = definition.oauth.clientSecret.startsWith("!")
+      ? definition.oauth.clientSecret
+      : interpolateEnvVars(definition.oauth.clientSecret)
   }
   if (definition.oauth?.scope !== undefined) {
     if (typeof definition.oauth.scope !== "string") throw new Error("OAuth scope must be a string")
@@ -194,13 +197,18 @@ export function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
 }
 
 async function probeAuthDiscovery(serverUrl: string, definition?: ServerEntry, signal?: AbortSignal): Promise<AuthDiscovery> {
+  // Discovery must not execute config commands or send their source text.
+  const discoveryHeaders = definition?.headers
+    ? Object.fromEntries(Object.entries(definition.headers).filter(([, value]) => !value.startsWith("!") || value.startsWith("!!")))
+    : undefined
+  const headers = new Headers(interpolateEnvRecord(discoveryHeaders))
+  headers.set("content-type", "application/json")
+
   const controller = new AbortController()
   const discoverySignal = combineAbortSignals(signal, controller.signal)
   const timer = setTimeout(() => controller.abort(), 5000)
 
   try {
-    const headers = new Headers(interpolateEnvRecord(definition?.headers))
-    headers.set("content-type", "application/json")
     headers.set("accept", "application/json, text/event-stream")
 
     const response = await fetch(new URL(serverUrl), {

package/mcp-oauth-provider.ts

@@ -26,6 +26,7 @@ import {
   type StoredTokens,
   type StoredClientInfo,
 } from "./mcp-auth.ts"
+import { resolveCommandSecret } from "./utils.ts"
 
 // Callback server configuration
 const DEFAULT_OAUTH_CALLBACK_PORT = 19876
@@ -169,9 +170,15 @@ export class McpOAuthProvider implements OAuthClientProvider {
       // this pre-registered client with one.
       const stored = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
       const issuer = stored?.clientInfo?.clientId === this.config.clientId ? stored.clientInfo.issuer : undefined
+      const clientSecret = this.config.clientSecret?.startsWith("!")
+        ? resolveCommandSecret(
+          this.config.clientSecret,
+          `MCP server "${this.serverName}" OAuth clientSecret`,
+        )
+        : this.config.clientSecret
       return {
         client_id: this.config.clientId,
-        client_secret: this.config.clientSecret,
+        client_secret: clientSecret,
         ...(issuer !== undefined ? { issuer } : {}),
       }
     }

package/mcp-trace.ts

@@ -9,7 +9,7 @@ export const DEFAULT_MCP_TRACE_MAX_BYTES = 256 * 1024;
 export const DEFAULT_MCP_TRACE_MAX_EVENTS = 10_000;
 
 export type McpTraceDirection = "outbound" | "inbound";
-export type McpTraceTransport = "stdio" | "sse" | "streamable-http" | "unknown";
+export type McpTraceTransport = "stdio" | "unix-socket" | "sse" | "streamable-http" | "unknown";
 export type McpTraceMessageKind = "request" | "response" | "notification";
 
 export interface McpTraceSettings {
@@ -301,8 +301,9 @@ export function wrapTransportWithMcpTrace<T extends Transport>(
   return traced as T;
 }
 
-export function traceTransportKind(definition: { command?: string; url?: string }, transport: Transport): McpTraceTransport {
+export function traceTransportKind(definition: { command?: string; url?: string; socket?: string }, transport: Transport): McpTraceTransport {
   if (definition.command) return "stdio";
+  if (definition.socket) return "unix-socket";
   const constructorName = transport.constructor?.name.toLowerCase() ?? "";
   if (constructorName.includes("sse")) return "sse";
   if (constructorName.includes("streamable")) return "streamable-http";

package/metadata-cache.ts

@@ -84,6 +84,7 @@ export function computeServerHash(definition: ServerEntry): string {
   const identity: Record<string, unknown> = {
     command: definition.command,
     args: definition.args,
+    socket: resolveConfigPath(definition.socket),
     env: interpolateEnvRecord(definition.env),
     cwd: resolveConfigPath(definition.cwd),
     url: resolveServerUrl(definition),
@@ -116,18 +117,48 @@ export function isServerCacheValid(
   return true;
 }
 
+export function parseDirectToolSelectors(selectors: string[]): {
+  servers: Set<string>;
+  tools: Map<string, Set<string>>;
+} {
+  const servers = new Set<string>();
+  const tools = new Map<string, Set<string>>();
+
+  for (let selector of selectors) {
+    selector = selector.replace(/\/+$/, "");
+    if (selector.includes("/")) {
+      const [server, tool] = selector.split("/", 2);
+      if (server && tool) {
+        const serverTools = tools.get(server) ?? new Set<string>();
+        serverTools.add(tool);
+        tools.set(server, serverTools);
+      } else if (server) {
+        servers.add(server);
+      }
+    } else if (selector) {
+      servers.add(selector);
+    }
+  }
+
+  return { servers, tools };
+}
+
 export function getMissingConfiguredDirectToolServers(
   config: McpConfig,
   cache: MetadataCache | null,
+  envOverride?: string[],
 ): string[] {
   const missing: string[] = [];
   const globalDirect = config.settings?.directTools;
+  const envSelection = envOverride ? parseDirectToolSelectors(envOverride) : null;
 
   for (const [serverName, definition] of Object.entries(config.mcpServers)) {
     if (isServerDisabled(definition)) continue;
-    const hasDirectTools = definition.directTools !== undefined
-      ? !!definition.directTools
-      : !!globalDirect;
+    const hasDirectTools = envSelection
+      ? envSelection.servers.has(serverName) || envSelection.tools.has(serverName)
+      : definition.directTools !== undefined
+        ? !!definition.directTools
+        : !!globalDirect;
 
     if (!hasDirectTools) continue;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -75,6 +75,8 @@
     "ui-stream-types.ts",
     "config.ts",
     "server-manager.ts",
+    "unix-socket-transport.ts",
+    "json-schema-validator.ts",
     "session-recovery.ts",
     "sampling-handler.ts",
     "elicitation-handler.ts",

package/proxy-modes.ts

@@ -12,7 +12,7 @@ import { reconstructPromptMetadata } from "./metadata-cache.ts";
 import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
-import { formatAuthRequiredMessage, resolveServerUrl, truncateAtWord } from "./utils.ts";
+import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 
@@ -663,7 +663,7 @@ export async function executeConnect(state: McpExtensionState, serverName: strin
 
   try {
     if (state.ui) {
-      state.ui.setStatus("mcp", `🔌 MCP: connecting to ${serverName}...`);
+      state.ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
     }
     const currentConnection = state.manager.getConnection(serverName);
     let connection = currentConnection?.status === "connected"
@@ -948,7 +948,7 @@ export async function executeCall(
 
     try {
       if (state.ui) {
-        state.ui.setStatus("mcp", `🔌 MCP: connecting to ${serverName}...`);
+        state.ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
       }
       connection = await state.manager.connect(serverName, definition, ownedSignal);
       if (connection.status === "needs-auth") {

package/server-manager.ts

@@ -2,12 +2,14 @@ import {
   Client,
   SSEClientTransport,
   StreamableHTTPClientTransport,
+  SdkHttpError,
   UnauthorizedError,
   type RequestOptions,
   type ReadResourceResult,
   type UrlElicitationRequiredError,
 } from "@modelcontextprotocol/client";
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { UnixSocketClientTransport } from "./unix-socket-transport.ts";
 import {
   isServerDisabled,
   type McpTool,
@@ -20,6 +22,7 @@ import {
 } from "./types.ts";
 import { SERVER_STREAM_RESULT_PATCH_METHOD, serverStreamResultPatchNotificationSchema } from "./types.ts";
 import { resolveNpxBinary } from "./npx-resolver.ts";
+import { createJsonSchemaValidator } from "./json-schema-validator.ts";
 import { logger } from "./logger.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
 import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
@@ -30,7 +33,13 @@ import {
   registerElicitationHandler,
   type ServerElicitationConfig,
 } from "./elicitation-handler.ts";
-import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath, resolveServerUrl } from "./utils.ts";
+import {
+  resolveBearerToken,
+  resolveCommandSecret,
+  resolveCommandSecretsRecord,
+  resolveConfigPath,
+  resolveServerUrl,
+} from "./utils.ts";
 import { abortable, throwIfAborted } from "./abort.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import {
@@ -50,6 +59,16 @@ const MCP_CLIENT_OPTIONS = {
 };
 const abortCleanupPromises = new WeakMap<object, Promise<void>>();
 
+type HttpAuthProviderState =
+  | { status: "disabled" }
+  | { status: "implicit-deferred" }
+  | { status: "explicit"; provider: McpOAuthProvider }
+  | { status: "implicit-challenged"; provider: McpOAuthProvider };
+
+function isUnauthorizedHttpError(error: unknown): boolean {
+  return error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401);
+}
+
 function boundedStderrChunk(chunk: Buffer | string): Buffer {
   if (Buffer.isBuffer(chunk)) {
     const start = Math.max(0, chunk.byteLength - MAX_CAPTURED_STDERR_BYTES);
@@ -296,6 +315,11 @@ export class McpServerManager {
 
     let transport: Transport;
     let stderrTail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+    const configuredTransports = [definition.command, definition.url, definition.socket]
+      .filter(value => typeof value === "string" && value.length > 0);
+    if (configuredTransports.length !== 1) {
+      throw new Error(`Server ${name} must configure exactly one of command, url, or socket`);
+    }
 
     if (definition.command) {
       let command = definition.command;
@@ -314,7 +338,7 @@ export class McpServerManager {
       const stdioTransport = new StdioClientTransport({
         command,
         args,
-        env: resolveEnv(definition.env),
+        env: resolveEnv(definition.env, name),
         cwd: resolveConfigPath(definition.cwd) ?? this.defaultCwd,
         stderr: definition.debug ? "inherit" : "pipe",
       });
@@ -330,7 +354,7 @@ export class McpServerManager {
       // HTTP transport with fallback
       transport = await this.createHttpTransport(definition, name, signal, requestSignal, traceObserver);
     } else {
-      throw new Error(`Server ${name} has no command or url`);
+      transport = new UnixSocketClientTransport(resolveConfigPath(definition.socket!)!);
     }
 
     if (traceObserver) {
@@ -406,7 +430,7 @@ export class McpServerManager {
 
       // Check for UnauthorizedError - server requires OAuth. A cleanup failure
       // remains a setup failure rather than being hidden behind needs-auth.
-      if (error instanceof UnauthorizedError && supportsOAuth(definition) && cleanupFailures.length === 0) {
+      if (isUnauthorizedHttpError(error) && supportsOAuth(definition) && cleanupFailures.length === 0) {
         return {
           client,
           transport,
@@ -484,6 +508,7 @@ export class McpServerManager {
       { name: `pi-mcp-${serverName}`, version: "1.0.0" },
       {
         ...MCP_CLIENT_OPTIONS,
+        jsonSchemaValidator: createJsonSchemaValidator(),
         ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}),
         listChanged: {
           tools: {
@@ -617,101 +642,128 @@ export class McpServerManager {
     const serverUrl = resolveServerUrl(definition)!;
     const url = new URL(serverUrl);
 
-    // Build headers first (including any bearer token)
-    const headers = resolveHeaders(definition.headers) ?? {};
+    // Resolve secret commands only for this connection attempt, without mutating config.
+    const hasCommandHeader = Object.values(definition.headers ?? {})
+      .some(value => value.startsWith("!") && !value.startsWith("!!"));
+    const headers = resolveCommandSecretsRecord(
+      definition.headers,
+      key => `MCP server "${serverName}" HTTP header "${key}"`,
+    ) ?? {};
 
     // For bearer auth, add the token to headers BEFORE creating requestInit
+    const commandBearer = definition.bearerToken?.startsWith("!") && !definition.bearerToken.startsWith("!!")
+      ? definition.bearerToken
+      : undefined;
     if (definition.auth === "bearer") {
-      const token = resolveBearerToken(definition);
-      if (token) {
-        headers["Authorization"] = `Bearer ${token}`;
+      const token = commandBearer
+        ? resolveCommandSecret(commandBearer, `MCP server "${serverName}" HTTP bearer token`)
+        : resolveBearerToken(definition);
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    if (hasCommandHeader || commandBearer) {
+      try {
+        new Headers(headers);
+      } catch {
+        throw new Error(`Failed to resolve MCP server "${serverName}" HTTP command secret: command returned an invalid header value`);
       }
     }
 
     // Create request init with headers (Authorization now included for bearer auth)
     const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
-
-    // For OAuth servers, create an auth provider
-    let authProvider: McpOAuthProvider | undefined;
-    if (supportsOAuth(definition)) {
-      const oauthConfig = extractOAuthConfig(definition);
-      authProvider = new McpOAuthProvider(
-        serverName,
-        serverUrl,
-        oauthConfig,
-        {
-          onRedirect: async (_authUrl) => {
-            // URL is captured by startAuth, no need to log
-          },
+    const createAuthProvider = (): McpOAuthProvider => new McpOAuthProvider(
+      serverName,
+      serverUrl,
+      extractOAuthConfig(definition),
+      {
+        onRedirect: async (_authUrl) => {
+          // URL is captured by startAuth, no need to log
         },
-        this.authStorageOptions,
-        this.oauthRuntime?.signal,
-      );
-    }
-
-    // Try StreamableHTTP first (modern MCP servers)
-    const streamableTransport = new StreamableHTTPClientTransport(url, {
-      requestInit,
-      authProvider,
-    });
-    const probeTransport = traceObserver
-      ? wrapTransportWithMcpTrace(streamableTransport, serverName, "streamable-http", traceObserver)
-      : streamableTransport;
-
-    const testClient = new Client(
-      { name: "pi-mcp-probe", version: "2.1.2" },
-      MCP_CLIENT_OPTIONS,
+      },
+      this.authStorageOptions,
+      this.oauthRuntime?.signal,
     );
-    let probeCleanupAttempted = false;
-    try {
-      await this.connectClientWithAbort(
-        testClient,
-        probeTransport,
-        this.buildRequestOptions(definition, requestSignal),
-        signal,
+
+    // Explicit OAuth must check the secure credential store before connecting.
+    let authState: HttpAuthProviderState = supportsOAuth(definition)
+      ? definition.auth === undefined
+        ? { status: "implicit-deferred" }
+        : { status: "explicit", provider: createAuthProvider() }
+      : { status: "disabled" };
+
+    // Try StreamableHTTP first (modern MCP servers). For implicit OAuth, defer
+    // creating the provider until the server proves that authentication is needed.
+    for (;;) {
+      const authProvider = "provider" in authState ? authState.provider : undefined;
+      const streamableTransport = new StreamableHTTPClientTransport(url, {
+        requestInit,
+        authProvider,
+      });
+      const probeTransport = traceObserver
+        ? wrapTransportWithMcpTrace(streamableTransport, serverName, "streamable-http", traceObserver)
+        : streamableTransport;
+      const testClient = new Client(
+        { name: "pi-mcp-probe", version: "2.1.2" },
+        MCP_CLIENT_OPTIONS,
       );
-      probeCleanupAttempted = true;
+      let probeCleanupAttempted = false;
       try {
-        await testClient.close();
-      } catch (cleanupError) {
-        throw new AggregateError([cleanupError], "MCP HTTP probe cleanup failed");
-      }
-
-      // StreamableHTTP works - create fresh transport for actual use
-      return new StreamableHTTPClientTransport(url, { requestInit, authProvider });
-    } catch (error) {
-      if (error instanceof AggregateError && (
-        error.message === "MCP connection abort cleanup failed" ||
-        error.message === "MCP HTTP probe cleanup failed"
-      )) {
-        throw error;
-      }
-
-      // StreamableHTTP failed, close through the SDK client and try SSE fallback.
-      // If connectClientWithAbort already owned the close, await that operation
-      // instead of closing the same transport again.
-      if (!probeCleanupAttempted) {
+        await this.connectClientWithAbort(
+          testClient,
+          probeTransport,
+          this.buildRequestOptions(definition, requestSignal),
+          signal,
+        );
         probeCleanupAttempted = true;
         try {
-          await (abortCleanupPromises.get(probeTransport) ?? testClient.close());
+          await testClient.close();
         } catch (cleanupError) {
-          throw new AggregateError([error, cleanupError], "MCP HTTP probe cleanup failed");
+          throw new AggregateError([cleanupError], "MCP HTTP probe cleanup failed");
         }
-      }
 
-      // Host cancellation is not transport capability evidence; do not fall
-      // through to SSE when the caller is trying to cancel the connect.
-      if (signal?.aborted) {
-        throwIfAborted(signal);
-      }
+        // StreamableHTTP works - create fresh transport for actual use
+        return new StreamableHTTPClientTransport(url, { requestInit, authProvider });
+      } catch (error) {
+        if (error instanceof AggregateError && (
+          error.message === "MCP connection abort cleanup failed" ||
+          error.message === "MCP HTTP probe cleanup failed"
+        )) {
+          throw error;
+        }
 
-      // If this was an UnauthorizedError, don't try SSE - the server needs auth
-      if (error instanceof UnauthorizedError) {
-        throw error;
-      }
+        // StreamableHTTP failed, close through the SDK client and try SSE fallback.
+        // If connectClientWithAbort already owned the close, await that operation
+        // instead of closing the same transport twice.
+        if (!probeCleanupAttempted) {
+          probeCleanupAttempted = true;
+          try {
+            await (abortCleanupPromises.get(probeTransport) ?? testClient.close());
+          } catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "MCP HTTP probe cleanup failed");
+          }
+        }
 
-      // SSE is the legacy transport
-      return new SSEClientTransport(url, { requestInit, authProvider });
+        // Host cancellation is not transport capability evidence; do not fall
+        // through to SSE when the caller is trying to cancel the connect.
+        if (signal?.aborted) {
+          throwIfAborted(signal);
+        }
+
+        // An implicit URL-only server gets a provider only after a real auth
+        // challenge. This keeps unauthenticated servers independent of storage.
+        if (authState.status === "implicit-deferred" && isUnauthorizedHttpError(error)) {
+          authState = { status: "implicit-challenged", provider: createAuthProvider() };
+          continue;
+        }
+
+        // If this was an UnauthorizedError, don't try SSE - the server needs auth
+        if (isUnauthorizedHttpError(error)) {
+          throw error;
+        }
+
+        // SSE is the legacy transport
+        return new SSEClientTransport(url, { requestInit, authProvider });
+      }
     }
   }
 
@@ -966,28 +1018,18 @@ export class McpServerManager {
 /**
  * Resolve environment variables with interpolation.
  */
-function resolveEnv(env?: Record<string, string>): Record<string, string> {
-  // Copy process.env, filtering out undefined values
+function resolveEnv(env: Record<string, string> | undefined, serverName: string): Record<string, string> {
   const resolved: Record<string, string> = {};
   for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined) {
-      resolved[key] = value;
-    }
+    if (value !== undefined) resolved[key] = value;
   }
-
-  if (!env) return resolved;
-
-  const overrides = interpolateEnvRecord(env);
+  const overrides = resolveCommandSecretsRecord(
+    env,
+    key => `MCP server "${serverName}" stdio env "${key}"`,
+  );
   return overrides ? { ...resolved, ...overrides } : resolved;
 }
 
-/**
- * Resolve headers with environment variable interpolation.
- */
-function resolveHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
-  return interpolateEnvRecord(headers);
-}
-
 function normalizeRequestTimeoutMs(timeoutMs: number | undefined): number | undefined {
   return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
     ? timeoutMs

package/types.ts

@@ -1,14 +1,9 @@
 // types.ts - Core type definitions
-import type { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
-import type { SSEClientTransport, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import type { Transport as McpTransport } from "@modelcontextprotocol/client";
 import type { TextContent, ImageContent } from "@earendil-works/pi-ai";
 import type { UiStreamMode } from "./ui-stream-types.ts";
 
-// Transport type (stdio + HTTP)
-export type Transport = 
-  | StdioClientTransport 
-  | SSEClientTransport 
-  | StreamableHTTPClientTransport;
+export type Transport = McpTransport;
 
 /** Versioned shared-event-bus channel for read-only MCP runtime snapshots. */
 export const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
@@ -324,6 +319,8 @@ export interface OAuthConfig {
 export interface ServerEntry {
   command?: string;
   args?: string[];
+  /** Explicit rmcp-mux Unix-domain socket path. Mutually exclusive with command and url. */
+  socket?: string;
   env?: Record<string, string>;
   cwd?: string;
   // HTTP fields
@@ -395,6 +392,8 @@ export interface McpTraceSettings {
 
 export interface McpSettings {
   toolPrefix?: ToolPrefix;
+  /** Show the plug prefix in MCP status and connection text (default: true). Set to false to disable it. */
+  showStatusIcon?: boolean;
   /** Discover detected host-specific MCP configs only when explicitly enabled. */
   hostConfigDiscovery?: HostConfigDiscovery;
   idleTimeout?: number; // minutes, default 10, 0 to disable

package/unix-socket-transport.ts

@@ -0,0 +1,88 @@
+import { createConnection, type Socket } from "node:net";
+import {
+  ReadBuffer,
+  serializeMessage,
+  type JSONRPCMessage,
+  type Transport,
+} from "@modelcontextprotocol/client";
+
+/** MCP JSONL transport for an explicitly configured Unix-domain socket. */
+export class UnixSocketClientTransport implements Transport {
+  private socket?: Socket;
+  private readonly readBuffer = new ReadBuffer();
+
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage) => void;
+
+  constructor(private readonly socketPath: string) {}
+
+  async start(): Promise<void> {
+    if (this.socket) {
+      throw new Error("UnixSocketClientTransport already started");
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const socket = createConnection(this.socketPath);
+      this.socket = socket;
+      let connected = false;
+
+      socket.once("connect", () => {
+        connected = true;
+        resolve();
+      });
+      socket.on("data", chunk => {
+        try {
+          this.readBuffer.append(chunk);
+          while (true) {
+            const message = this.readBuffer.readMessage();
+            if (message === null) break;
+            this.onmessage?.(message);
+          }
+        } catch (error) {
+          const cause = error instanceof Error ? error : new Error(String(error));
+          this.onerror?.(cause);
+          void this.close();
+        }
+      });
+      socket.on("error", error => {
+        if (!connected) reject(error);
+        this.onerror?.(error);
+      });
+      socket.on("close", () => {
+        if (this.socket === socket) this.socket = undefined;
+        this.readBuffer.clear();
+        this.onclose?.();
+      });
+    });
+  }
+
+  async close(): Promise<void> {
+    const socket = this.socket;
+    this.socket = undefined;
+    this.readBuffer.clear();
+    if (!socket || socket.destroyed) return;
+
+    await new Promise<void>(resolve => {
+      const timeout = setTimeout(() => socket.destroy(), 2_000);
+      timeout.unref();
+      socket.once("close", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      socket.end();
+    });
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    const socket = this.socket;
+    if (!socket || socket.destroyed) throw new Error("Unix socket is not connected");
+
+    await new Promise<void>((resolve, reject) => {
+      socket.write(serializeMessage(message), error => {
+        if (error) reject(error);
+        else resolve();
+      });
+    });
+  }
+}

package/utils.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import type { McpConfig, ServerEntry } from "./types.ts";
@@ -87,18 +88,73 @@ export function toStringRecord(value: unknown): Record<string, string> | undefin
   return Object.keys(result).length > 0 ? result : undefined;
 }
 
+function interpolateSecretExpression(value: string): string {
+  if (value.startsWith("!!")) return interpolateEnvVars(value.slice(1));
+  return value.startsWith("!") ? value : interpolateEnvVars(value);
+}
+
 export function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {
   if (!values) return undefined;
 
-  const resolved: Record<string, string> = {};
-  for (const [key, value] of Object.entries(values)) {
-    resolved[key] = interpolateEnvVars(value);
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [
+    key,
+    interpolateSecretExpression(value),
+  ]));
+}
+
+const COMMAND_SECRET_TIMEOUT_MS = 10_000;
+const COMMAND_SECRET_MAX_OUTPUT_BYTES = 1024 * 1024;
+
+/** Resolve a secret value, executing only a single leading `!` command marker. */
+export function resolveCommandSecret(value: string | undefined, context: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (value.startsWith("!!")) return interpolateEnvVars(value.slice(1));
+  if (!value.startsWith("!")) return interpolateEnvVars(value);
+
+  const result = spawnSync(value.slice(1), {
+    shell: true,
+    encoding: "utf8",
+    timeout: COMMAND_SECRET_TIMEOUT_MS,
+    maxBuffer: COMMAND_SECRET_MAX_OUTPUT_BYTES,
+    stdio: ["ignore", "pipe", "ignore"],
+    windowsHide: true,
+  });
+  if (result.error) {
+    const code = (result.error as NodeJS.ErrnoException).code;
+    const reason = code === "ETIMEDOUT"
+      ? "command timed out after 10 seconds"
+      : code === "ENOBUFS"
+        ? "command output exceeded 1 MiB"
+        : "command failed to start";
+    throw new Error(`Failed to resolve ${context}: ${reason}`);
   }
+  if (result.status !== 0) {
+    throw new Error(`Failed to resolve ${context}: command exited with code ${result.status ?? "unknown"}`);
+  }
+
+  const resolved = result.stdout.trim();
+  if (!resolved) throw new Error(`Failed to resolve ${context}: command returned empty output`);
   return resolved;
 }
 
+/** Resolve command markers in a configured record without mutating the input. */
+export function resolveCommandSecretsRecord(
+  values: Record<string, string> | undefined,
+  context: (key: string) => string,
+): Record<string, string> | undefined {
+  if (!values) return undefined;
+
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [
+    key,
+    resolveCommandSecret(value, context(key)),
+  ]));
+}
+
 export function resolveServerUrl(definition: Pick<ServerEntry, "url">): string | undefined {
-  if (definition.url === undefined) return undefined;
+  if (definition.url == null) return undefined;
+  if (typeof definition.url !== "string") {
+    throw new Error("MCP server URL must be a string");
+  }
 
   const missing = getMissingEnvVars(definition.url);
   if (missing.length > 0) {
@@ -127,7 +183,7 @@ export function resolveConfigPath(value: string | undefined): string | undefined
 
 export function resolveBearerToken(definition: Pick<ServerEntry, "bearerToken" | "bearerTokenEnv">): string | undefined {
   if (definition.bearerToken !== undefined) {
-    return interpolateEnvVars(definition.bearerToken);
+    return interpolateSecretExpression(definition.bearerToken);
   }
   return definition.bearerTokenEnv ? process.env[definition.bearerTokenEnv] : undefined;
 }
@@ -221,6 +277,10 @@ export function formatAuthRequiredMessage(
   return template ? template.replaceAll("${server}", serverName) : defaultMessage;
 }
 
+export function formatMcpStatus(config: Pick<McpConfig, "settings">, message: string): string {
+  return `${config.settings?.showStatusIcon === false ? "MCP: " : "🔌 MCP: "}${message}`;
+}
+
 /**
  * Extract the adapter-owned UI stream mode from tool metadata.
  */