@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-mcp-adapter/README.md

@@ -126,6 +126,42 @@ Each directory must contain a valid Agent Plugins 1.0 `plugin.json`. If it also
 
 Agent Plugins is a portable package format. Native Pi MCP config remains `.mcp.json`, `~/.config/mcp/mcp.json`, and Pi-owned overrides.
 
+### Pi package manifests
+
+A Pi package can ship MCP servers for the installed adapter without requiring a separate MCP config file. Declare a package-relative config in its `package.json`:
+
+```json
+{
+  "pi": {
+    "mcp": "./mcp.json"
+  }
+}
+```
+
+`pi.mcp` can also be an array of package-relative paths. Each file uses the normal `mcpServers` object shape, but package manifests load only server entries: package `settings` and `imports` are ignored. Server names are prefixed with the sanitized package name, such as `acme_tools__docs`, and user/global/project MCP config has higher precedence. The adapter loads only Pi packages listed in Pi settings; it does not scan `node_modules`.
+
+### Runtime registration from other extensions
+
+An extension can register MCP servers with the installed adapter at runtime, for example a plugin host that discovers plugins after load:
+
+```ts
+import { registerMcpServer } from "pi-mcp-adapter";
+
+export default function pluginHost(pi) {
+  const registration = registerMcpServer({
+    pi,
+    name: "acme__docs",
+    definition: {
+      url: "https://mcp.example.com/mcp",
+    },
+  });
+  // Later, when the plugin is uninstalled:
+  await registration.dispose();
+}
+```
+
+Runtime registrations are session scoped and never written to config files. Duplicate server names fail closed against configured servers and other registrations. Registered servers use the normal lazy connection, OAuth, approval, and shutdown behavior, but they are proxy-tool-only and their tools become visible at the next tool sync. To change a definition, dispose the registration and register again. Registration throws when no adapter is installed for the given Pi instance.
+
 ### SDK configuration
 
 Use `createMcpAdapter` when an SDK or server integration already owns its MCP configuration:
@@ -178,7 +214,7 @@ pi.events.on(MCP_STATUS_EVENT, (snapshot) => {
 });
 ```
 
-The snapshot is read-only machine-readable data with copied per-server entries. It includes `totalTools`, `totalResources`, `connectedCount`, and `disabledCount`; each server includes `name`, `status`, `toolCount`, and `disabled`, with `resourceCount` when known and `failedAgoSeconds` only for an active failure. Reading status never connects a lazy server, starts authentication, or exposes SDK clients, transports, credentials, or server definitions. An initial snapshot is emitted after initialization, updates are emitted for status and metadata changes, and an empty snapshot is emitted when the session shuts down.
+The snapshot is read-only machine-readable data with copied per-server entries. It includes `totalTools`, `totalResources`, `connectedCount`, and `disabledCount`; each server includes `name`, `status`, `toolCount`, and `disabled`, with `resourceCount` when known and `failedAgoSeconds` only for an active failure. Reading status never connects a lazy server, starts authentication, or exposes SDK clients, transports, credentials, or server definitions. An initial snapshot is emitted after initialization, updates are emitted for status and metadata changes, and an empty snapshot is emitted when the session shuts down. Initialization withholds that first snapshot until authoritative metadata has been reconciled into Pi's active direct-tool registry. A `connected` snapshot therefore follows model-facing tool-surface synchronization, including removal of stale cached tools when the authoritative catalog is empty.
 
 In the configuration examples below, `30000` is illustrative only. If `requestTimeoutMs` is omitted or set to `<= 0`, the MCP SDK default timeout is used.
 
@@ -219,6 +255,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `oauth.logoUri` | Client logo URL advertised during Dynamic Client Registration fallback (RFC 7591 `logo_uri`). Must be an absolute `http(s)` URL — consent screens fetch it server-side, so local paths render nothing. Omitted from the registration request when unset |
 | `oauth.skipIssuerMetadataValidation` | `true` disables the OAuth authorization-server metadata issuer check for this server. This weakens OAuth mix-up protection and should only be used for known-misconfigured internal servers while their metadata is being fixed. |
 | `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 `!`. |
