pi-mcp-adapter 2.14.0 → 2.15.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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

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:

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

@@ -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(

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.14.0",
+  "version": "2.15.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -75,6 +75,7 @@
     "ui-stream-types.ts",
     "config.ts",
     "server-manager.ts",
+    "unix-socket-transport.ts",
     "json-schema-validator.ts",
     "session-recovery.ts",
     "sampling-handler.ts",

package/server-manager.ts

@@ -9,6 +9,7 @@ import {
   type UrlElicitationRequiredError,
 } from "@modelcontextprotocol/client";
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { UnixSocketClientTransport } from "./unix-socket-transport.ts";
 import {
   isServerDisabled,
   type McpTool,
@@ -32,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 {
@@ -308,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;
@@ -326,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",
       });
@@ -342,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) {
@@ -630,14 +642,30 @@ 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`);
       }
     }
 
@@ -990,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

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;
 }