@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-mcp-adapter/config.ts

@@ -4,8 +4,9 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import stripJsonComments from "strip-json-comments";
-import { getAgentPath } from "./agent-dir.ts";
+import { getAgentPath, getConfigDirName } from "./agent-dir.ts";
 import { getAgentPluginSummaries, loadAgentPluginConfigs, type AgentPluginSummary } from "./agent-plugin-loader.ts";
+import { loadPackageMcpConfigs } from "./package-mcp-loader.ts";
 import { isServerDisabled, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
 import { toStringRecord } from "./utils.ts";
 
@@ -15,7 +16,7 @@ const AGENTS_GLOBAL_CONFIG_PATHS = [
   join(homedir(), ".agents", "mcp", "mcp.json"),
 ] as const;
 const PROJECT_CONFIG_NAME = ".mcp.json";
-const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
+const PROJECT_PI_CONFIG_NAME = "mcp.json";
 const REPOPROMPT_BINARY_CANDIDATES = [
   join(homedir(), "RepoPrompt", "repoprompt_cli"),
   "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp",
@@ -177,7 +178,7 @@ export function getProjectConfigPath(cwd = process.cwd()): string {
 }
 
 export function getProjectPiConfigPath(cwd = process.cwd()): string {
-  return resolve(cwd, PROJECT_PI_CONFIG_NAME);
+  return resolve(cwd, getConfigDirName(), PROJECT_PI_CONFIG_NAME);
 }
 
 export function getConfigDiscoveryPaths(overridePath?: string, cwd = process.cwd()): ConfigDiscoveryPath[] {
@@ -306,8 +307,12 @@ export function loadMcpConfig(overridePath?: string, cwd = process.cwd()): McpCo
     config = mergeConfigs(config, expandImports(loaded, cwd));
   }
 
+  const packageConfig = loadPackageMcpConfigs(cwd);
   const pluginConfig = loadAgentPluginConfigs(config.settings?.agentPluginPaths, cwd);
-  return mergeConfigs(pluginConfig, config);
+  const packageServers = Object.fromEntries(
+    Object.entries(packageConfig.mcpServers).filter(([name]) => !Object.hasOwn(pluginConfig.mcpServers, name)),
+  );
+  return mergeConfigs({ mcpServers: packageServers }, mergeConfigs(pluginConfig, config));
 }
 
 function getMergedSettings(overridePath?: string, cwd = process.cwd()): McpSettings | undefined {
@@ -471,7 +476,7 @@ function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
 // different url, these MUST NOT be inherited from the lower-precedence entry —
 // otherwise the original endpoint's credentials would be shipped to the new
 // url. See the SECURITY note in mergeServerMaps.
-const URL_BOUND_AUTH_FIELDS = ["headers", "bearerToken", "bearerTokenEnv"] as const;
+const URL_BOUND_AUTH_FIELDS = ["headers", "bearerToken", "bearerTokenEnv", "bearerTokenStore", "requestHeadersCommand"] as const;
 
 function mergeServerMaps(
   base: Record<string, ServerEntry>,
@@ -491,17 +496,30 @@ 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.socket === "string") {
+    if (existing && typeof definition.command === "string") {
       baseEntry = { ...existing };
       for (const field of [
-        "command", "args", "env", "cwd", "url", "headers", "auth",
-        "bearerToken", "bearerTokenEnv", "oauth",
+        "url", "headers", "requestHeadersCommand", "auth", "bearerToken",
+        "bearerTokenEnv", "oauth", "httpTransport", "socket",
       ] as const) {
         delete baseEntry[field];
       }
-    } else if (existing?.socket && (typeof definition.command === "string" || typeof definition.url === "string")) {
+    } else if (existing && typeof definition.url === "string") {
       baseEntry = { ...existing };
-      delete baseEntry.socket;
+      for (const field of [
+        "command", "args", "env", "cwd", "pluginDataDir", "literalEnv", "socket",
+      ] as const) {
+        delete baseEntry[field];
+      }
+    } else if (existing && typeof definition.socket === "string") {
+      baseEntry = { ...existing };
+      for (const field of [
+        "command", "args", "env", "cwd", "pluginDataDir", "literalEnv", "url",
+        "headers", "requestHeadersCommand", "auth", "bearerToken", "bearerTokenEnv",
+        "oauth", "httpTransport",
+      ] as const) {
+        delete baseEntry[field];
+      }
     }
     if (existing && typeof definition.url === "string" && definition.url !== existing.url) {
       if (baseEntry === existing) baseEntry = { ...existing };

package/node_modules/pi-mcp-adapter/direct-tools.ts

@@ -11,11 +11,11 @@ import { formatSchema } from "./tool-metadata.ts";
 import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
-import { formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
+import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
 import { isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.ts";
-import { formatAuthRequiredMessage, resolveServerUrl, truncateAtWord } from "./utils.ts";
+import { formatAuthRequiredMessage, normalizeToolArguments, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { ensureToolCallApproved } from "./tool-approval.ts";
@@ -150,7 +150,10 @@ export function resolveDirectTools(
     if (!toolFilter) continue;
 
     const effectivePrefix = resolveToolPrefix(definition, prefix);
-    const getOtherCurrentCandidates = (toolName: string): Set<string> => {
+    const hasToolFilters =
+      (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+      (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+    const selectorCandidateIndex = hasToolFilters ? (() => {
       const candidates = new Set<string>();
       for (const [otherServerName, otherDefinition] of Object.entries(config.mcpServers)) {
         const otherCache = cache.servers[otherServerName];
@@ -167,14 +170,13 @@ export function resolveDirectTools(
           }
         }
       }
-      for (const candidate of getToolNameCandidates(toolName, serverName, effectivePrefix, false)) candidates.delete(candidate);
-      return candidates;
-    };
+      return createToolSelectorCandidateIndex(candidates);
+    })() : undefined;
 
     for (const tool of serverCache.tools ?? []) {
       if (!isUiToolVisibleToModel(tool.uiVisibility)) continue;
       if (toolFilter !== true && !toolFilter.includes(tool.name)) continue;
-      if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(tool.name))) continue;
+      if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) continue;
       const prefixedName = formatToolName(tool.name, serverName, effectivePrefix);
       if (BUILTIN_NAMES.has(prefixedName)) {
         console.warn(`MCP: skipping direct tool "${prefixedName}" (collides with builtin)`);
@@ -200,7 +202,7 @@ export function resolveDirectTools(
       for (const resource of serverCache.resources ?? []) {
         const baseName = `read_${resourceNameToToolName(resource.name)}`;
         if (toolFilter !== true && !toolFilter.includes(baseName)) continue;
-        if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(baseName))) continue;
+        if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) continue;
         const prefixedName = formatToolName(baseName, serverName, effectivePrefix);
         if (BUILTIN_NAMES.has(prefixedName)) {
           console.warn(`MCP: skipping direct resource tool "${prefixedName}" (collides with builtin)`);
@@ -222,7 +224,7 @@ export function resolveDirectTools(
     }
   }
 
-  if (specs.length >= DIRECT_TOOLS_ADVISORY_THRESHOLD) {
+  if (config.settings?.warnOnLargeDirectTools !== false && specs.length >= DIRECT_TOOLS_ADVISORY_THRESHOLD) {
     console.warn(`MCP: ${specs.length} direct tools resolved. Each direct tool adds prompt context; README guidance recommends targeted sets of 5-20 tools and using the proxy or an explicit string[] when 75+ direct tools would be registered.`);
   }
 
@@ -255,8 +257,10 @@ export function buildProxyDescription(
     const cachedEntry = cache?.servers?.[serverName];
     const entry = cachedEntry && isServerCacheValid(cachedEntry, definition) ? cachedEntry : undefined;
     const effectivePrefix = resolveToolPrefix(definition, prefix);
-    const getOtherCurrentCandidates = (toolName: string): Set<string> | undefined => {
-      if (!cache) return undefined;
+    const hasToolFilters =
+      (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+      (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+    const selectorCandidateIndex = hasToolFilters && cache ? (() => {
       const candidates = new Set<string>();
       for (const [otherServerName, otherDefinition] of Object.entries(config.mcpServers)) {
         const otherEntry = cache.servers[otherServerName];
@@ -273,17 +277,16 @@ export function buildProxyDescription(
           }
         }
       }
-      for (const candidate of getToolNameCandidates(toolName, serverName, effectivePrefix, false)) candidates.delete(candidate);
-      return candidates;
-    };
+      return createToolSelectorCandidateIndex(candidates);
+    })() : undefined;
     const toolCount = (entry?.tools ?? []).filter(
       (tool) => isUiToolVisibleToModel(tool.uiVisibility)
-        && isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(tool.name)),
+        && isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex),
     ).length;
     const resourceCount = definition?.exposeResources !== false
       ? (entry?.resources ?? []).filter((resource) => {
           const baseName = `read_${resourceNameToToolName(resource.name)}`;
-          return isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(baseName));
+          return isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex);
         }).length
       : 0;
     const totalItems = toolCount + resourceCount;
@@ -426,6 +429,7 @@ export function createDirectToolExecutor(
       };
     }
 
+    const normalizedParams = spec.resourceUri ? params : normalizeToolArguments(params);
     const approval = await ensureToolCallApproved(state, spec.serverName, {
       name: spec.prefixedName,
       originalName: spec.originalName,
@@ -434,7 +438,7 @@ export function createDirectToolExecutor(
       ...(spec.resourceUri !== undefined ? { resourceUri: spec.resourceUri } : {}),
       ...(spec.uiResourceUri !== undefined ? { uiResourceUri: spec.uiResourceUri } : {}),
       ...(spec.uiStreamMode !== undefined ? { uiStreamMode: spec.uiStreamMode } : {}),
-    }, params, ownedSignal, spec.resourceUri ? "resource" : "direct");
+    }, normalizedParams, ownedSignal, spec.resourceUri ? "resource" : "direct");
     if (approval.ok === false) {
       const denied = approval.reason === "denied";
       const message = denied
@@ -506,7 +510,7 @@ export function createDirectToolExecutor(
         ? await maybeStartUiSession(state, {
             serverName: spec.serverName,
             toolName: spec.originalName,
-            toolArgs: params ?? {},
+            toolArgs: normalizedParams,
             uiResourceUri: spec.uiResourceUri!,
             ...(spec.uiStreamMode !== undefined ? { streamMode: spec.uiStreamMode } : {}),
             ...(signal ? { signal } : {}),
@@ -524,7 +528,7 @@ export function createDirectToolExecutor(
         spec.serverName,
         (conn) => abortable(conn.client.callTool({
           name: spec.originalName,
-          arguments: params ?? {},
+          arguments: normalizedParams,
           _meta: uiSession?.requestMeta,
         }, requestOptions), ownedSignal),
       );

package/node_modules/pi-mcp-adapter/index.ts

@@ -1,10 +1,10 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata } from "./types.ts";
+import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata, ServerEntry } from "./types.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { Type } from "typebox";
 import type { TSchema } from "typebox";
-import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
+import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, manageBearerToken, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
 import { cloneMcpConfig, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.ts";
 import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.ts";
 import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
@@ -22,6 +22,7 @@ import { runMcpScript } from "./mcp-code.ts";
 import { cleanupMaterializedBinaryResources } from "./tool-registrar.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
+export type { ServerEntry } from "./types.ts";
 export {
   MCP_STATUS_EVENT,
   MCP_STATUS_SNAPSHOT_VERSION,
@@ -38,6 +39,14 @@ export {
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_WAIT_TIMED_OUT: unique symbol = Symbol("init-wait-timed-out");
 
+export interface McpServerRegistration {
+  dispose(): Promise<void>;
+}
+
+// Routes runtime registrations to the adapter installed for a specific Pi
+// instance, so a process with several adapters cannot cross-register.
+const runtimeRegistrars = new WeakMap<ExtensionAPI, (name: string, definition: ServerEntry) => McpServerRegistration>();
+
 async function awaitWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | typeof INIT_WAIT_TIMED_OUT> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -130,6 +139,19 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   let proxyToolRegistered = false;
   let proxyToolDescription: string | null = null;
   let directToolsFrozen = false;
+  // Session/runtime scoped server registrations from other extensions. They
+  // survive session restarts within this install and die with the process.
+  const runtimeServers = new Map<string, ServerEntry>();
+
+  // Mirrors init's per-server lifecycle registration so runtime servers get
+  // idle cleanup and keep-alive health recovery like configured servers.
+  function attachRuntimeServerLifecycle(targetState: McpExtensionState, name: string, definition: ServerEntry): void {
+    const lifecycleMode = definition.lifecycle ?? "lazy";
+    const persistsAfterFirstSpawn = lifecycleMode === "eager" || lifecycleMode === "lazy-keep-alive";
+    const idleOverride = definition.idleTimeout ?? (persistsAfterFirstSpawn ? 0 : undefined);
+    targetState.lifecycle.registerServer(name, definition, idleOverride !== undefined ? { idleTimeout: idleOverride } : undefined);
+    if (lifecycleMode === "keep-alive") targetState.lifecycle.markKeepAlive(name, definition);
+  }
 
   // OMP remaps `typebox` to a host shim that historically lacked Type.Unsafe.
   // Prefer Unsafe when present (real TypeBox / fixed OMP shim); otherwise pass
@@ -282,6 +304,45 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
   registerPromptCommands(resolveCachedPrompts(earlyConfig));
 
+  runtimeRegistrars.set(pi, (name: string, definition: ServerEntry): McpServerRegistration => {
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new Error("MCP server name must be a non-empty string");
+    }
+    if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+      throw new Error(`MCP server definition for "${name}" must be an object`);
+    }
+    const effective = state?.config ?? earlyConfig;
+    if (runtimeServers.has(name) || Object.hasOwn(effective.mcpServers, name)) {
+      throw new Error(`MCP server "${name}" is already registered`);
+    }
+    // Runtime-registered servers are proxy-tool-only: direct tools are frozen
+    // at startup and must not be rebuilt for late registrations.
+    const entry: ServerEntry = { ...structuredClone(definition), directTools: false };
+    runtimeServers.set(name, entry);
+    const registeredState = state;
+    if (registeredState) {
+      registeredState.config.mcpServers[name] = entry;
+      attachRuntimeServerLifecycle(registeredState, name, entry);
+      syncToolSurface();
+      updateStatusBar(registeredState);
+    }
+    let disposed = false;
+    return {
+      dispose: async (): Promise<void> => {
+        if (disposed) return;
+        disposed = true;
+        runtimeServers.delete(name);
+        const currentState = state;
+        if (!currentState || currentState.config.mcpServers[name] !== entry) return;
+        delete currentState.config.mcpServers[name];
+        currentState.lifecycle.unregisterServer(name);
+        await currentState.manager.close(name);
+        syncToolSurface();
+        updateStatusBar(currentState);
+      },
+    };
+  });
+
   const getPiTools = (): ToolInfo[] => pi.getAllTools();
 
   pi.registerFlag("mcp-config", {
@@ -299,7 +360,6 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           }
         : {}),
       oauthRuntime,
-      statusEvents: pi.events,
     });
     initPromise = promise;
 
@@ -314,6 +374,14 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
 
       state = nextState;
+      for (const [name, definition] of runtimeServers) {
+        if (Object.hasOwn(nextState.config.mcpServers, name)) {
+          console.error(`MCP: runtime-registered server "${name}" now collides with a configured server; keeping the configured server`);
+          continue;
+        }
+        nextState.config.mcpServers[name] = definition;
+        attachRuntimeServerLifecycle(nextState, name, definition);
+      }
       nextState.onToolMetadataUpdated = (_serverName, _reason) => {
         if (state !== nextState || !owner.isActive()) return;
         syncPromptCommands();
@@ -325,6 +393,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       };
       syncPromptCommands();
       syncToolSurface(ctx);
+      // A connected snapshot is readiness-like external state. Publish it only
+      // after Pi's model-facing direct-tool surface reflects live metadata.
+      nextState.statusEvents = pi.events;
       updateStatusBar(nextState);
       initPromise = null;
       if (earlyConfig.settings?.freezeDirectTools === true) {
@@ -417,6 +488,29 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
   });
 
+  pi.on("input", async () => {
+    const inputOwner = currentOwner;
+    if (!inputOwner?.isActive()) return;
+
+    if (!state && initPromise) {
+      try {
+        await awaitWithTimeout(initPromise, INIT_WAIT_TIMEOUT_MS);
+      } catch {
+        return;
+      }
+    }
+
+    const inputState = state;
+    if (!inputState || !inputOwner.isActive()) return;
+    try {
+      await inputState.lifecycle.ensureConverged(inputOwner.signal);
+    } catch (error) {
+      if (!isAbortError(error, inputOwner.signal)) {
+        logger.debug(`MCP: keep-alive convergence failed before input: ${formatTerminalError(error)}`);
+      }
+    }
+  });
+
   pi.on("session_shutdown", async () => {
     ++lifecycleGeneration;
     const currentState = state;
@@ -444,7 +538,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   // Re-flag returned MCP tool failures so pi registers them as errors (see toolErrorOverride).
   pi.on("tool_result", (event) => toolErrorOverride(event.details));
 
-  pi.registerCommand("mcp", {
+  const registerMcpCommand = (commandName: string) => pi.registerCommand(commandName, {
     description: "Show MCP server status",
     getArgumentCompletions: (prefix: string) => {
       const normalized = prefix.trimStart();
@@ -456,6 +550,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           { value: "prompts", label: "prompts — List all MCP prompts" },
           { value: "setup", label: "setup — Configure MCP servers" },
           { value: "logout", label: "logout — Clear server credentials" },
+          { value: "token", label: "token — Manage stored bearer tokens" },
           { value: "disable", label: "disable — Disable a server" },
           { value: "enable", label: "enable — Enable a server" },
           { value: "status", label: "status — Show server status" },
@@ -465,11 +560,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
       const [, subcommand, argumentPrefix] = argumentMatch;
       if (
-        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable")
+        (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token")
         || argumentPrefix === undefined
         || !state
       ) return null;
 
+      if (subcommand === "token") {
+        const tokenMatch = argumentPrefix.trimStart().match(/^(set|remove|status)\s+(.*)$/);
+        if (!tokenMatch) {
+          const actions = ["set", "remove", "status"]
+            .filter(action => action.startsWith(argumentPrefix.trimStart()))
+            .map(action => ({ value: `token ${action} `, label: `${action} — Bearer token ${action}` }));
+          return actions.length > 0 ? actions : null;
+        }
+        const action = tokenMatch[1] ?? "";
+        const serverPrefix = tokenMatch[2] ?? "";
+        const servers = Object.keys(state.config.mcpServers)
+          .filter(serverName => serverName.startsWith(serverPrefix.trimStart()))
+          .map(serverName => ({ value: `token ${action} ${serverName}`, label: serverName }));
+        return servers.length > 0 ? servers : null;
+      }
+
       const servers = Object.keys(state.config.mcpServers)
         .filter((serverName) => serverName.startsWith(argumentPrefix.trimStart()))
         .map((serverName) => ({ value: `${subcommand} ${serverName}`, label: serverName }));
@@ -545,6 +656,21 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           await logoutServer(serverName, state, commandCtx);
           break;
         }
+        case "token": {
+          const action = parts[1];
+          const serverName = parts.slice(2).join(" ");
+          if (action !== "set" && action !== "remove" && action !== "status") {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          if (!serverName) {
+            if (commandCtx.hasUI) commandCtx.ui?.notify("Usage: /mcp token set|remove|status <server>", "error");
+            return;
+          }
+          commandOwner?.throwIfInactive();
+          await manageBearerToken(action, serverName, state, commandCtx);
+          break;
+        }
         case "disable":
         case "enable": {
           const serverName = rest;
@@ -595,6 +721,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }
     },
   });
+  registerMcpCommand("mcp");
+  registerMcpCommand("pi-mcp");
 
   pi.registerCommand("mcp-auth", {
     description: "Authenticate with an MCP server (OAuth)",
@@ -737,12 +865,12 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         action?: string;
       }, signal: AbortSignal | undefined, _onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, _ctx: ExtensionContext) {
         const executeOwner = currentOwner;
-        let parsedArgs: Record<string, unknown> | undefined;
-        if (params.args !== undefined && params.args !== "") {
+        const parseArgs = (value: string | Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+          if (value === undefined || value === "") return undefined;
           let args: unknown;
-          if (typeof params.args === "string") {
+          if (typeof value === "string") {
             try {
-              args = JSON.parse(params.args);
+              args = JSON.parse(value);
             } catch (error) {
               if (error instanceof SyntaxError) {
                 throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
@@ -750,14 +878,57 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
               throw error;
             }
           } else {
-            args = params.args;
+            args = value;
           }
 
           if (typeof args !== "object" || args === null || Array.isArray(args)) {
             const gotType = Array.isArray(args) ? "array" : args === null ? "null" : typeof args;
             throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
           }
-          parsedArgs = args as Record<string, unknown>;
+          return args as Record<string, unknown>;
+        };
+        const validateNestedGatewayParams = (value: Record<string, unknown>): typeof params => {
+          for (const key of ["tool", "connect", "describe", "instructions", "search", "server", "action"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "string") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected string, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["regex", "includeSchemas"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "boolean") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected boolean, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          for (const key of ["limit", "offset"] as const) {
+            if (value[key] !== undefined && typeof value[key] !== "number") {
+              throw new Error(`Invalid nested gateway param \`${key}\`: expected number, got ${Array.isArray(value[key]) ? "array" : typeof value[key]}`);
+            }
+          }
+          const args = value.args;
+          if (args !== undefined && typeof args !== "string" && (typeof args !== "object" || args === null || Array.isArray(args))) {
+            throw new Error(`Invalid nested gateway param \`args\`: expected JSON object or JSON string, got ${Array.isArray(args) ? "array" : args === null ? "null" : typeof args}`);
+          }
+          return value as typeof params;
+        };
+        let parsedArgs = parseArgs(params.args);
+        let dispatchParams = params;
+        const hasGatewayMode = (value: typeof params): boolean =>
+          value.tool !== undefined
+          || value.connect !== undefined
+          || value.describe !== undefined
+          || value.instructions !== undefined
+          || value.search !== undefined
+          || value.server !== undefined
+          || value.action !== undefined;
+        if (!hasGatewayMode(params) && parsedArgs) {
+          const nestedParams = validateNestedGatewayParams(parsedArgs);
+          if (hasGatewayMode(nestedParams)) {
+            dispatchParams = nestedParams;
+            parsedArgs = parseArgs(nestedParams.args);
+          } else {
+            throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
+          }
+        } else if (!hasGatewayMode(params) && params.args !== undefined) {
+          throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
         }
 
         if (!state && initPromise) {
@@ -788,22 +959,22 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         }
         executeOwner?.throwIfInactive();
 
-        if (params.action === "ui-messages") {
+        if (dispatchParams.action === "ui-messages") {
           return executeUiMessages(state);
         }
-        if (params.action === "auth-start") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-start") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-start requires `server`. Example: mcp({ action: \"auth-start\", server: \"linear-server\" })" }],
               details: { mode: "auth-start", error: "missing_server" },
             };
           }
           return signal
-            ? executeAuthStart(state, params.server, signal)
-            : executeAuthStart(state, params.server);
+            ? executeAuthStart(state, dispatchParams.server, signal)
+            : executeAuthStart(state, dispatchParams.server);
         }
-        if (params.action === "auth-complete") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-complete") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-complete requires `server`." }],
               details: { mode: "auth-complete", error: "missing_server" },
@@ -817,28 +988,28 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             };
           }
           return signal
-            ? executeAuthComplete(state, params.server, input, signal)
-            : executeAuthComplete(state, params.server, input);
+            ? executeAuthComplete(state, dispatchParams.server, input, signal)
+            : executeAuthComplete(state, dispatchParams.server, input);
         }
-        if (params.tool) {
-          return executeCall(state, params.tool, parsedArgs, params.server, getPiTools, signal);
+        if (dispatchParams.tool) {
+          return executeCall(state, dispatchParams.tool, parsedArgs, dispatchParams.server, getPiTools, signal);
         }
-        if (params.connect) {
-          const result = await executeConnect(state, params.connect, signal);
+        if (dispatchParams.connect) {
+          const result = await executeConnect(state, dispatchParams.connect, signal);
           syncToolSurface(_ctx as ExtensionContext);
           return result;
         }
-        if (params.describe) {
-          return executeDescribe(state, params.describe);
+        if (dispatchParams.describe) {
+          return executeDescribe(state, dispatchParams.describe);
         }
-        if (params.instructions) {
-          return executeInstructions(state, params.instructions);
+        if (dispatchParams.instructions) {
+          return executeInstructions(state, dispatchParams.instructions);
         }
-        if (params.search !== undefined) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
+        if (dispatchParams.search !== undefined) {
+          return executeSearch(state, dispatchParams.search, dispatchParams.regex, dispatchParams.server, dispatchParams.includeSchemas, dispatchParams.limit, dispatchParams.offset);
         }
-        if (params.server) {
-          return executeList(state, params.server);
+        if (dispatchParams.server) {
+          return executeList(state, dispatchParams.server);
         }
         return executeStatus(state);
       },
@@ -895,4 +1066,20 @@ export function createMcpAdapter(options: McpAdapterOptions = {}) {
   };
 }
 
+/**
+ * Register an MCP server with the adapter installed for this Pi instance.
+ * Registrations are session/runtime scoped and never persisted. Duplicate
+ * names fail closed. Registered servers are proxy-tool-only; their tools
+ * become visible at the next tool sync. To change a definition, dispose the
+ * registration and register again.
+ */
+export function registerMcpServer(options: { pi: ExtensionAPI; name: string; definition: ServerEntry }): McpServerRegistration {
+  const { pi, name, definition } = options;
+  const register = runtimeRegistrars.get(pi);
+  if (!register) {
+    throw new Error("pi-mcp-adapter is not installed for this Pi instance");
+  }
+  return register(name, definition);
+}
+
 export default createMcpAdapter();