+| `bearerTokenStore` | Set to `true` to read a static bearer token from the adapter-owned OS credential store when `auth` is `"bearer"` and no `bearerToken` or `bearerTokenEnv` is configured. Stored records are keyed only by the server name, bind to the resolved server URL, and are never named by config. Store a token with `pi-mcp-adapter token set <server>`, which reads it from a masked prompt or stdin pipe and never from an argument. `/mcp token status <server>` and `/mcp token remove <server>` manage non-secret state inside Pi; `/mcp token set` stays disabled until Pi exposes masked secret input. |
 | `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) |
@@ -249,6 +286,8 @@ If an internal authorization server publishes mismatched OAuth metadata and cann
 
 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.
 
+For local desktop bearer tokens, `bearerTokenStore: true` can opt in to the adapter-owned credential-store namespace. It never falls back to plaintext if the store is unavailable, if the stored record is malformed, or if the stored URL differs from the effective server URL. Literal tokens, command tokens, and environment tokens keep precedence so existing configs do not change. Create or rotate a stored token with `pi-mcp-adapter token set <server>` (masked prompt on a terminal, or piped stdin such as `security find-generic-password -s my-token -w | pi-mcp-adapter token set <server>`); the record binds to the effective configured URL at write time. Token commands need Node 22.18+.
+
 ### 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:
@@ -293,8 +332,10 @@ You can also pass only the `code` query parameter with `args: { code: "..." }`.
 
 - **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
 - **`eager`** — Connect at startup but don't auto-reconnect if the connection drops. No idle timeout by default (set `idleTimeout` explicitly to enable).
-- **`keep-alive`** — Connect at startup. Auto-reconnect via health checks. No idle timeout. Use for servers you always need available.
-- **`lazy-keep-alive`** — Don't connect at startup. Connect on first tool call (like `lazy`). Once spawned, never idle-shut down and auto-reconnect via health checks if the process dies (like `keep-alive`). Use for servers that are expensive to start but should stay resident after their first use.
+- **`keep-alive`** — Connect at startup. Remote HTTP servers refresh their tool catalog during health checks, before user input, and before adapter-triggered turns, reconnecting when the server reports that the session expired. No idle timeout. Use for servers you always need available.
+- **`lazy-keep-alive`** — Don't connect at startup. Connect on first tool call (like `lazy`). Once spawned, never idle-shut down and use the same catalog refresh and reconnect checks as `keep-alive`. Use for servers that are expensive to start but should stay resident after their first use.
+
+For remote HTTP keep-alive servers, the authoritative `tools/list` refresh is also the fallback when `list_changed` notifications are unavailable or their stream is lost. Each `tools/list` or `ping` request is capped at 5 seconds, up to 10 servers are checked concurrently, and transient failures use bounded backoff. A successful refresh updates metadata without reconnecting; a response proving that the HTTP session expired triggers a full reconnect and reinstalls the notification handlers. Dynamic direct-tool registration follows the refreshed metadata unless `freezeDirectTools` is enabled.
 
 When any enabled server uses `eager` or `keep-alive`, initialization also starts when the extension loads. This supports hosts that embed Pi programmatically and never emit `session_start`; if a session does start later, the session-owned runtime supersedes the load-time runtime.
 
@@ -658,7 +699,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 
 `mcp({ connect: "server-name" })` refreshes an already connected server, so new tools, resources, prompts, and instructions can load without restarting Pi.
 
-MCP proxy and direct-tool results use compact self-rendered rows by default. Collapsed success output shows the call title and the first result line, with a `Ctrl+O to expand` hint when more text is hidden. The full result remains available when expanded and is still returned unchanged to the model. Set `settings.toolResultRendering` to `"boxed"` to restore the legacy boxed Pi row, or set `settings.collapsedResultLines` to `2` or `3` when you want more collapsed text.
+MCP proxy and direct-tool results use compact self-rendered rows by default. Collapsed success output shows the call title, a bounded one-line input preview when arguments exist, and the first result line, with a `Ctrl+O to expand` hint when more text is hidden. The full result remains available when expanded and is still returned unchanged to the model. Set `settings.toolResultRendering` to `"boxed"` to restore the legacy boxed Pi row, or set `settings.collapsedResultLines` to `2` or `3` when you want more collapsed text.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, description, and any configured `searchKeywords`, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
 
@@ -698,6 +739,7 @@ Servers that provide usage guidance via the MCP `instructions` field surface it
 | Command | What it does |
 |---------|--------------|
 | `/mcp` | Interactive panel and first-run onboarding surface |
+| `/pi-mcp` | Alias for `/mcp` when the host reserves `/mcp` |
 | `/mcp setup` | Guided setup for imports, a minimal `.mcp.json`, curated known servers, RepoPrompt quick-add, and config-path inspection |
 | `/mcp tools` | List all tools |
 | `/mcp prompts` | List all MCP prompts registered as slash commands |
@@ -725,7 +767,7 @@ Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12.
 - Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
 - npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
 - MCP server validates arguments, not the adapter
-- Keep-alive servers get health checks and auto-reconnect
+- Remote keep-alive servers force-refresh their tool catalog during health checks, before user input, and before adapter-triggered turns, with bounded reconnect backoff
 - Specific tools can be promoted from the proxy to first-class Pi tools via `directTools` config, so the LLM sees them directly instead of having to search
 
 ## Limitations

package/node_modules/pi-mcp-adapter/cli.js

@@ -73,6 +73,11 @@ function printHelp(log = console.log) {
   log("  pi-mcp-adapter init       Detect host configs and scaffold Pi imports");
   log("  pi-mcp-adapter init --dry-run");
   log("  pi-mcp-adapter init --discover-host-configs  Opt in to host config fallback discovery");
+  log("");
+  log("Bearer token storage (servers configured with auth: \"bearer\" and bearerTokenStore: true):");
+  log("  pi-mcp-adapter token set <server>     Store a token read from stdin (masked prompt or pipe; never argv)");
+  log("  pi-mcp-adapter token status <server>  Report whether a stored token matches the configured URL");
+  log("  pi-mcp-adapter token remove <server>  Remove the stored token");
 }
 
 function readJsonFile(filePath) {
@@ -194,7 +199,160 @@ async function runInit(argv, log = console.log) {
   return 0;
 }
 
-export async function main(argv = process.argv.slice(2), log = console.log, error = console.error) {
+async function importTokenModules(error) {
+  try {
+    const [store, config, utils] = await Promise.all([
+      import("./mcp-bearer-store.ts"),
+      import("./config.ts"),
+      import("./utils.ts"),
+    ]);
+    return { store, config, utils };
+  } catch (err) {
+    error("Token commands need a Node.js version that can load TypeScript modules (Node 22.18+ or 23+).");
+    error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+}
+
+function readTokenFromStdin(stdin) {
+  if (stdin.isTTY) return readTokenMasked(stdin);
+  return new Promise((resolve, reject) => {
+    let data = "";
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    stdin.on("end", () => resolve(data.replace(/[\r\n]+$/, "")));
+    stdin.on("error", reject);
+  });
+}
+
+// Raw-mode masked prompt: the token never echoes to the terminal.
+function readTokenMasked(stdin) {
+  return new Promise((resolve, reject) => {
+    process.stderr.write("Enter bearer token (input hidden): ");
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let token = "";
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\u0003") {
+          cleanup();
+          reject(new Error("Token entry cancelled"));
+          return;
+        }
+        if (char === "\r" || char === "\n") {
+          cleanup();
+          resolve(token);
+          return;
+        }
+        if (char === "\u007f" || char === "\b") {
+          token = token.slice(0, -1);
+          continue;
+        }
+        token += char;
+      }
+    };
+    const cleanup = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      process.stderr.write("\n");
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function runToken(argv, log, error, stdin) {
+  const [action, serverName, ...extra] = argv;
+  if (!["set", "status", "remove"].includes(action) || !serverName) {
+    error("Usage: pi-mcp-adapter token <set|status|remove> <server>");
+    error("`token set` reads the token from stdin only. Never pass the token as an argument.");
+    return 1;
+  }
+  if (extra.length > 0) {
+    error("Unexpected extra arguments. The token must not be passed on the command line; pipe it on stdin or use the interactive prompt.");
+    return 1;
+  }
+
+  const modules = await importTokenModules(error);
+  if (!modules) return 1;
+
+  // Argv-derived text is sanitized before terminal output, and the resolved
+  // URL is never printed: it can embed userinfo or interpolated secrets.
+  const safeName = modules.utils.sanitizeTerminalText(serverName);
+  const definition = modules.config.loadMcpConfig(undefined, process.cwd()).mcpServers[serverName];
+  if (!definition) {
+    error(`Server "${safeName}" not found in the effective MCP config.`);
+    return 1;
+  }
+  if (definition.auth !== "bearer" || definition.bearerTokenStore !== true) {
+    error(`Server "${safeName}" is not configured for bearerTokenStore. Set "auth": "bearer" and "bearerTokenStore": true.`);
+    return 1;
+  }
+  // resolveServerUrl embeds the interpolated URL in its exceptions, so catch
+  // and redact: the URL can carry userinfo or interpolated secrets.
+  let serverUrl;
+  try {
+    serverUrl = modules.utils.resolveServerUrl(definition);
+  } catch {
+    error(`Server "${safeName}" has an invalid or unresolvable URL. Fix the server's url in the MCP config and retry.`);
+    return 1;
+  }
+  if (!serverUrl) {
+    error(`Server "${safeName}" has no URL configured.`);
+    return 1;
+  }
+
+  if (action === "set") {
+    const token = await readTokenFromStdin(stdin);
+    if (!token) {
+      error("No token provided on stdin.");
+      return 1;
+    }
+    try {
+      modules.store.saveBearerTokenForUrl(serverName, token, serverUrl);
+    } catch (err) {
+      error(modules.utils.sanitizeTerminalText(err instanceof Error ? err.message : String(err)));
+      return 1;
+    }
+    log(`Bearer token stored for "${safeName}" and bound to the configured server URL.`);
+    if (definition.bearerToken !== undefined || definition.bearerTokenEnv !== undefined) {
+      log("Note: this server also configures bearerToken or bearerTokenEnv, which take precedence over the stored token.");
+    }
+    return 0;
+  }
+
+  if (action === "status") {
+    const status = modules.store.inspectBearerTokenForUrl(serverName, serverUrl);
+    if (status.status === "present") {
+      log(`Bearer token is stored for "${safeName}".`);
+      return 0;
+    }
+    if (status.status === "url-mismatch") {
+      log(`Bearer token is stored for "${safeName}", but its URL does not match the current server URL. Run \`pi-mcp-adapter token set ${safeName}\` to rebind it.`);
+      return 1;
+    }
+    if (status.status === "unavailable") {
+      error(status.message);
+      return 1;
+    }
+    log(`No bearer token is stored for "${safeName}".`);
+    return 1;
+  }
+
+  try {
+    modules.store.removeBearerToken(serverName);
+  } catch (err) {
+    error(modules.utils.sanitizeTerminalText(err instanceof Error ? err.message : String(err)));
+    return 1;
+  }
+  log(`Bearer token removed for "${safeName}".`);
+  return 0;
+}
+
+export async function main(argv = process.argv.slice(2), log = console.log, error = console.error, stdin = process.stdin) {
   const [command, ...rest] = argv;
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -202,6 +360,10 @@ export async function main(argv = process.argv.slice(2), log = console.log, erro
     return 0;
   }
 
+  if (command === "token") {
+    return runToken(rest, log, error, stdin);
+  }
+
   if (command === "install") {
     error("The custom downloader has been retired.");
     error("Use `pi install npm:pi-mcp-adapter` instead, then optionally run `pi-mcp-adapter init`.");

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

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { OverlayHandle } from "@earendil-works/pi-tui";
 import type { McpExtensionState } from "./state.ts";
 import { isServerDisabled, type McpAuthResult, type McpConfig, type McpPanelCallbacks, type McpPanelResult, type ImportKind } from "./types.ts";
 import {
@@ -20,6 +21,7 @@ import { loadMetadataCache, reconstructPromptMetadata } from "./metadata-cache.t
 import { buildToolMetadata } from "./tool-metadata.ts";
 import { supportsOAuth, authenticate, removeAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { getAuthStorageOptions, inspectAuthForUrl } from "./mcp-auth.ts";
+import { inspectBearerTokenForUrl, removeBearerToken } from "./mcp-bearer-store.ts";
 import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markSharedConfigHintShown } from "./onboarding-state.ts";
 import { openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
@@ -28,6 +30,19 @@ function terminalHyperlink(label: string, url: string): string {
   return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
 }
 
+/**
+ * True when this run mode can display a `ctx.ui.custom()` overlay.
+ *
+ * `ctx.hasUI` only reports that *some* UI context is bound. In rpc/print mode
+ * that context is a headless stub whose `custom()` returns immediately without
+ * ever invoking the factory or the `done` callback, so a panel awaited through
+ * `new Promise(resolve => ctx.ui.custom(...))` never settles and the command
+ * hangs. Overlay panels therefore additionally require `ctx.mode === "tui"`.
+ */
+function canRenderPanel(ctx: ExtensionContext): boolean {
+  return ctx.hasUI && ctx.mode === "tui";
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -274,25 +289,14 @@ export async function authenticateServer(
     const authStorageOptions = getAuthStorageOptions(config.settings?.oauthDir, cwd);
     const status = await authenticate(serverName, serverUrl, definition, {
       ...(authStorageOptions.baseDir ? { authStorageOptions } : {}),
-      onAuthorizationUrl: (authorizationUrl) => {
-        ui.notify(
-          `Open this URL to authenticate ${serverName}:\n\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
-          "After approving, Pi will complete automatically if the browser can reach its localhost callback. " +
-          "On a remote machine, copy the full localhost URL from the browser address bar and paste it into Pi.",
-          "info"
-        );
-      },
+      onAuthorizationUrl: () => {},
       onAuthorizationInput: async (authorizationUrl, inputSignal) => {
-        const readyToPaste = await ui.confirm(
-          `Authorize ${serverName}`,
-          `Open this link in your browser:\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
-          "After approving access, select Yes to paste the callback URL.",
-          { signal: inputSignal },
-        );
-        if (!readyToPaste || inputSignal.aborted) return undefined;
+        if (inputSignal.aborted) return undefined;
         return ui.input(
-          `Complete ${serverName} OAuth`,
-          "Paste the full callback URL",
+          `Complete ${serverName} OAuth\n\n` +
+            `${terminalHyperlink("Open authorization page", authorizationUrl)}\n${authorizationUrl}\n\n` +
+            "Approve access, then paste the full localhost callback URL below.",
+          undefined,
           { signal: inputSignal },
         );
       },
@@ -368,6 +372,75 @@ export async function logoutServer(
   return { ok: true, message };
 }
 
+function validateBearerTokenStoreServer(
+  serverName: string,
+  state: McpExtensionState,
+): { ok: true; serverUrl: string } | { ok: false; message: string; type: "error" | "warning" } {
+  const safeName = sanitizeTerminalText(serverName);
+  const definition = state.config.mcpServers[serverName];
+  if (!definition) return { ok: false, message: `Server "${safeName}" not found in config`, type: "error" };
+  if (isServerDisabled(definition)) return { ok: false, message: `Server "${safeName}" is disabled. Run /mcp enable ${safeName}, then /reload.`, type: "warning" };
+  if (definition.auth !== "bearer" || definition.bearerTokenStore !== true) {
+    return { ok: false, message: `Server "${safeName}" is not configured for bearerTokenStore.`, type: "error" };
+  }
+  // resolveServerUrl embeds the interpolated URL in its exceptions; redact it
+  // because the URL can carry userinfo or interpolated secrets.
+  let serverUrl: string | undefined;
+  try {
+    serverUrl = resolveServerUrl(definition);
+  } catch {
+    return { ok: false, message: `Server "${safeName}" has an invalid or unresolvable URL.`, type: "error" };
+  }
+  if (!serverUrl) return { ok: false, message: `Server "${safeName}" has no URL configured.`, type: "error" };
+  return { ok: true, serverUrl };
+}
+
+export async function manageBearerToken(
+  action: "set" | "remove" | "status",
+  serverName: string,
+  state: McpExtensionState,
+  ctx: ExtensionContext,
+): Promise<{ ok: boolean; message: string }> {
+  const ui = ctx.hasUI ? ctx.ui : undefined;
+  const safeName = sanitizeTerminalText(serverName);
+  const validation = validateBearerTokenStoreServer(serverName, state);
+  if (!validation.ok) {
+    if (ui) ui.notify(validation.message, validation.type);
+    return { ok: false, message: validation.message };
+  }
+
+  if (action === "set") {
+    const message = `Cannot store bearer token here: Pi extension UI has no masked secret input primitive. Run \`pi-mcp-adapter token set ${safeName}\` in a terminal; it reads the token from stdin only.`;
+    if (ui) ui.notify(message, "error");
+    return { ok: false, message };
+  }
+
+  if (action === "status") {
+    const status = inspectBearerTokenForUrl(serverName, validation.serverUrl);
+    const message = status.status === "present"
+      ? `Bearer token is stored for "${safeName}".`
+      : status.status === "url-mismatch"
+        ? `Bearer token is stored for "${safeName}", but its URL does not match the current server URL.`
+        : status.status === "unavailable"
+          ? status.message
+          : `No bearer token is stored for "${safeName}".`;
+    if (ui) ui.notify(message, status.status === "unavailable" ? "error" : "info");
+    return { ok: status.status !== "unavailable", message };
+  }
+
+  try {
+    removeBearerToken(serverName);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (ui) ui.notify(`Failed to remove bearer token for "${safeName}": ${sanitizeTerminalText(message)}`, "error");
+    return { ok: false, message };
+  }
+
+  const message = `Bearer token removed for "${safeName}".`;
+  if (ui) ui.notify(message, "info");
+  return { ok: true, message };
+}
+
 export interface PanelFlowResult {
   configChanged: boolean;
 }
@@ -399,6 +472,10 @@ export async function openMcpSetup(
   options: { includeHostConfigs?: boolean } = {},
 ): Promise<PanelFlowResult> {
   if (!ctx.hasUI) return { configChanged: false };
+  if (!canRenderPanel(ctx)) {
+    ctx.ui.notify(`The interactive MCP setup panel is only available in the terminal UI (current mode: ${ctx.mode}). Edit .mcp.json directly, or run /mcp status to review servers.`, "info");
+    return { configChanged: false };
+  }
   if (state.programmaticConfig) {
     ctx.ui.notify("MCP setup is unavailable when config is supplied by createMcpAdapter().", "info");
     return { configChanged: false };
@@ -467,6 +544,7 @@ function buildMcpPanelCallbacks(
   state: McpExtensionState,
   config: McpConfig,
   ctx: ExtensionContext,
+  getOverlayHandle?: () => OverlayHandle | undefined,
 ): McpPanelCallbacks {
   // Panel-only diagnostics keep status inspection from mutating connection
   // failure state while allowing the existing panel failure UI to show why the
@@ -479,7 +557,16 @@ function buildMcpPanelCallbacks(
       const definition = config.mcpServers[serverName];
       return definition ? !isServerDisabled(definition) && supportsOAuth(definition) : false;
     },
-    authenticate: (serverName: string) => authenticateServer(serverName, config, ctx, state.owner?.signal, state.oauthRuntime),
+    authenticate: async (serverName: string) => {
+      const overlay = getOverlayHandle?.();
+      overlay?.setHidden(true);
+      try {
+        return await authenticateServer(serverName, config, ctx, state.owner?.signal, state.oauthRuntime);
+      } finally {
+        overlay?.setHidden(false);
+        overlay?.focus();
+      }
+    },
     getConnectionStatus: (serverName: string) => {
       authStatusFailures.delete(serverName);
       const definition = config.mcpServers[serverName];
@@ -533,6 +620,11 @@ export async function openMcpPanel(
     }
     return { configChanged: false };
   }
+  if (!canRenderPanel(ctx)) {
+    // No overlay here, but the same information is available as text.
+    await showStatus(state, ctx);
+    return { configChanged: false };
+  }
   if (Object.keys(state.config.mcpServers).length === 0) {
     return openMcpSetup(state, pi, ctx, configOverridePath, "empty", { includeHostConfigs: false });
   }
@@ -543,7 +635,8 @@ export async function openMcpPanel(
   const provenanceMap = getServerProvenance(configPath, ctx.cwd);
   const { lines: noticeLines, fingerprint } = buildSharedConfigNoticeLines(configPath, ctx.cwd);
 
-  const callbacks = buildMcpPanelCallbacks(state, config, ctx);
+  let overlayHandle: OverlayHandle | undefined;
+  const callbacks = buildMcpPanelCallbacks(state, config, ctx, () => overlayHandle);
 
   const { createMcpPanel } = await import("./mcp-panel.ts");
   let configChanged = false;
@@ -569,7 +662,11 @@ export async function openMcpPanel(
           });
         }, { noticeLines, keybindings });
       },
-      { overlay: true, overlayOptions: { anchor: "center", width: 82 } },
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: 82 },
+        onHandle: (handle) => { overlayHandle = handle; },
+      },
     );
   });
 
@@ -587,6 +684,10 @@ export async function openMcpAuthPanel(
   configOverridePath?: string,
 ): Promise<PanelFlowResult> {
   if (!ctx.hasUI) return { configChanged: false };
+  if (!canRenderPanel(ctx)) {
+    ctx.ui.notify(`The interactive MCP auth panel is only available in the terminal UI (current mode: ${ctx.mode}). Use /mcp-auth <server> to authenticate a specific server.`, "info");
+    return { configChanged: false };
+  }
   if (state.programmaticConfig) {
     ctx.ui.notify("Use /mcp-auth <server> to authenticate a server from the in-memory SDK config.", "info");
     return { configChanged: false };
@@ -604,7 +705,8 @@ export async function openMcpAuthPanel(
   const cache = loadMetadataCache();
   const configPath = pi.getFlag("mcp-config") as string | undefined ?? configOverridePath;
   const provenanceMap = getServerProvenance(configPath, ctx.cwd);
-  const callbacks = buildMcpPanelCallbacks(state, config, ctx);
+  let overlayHandle: OverlayHandle | undefined;
+  const callbacks = buildMcpPanelCallbacks(state, config, ctx, () => overlayHandle);
   const { createMcpPanel } = await import("./mcp-panel.ts");
 
   await new Promise<void>((resolve) => {
@@ -619,7 +721,11 @@ export async function openMcpAuthPanel(
           noticeLines: ["Select an OAuth MCP server and press Enter or ctrl+a to authenticate."],
         });
       },
-      { overlay: true, overlayOptions: { anchor: "center", width: 82 } },
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: 82 },
+        onHandle: (handle) => { overlayHandle = handle; },
+      },
     );
   });
 

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

@@ -6,6 +6,7 @@ import { parse as parseToml } from "smol-toml";
 import stripJsonComments from "strip-json-comments";
 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";
 
@@ -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", "requestHeadersCommand"] 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

@@ -15,7 +15,7 @@ import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates
 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";
@@ -429,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,
@@ -437,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
@@ -509,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 } : {}),
@@ -527,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),
       );