@herbertgao/pi-extensions 2026.8.5 → 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.
 
@@ -207,6 +243,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `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. A value beginning with `!` runs a command when the HTTP server connects or OAuth authenticates; use `!!` for a literal leading `!`. |
+| `requestHeadersCommand` | Trusted executable run for every HTTP request. It receives a versioned JSON envelope containing `method`, `url`, and the exact `bodyBase64` on stdin, and must return a JSON object of headers on stdout. `command`, `args`, and `env` support environment interpolation. Use for caller-bound request signatures; failures stop the request. |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
 | `oauth.clientId` | Pre-registered OAuth client ID. MCP 2026 prefers pre-registered clients or Client ID Metadata Documents; this adapter falls back to Dynamic Client Registration when the ID is omitted and the server supports it. |
@@ -218,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) |
@@ -248,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:
@@ -292,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.
 
@@ -310,6 +352,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "toolResultRendering": "compact",
     "collapsedResultLines": 1,
     "notifyOnStartupConnect": true,
+    "warnOnLargeDirectTools": true,
     "hostConfigDiscovery": "off",
     "approveTools": ["github_delete_*", "notion_update_*"],
     "oauthDir": ".pi/mcp-oauth",
@@ -340,6 +383,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
+| `warnOnLargeDirectTools` | Show the advisory when 75 or more direct tools resolve (default: `true`). Set to `false` to suppress only this advisory. |
 | `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ connect: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
 | `scriptMode` | Register the MCP-only `mcpScript` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
@@ -544,7 +588,7 @@ To hide specific tools while still using `directTools: true`, add `excludeTools`
 
 `includeTools` and `excludeTools` filter direct tools, proxy search/list/describe, and the `/mcp` panel view.
 
-Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`. If 75+ direct tools resolve, the adapter prints a warning but still registers the tools you configured.
+Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`. If 75+ direct tools resolve, the adapter prints an advisory but still registers the tools you configured. Set `settings.warnOnLargeDirectTools` to `false` to suppress this advisory.
 
 Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only while the cache populates, then the extension hot-loads the refreshed direct tools into the current session. Servers that advertise MCP list-change notifications refresh the current session when their tool or resource list changes. On Pi versions that expose `pi.unregisterTool()`, stale direct tools are removed from the registry during refresh; older Pi versions still deactivate them from the active tool set. To force a refresh: `/mcp reconnect <server>`.
 
@@ -655,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.
 
@@ -695,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 |
@@ -722,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/agent-dir.ts

@@ -2,10 +2,18 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+export function getConfigDirName(): string {
+  const configDir = readPiConfig()?.configDir;
+  return typeof configDir === "string" && configDir.trim() ? configDir.trim() : ".pi";
+}
+
 export function getAgentDir(): string {
-  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  const piConfig = readPiConfig();
+  const name = piConfig?.name;
+  const appName = typeof name === "string" && name.trim() ? name.trim() : "pi";
+  const configured = process.env[`${appName.toUpperCase()}_CODING_AGENT_DIR`]?.trim();
   if (!configured) {
-    return join(homedir(), ".pi", "agent");
+    return join(homedir(), getConfigDirName(), "agent");
   }
   if (configured === "~") {
     return homedir();
@@ -31,12 +39,12 @@ export function getAgentPath(...segments: string[]): string {
  *
  * Falls back to "pi", which is what pi's own APP_NAME resolves to.
  */
-function readPiConfig(): { name?: unknown; clientUri?: unknown } | undefined {
+function readPiConfig(): { name?: unknown; configDir?: unknown; clientUri?: unknown } | undefined {
   const dir = process.env.PI_PACKAGE_DIR?.trim()
   if (!dir) return undefined
   try {
     const manifest = JSON.parse(readFileSync(join(resolve(dir), "package.json"), "utf8")) as {
-      piConfig?: { name?: unknown; clientUri?: unknown }
+      piConfig?: { name?: unknown; configDir?: unknown; clientUri?: unknown }
     }
     return manifest.piConfig
   } catch {

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

@@ -14,15 +14,36 @@ function expandHome(input) {
   return path.resolve(input);
 }
 
-const AGENT_DIR = process.env.PI_CODING_AGENT_DIR?.trim()
-  ? expandHome(process.env.PI_CODING_AGENT_DIR.trim())
-  : path.join(HOME, ".pi", "agent");
+function readPiConfig() {
+  const dir = process.env.PI_PACKAGE_DIR?.trim();
+  if (!dir) return undefined;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(path.resolve(dir), "package.json"), "utf8")).piConfig;
+  } catch {
+    return undefined;
+  }
+}
+
+function getConfigDirName() {
+  const configDir = readPiConfig()?.configDir;
+  return typeof configDir === "string" && configDir.trim() ? configDir.trim() : ".pi";
+}
+
+function getAgentDir() {
+  const piConfig = readPiConfig();
+  const appName = typeof piConfig?.name === "string" && piConfig.name.trim() ? piConfig.name.trim() : "pi";
+  const configured = process.env[`${appName.toUpperCase()}_CODING_AGENT_DIR`]?.trim();
+  if (configured) return expandHome(configured);
+  return path.join(HOME, getConfigDirName(), "agent");
+}
+
+const AGENT_DIR = getAgentDir();
 const PI_CONFIG_PATH = path.join(AGENT_DIR, "mcp.json");
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
 const AGENTS_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp.json");
 const AGENTS_NESTED_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp", "mcp.json");
 const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
-const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "mcp.json");
+const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), getConfigDirName(), "mcp.json");
 
 const IMPORT_PATHS = {
   cursor: [path.join(HOME, ".cursor", "mcp.json")],
@@ -52,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) {
@@ -173,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") {
@@ -181,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; },
+      },
     );
   });