pi-mcp-adapter 2.26.1 → 2.28.0

package/CHANGELOG.md

@@ -7,14 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.26.1] - 2026-08-18
+## [2.28.0] - 2026-08-26
+
+### Highlights
+- MCP connections are less fragile when servers fail, recover, move slowly, or refresh their catalogs.
+- Direct MCP tools are safer to expose, with stricter input checks and bounded result details when hosts opt in.
+- Other Pi extensions can register MCP servers at runtime without sharing module state.
+- Proxy calls now show live server progress in the interactive UI.
+- Package installs and public helper imports are easier to use from downstream hosts.
+
+### Added
+- Persistent metadata cache entries now honor server `ttlMs` hints without extending the default max age. Thanks to [@Seinra](https://github.com/Seinra) for #431.
+- Proxy tool calls now forward server progress notifications to the interactive UI. Thanks to [@Seinra](https://github.com/Seinra) for PR #440 and for mapping the area in #431.
+- Added a pure `mcp:` reference resolver API for consumers that validate adapter tool names from explicit config and cache inputs. Thanks to [@abdwhb-png](https://github.com/abdwhb-png) for PR #420.
+- Direct tools can opt into strict advertised-schema validation with one-layer JSON recovery for object and array properties. Thanks to [@4ndr3wxh1ll](https://github.com/4ndr3wxh1ll) for PR #430.
+- Direct tools can opt into guarded raw MCP result details, retaining bounded structured fields while summarizing oversized values.
+- Embedding hosts can import the configuration loader and metadata cache helpers from public package subpaths, and can validate cached metadata against an explicit private process environment.
+
+### Fixed
+- Runtime MCP registration now works across separately loaded Pi extensions through a versioned shared event contract. Thanks to [@fmoda3](https://github.com/fmoda3) for #443.
+- Stdio MCP startup errors now identify a configured missing or non-directory `cwd` instead of blaming the executable. Thanks to [@SoyElf](https://github.com/SoyElf) for #442.
+- Package installs with `--omit=dev` no longer run the public helper build during `prepare`; Git installs and package tarballs still include the built public exports. Thanks to [@KripaMishra](https://github.com/KripaMishra) for #441.
+- MCP gateway descriptions now stay stable across metadata-only refreshes and keep live counts behind `mcp({})`. Thanks to [@voidfreud](https://github.com/voidfreud) for PR #432.
+- Failed MCP servers in active backoff no longer remain advertised through cached direct tools, gateway list/search/describe results, or status tool counts. Thanks to [@voidfreud](https://github.com/voidfreud) for PR #434.
+- OAuth token invalidation now preserves credentials replaced by another Pi process instead of letting a stale refresh delete newly authorized shared credentials. Thanks to [@mjlbach](https://github.com/mjlbach) for PR #422.
+- Failed first-time MCP initialization no longer leaves the session permanently stuck with only `MCP not initialized`; the gateway keeps the failure reason and retries initialization on the next `mcp(...)` call. Thanks to [@hara-seihun](https://github.com/hara-seihun) for #428.
+- HTTP 202 and unauthenticated HTTP 401 endpoint probes now report ambiguous endpoint shape instead of claiming the URL is not MCP. Thanks to [@jayshah5696](https://github.com/jayshah5696) for #415.
+- Expanded `mcpScript` calls now show bounded submitted code. Thanks to [@DenisBalan](https://github.com/DenisBalan) for #413.
+- Gateway parameters nested inside `args` now fail with top-level guidance instead of dispatching inconsistently. Thanks to [@voidfreud](https://github.com/voidfreud) for PR #417.
+- Large direct-tool advisories now explain how to hide them with `settings.warnOnLargeDirectTools: false`. Thanks to [@afrodao2394](https://github.com/afrodao2394) for #412.
+- Namespace proxy tools now use valid cached metadata, include resource-only proxy servers, clean up only prior namespace registrations, follow `MCP_DIRECT_TOOLS` selection, and skip ambiguous normalized server names. Thanks to [@abdwhb-png](https://github.com/abdwhb-png) for PR #414.
+- Kept transient HTTP 503 connection failures as availability errors without multiplying gateway retries or misdiagnosing the endpoint as non-MCP. Thanks to [@elkaix](https://github.com/elkaix) for PR #411.
+- Preserved cached keep-alive catalogs during transient 503 refresh outages while deferred recovery continues with bounded backoff.
+- Startup connections that fail with a transient HTTP 503 now surface one quiet "temporarily unavailable; retry later" warning instead of the full hard failure; documented lifecycle behavior is unchanged, and keep-alive health checks continue their existing self-healing path. Thanks to [@elkaix](https://github.com/elkaix) for PR #424.
+
+## [2.27.0] - 2026-08-20
+
+### Highlights
+- MCP servers can now come from packages, runtime extension APIs, or the usual config files.
+- Static bearer tokens can use the OS credential store, with a stdin-only CLI for safer token management.
+- Long-lived sessions recover better when remote MCP servers are slow, refreshed, or reconnected.
+- OAuth flows clean up their callback listener when idle and work better inside nested terminal UI prompts.
+- Search, metadata cache writes, direct-tool counts, and UI stream pruning now do less repeated work.
+
+### Added
+- `/pi-mcp` now works as an alias for `/mcp` when a host reserves `/mcp`. Thanks to [@inxeoz](https://github.com/inxeoz) for #391.
+- `registerMcpServer({ pi, name, definition })` lets other extensions register and dispose session-scoped MCP servers at runtime. Registrations are proxy-tool-only, never persisted, and duplicate names fail closed. Thanks to [@bendavis78](https://github.com/bendavis78) and [@fmoda3](https://github.com/fmoda3) for the runtime API request in #376/#382.
+- Pi packages can ship prefixed MCP server definitions with `pi.mcp` manifest entries, without asking users to edit MCP config files. Thanks to [@bendavis78](https://github.com/bendavis78) for #376 and [@fmoda3](https://github.com/fmoda3) for the manifest design.
+- Static bearer tokens can opt into OS credential-store lookup with URL-bound records by setting `bearerTokenStore: true`. The new `pi-mcp-adapter token set|status|remove <server>` CLI reads tokens from stdin and never accepts a token as an argument. Thanks to [@AlexanderBartash](https://github.com/AlexanderBartash) for issue #366.
 
-### Fixed
-- Scoped “Allow for session” tool approvals to the approved arguments, so one approval no longer applies to later calls with different inputs. Thanks to [@spaceshipmike](https://github.com/spaceshipmike) for #367.
-- Stopped MCP panel commands from hanging in RPC, JSON, and print modes when terminal-only UI is unavailable. Thanks to [@shixin-guo](https://github.com/shixin-guo) for PR #365.
-- Kept compact MCP result rows useful by showing a short input preview and skipping leading blank output in collapsed previews.
-- Recovered MCP gateway requests nested inside proxy `args` instead of showing status, and now rejects invalid nested gateway requests with guidance. Thanks to [@ibrmora](https://github.com/ibrmora) for #363.
-- Kept remote keep-alive tool catalogs fresh across server restarts, so long-lived Pi sessions can discover replacement tools without restarting. Thanks to [@dmorn](https://github.com/dmorn) for #369 and PR #370.
+### Changed
+- Search ranking now reuses normalized MCP tool fields and keyword tokens per catalog.
+- Per-request header commands collect process cleanup data in one snapshot per pass, reducing cold HTTP connect overhead.
+- Metadata cache saves write compact JSON while preserving atomic replacement and cross-process merges.
+- High-frequency UI stream event-log pruning tracks the latest checkpoint event ID instead of rescanning retained patches.
+- The MCP panel reuses direct-tool counts and token totals across renders while keeping toggle and reconnect updates immediate.
+
+### Fixed
+- Short-lived `mcpScript` workers no longer emit false unmanaged file-descriptor warnings on Node 24. Thanks to [@blalor](https://github.com/blalor) for PR #407.
+- OAuth callback listeners are released after idle auth flows, and MCP pickers stay hidden while nested OAuth input is active. Thanks to [@trevorleibert-mixpanel](https://github.com/trevorleibert-mixpanel) for PRs #403 and #404.
+- Request-header command cleanup can scan large process lists without overflowing `spawnSync`'s 1 MiB default buffer, which previously caused spurious `HTTP request headers command cleanup failed: ps exited with code unknown` refresh failures on busy hosts. Thanks to [@rtfpessoa](https://github.com/rtfpessoa) for PR #399.
+- Slow but healthy remote keep-alive servers are no longer marked failed when a bounded tools/list refresh times out. Thanks to [@brightmeowso](https://github.com/brightmeowso) for #400.
+- Cached metadata reconstruction now reuses one selector candidate index, avoiding repeated scans of large cached catalogs at startup.
+- MCP status consumers no longer see a connected catalog before Pi's model-facing tool surface is current. The first connected status snapshot now waits for direct-tool synchronization. Thanks to [@dmorn](https://github.com/dmorn) for PR #380.
+- JSON-string MCP tool-call arguments are normalized before approval and transport, preserving all fields and embedded quotes. Thanks to [@sebbean](https://github.com/sebbean) for PR #377.
+- Session tool approvals are scoped to the approved argument payload instead of every later call to the same tool. Thanks to [@spaceshipmike](https://github.com/spaceshipmike) for #367.
+- MCP panel commands no longer hang in RPC, JSON, and print modes when terminal-only custom UI is unavailable. Thanks to [@shixin-guo](https://github.com/shixin-guo) for PR #365.
+- Compact MCP rows now show a bounded tool-input preview and skip leading blank output lines in collapsed result previews.
+- MCP gateway requests nested inside proxy `args` are recovered instead of silently showing status, and invalid nested gateway requests now fail with guidance. Thanks to [@ibrmora](https://github.com/ibrmora) for #363.
+- Remote keep-alive tool catalogs refresh before user input, adapter-triggered turns, and health checks. Expired Streamable HTTP sessions reconnect so long-lived Pi sessions can discover replacement catalogs without restarting. Thanks to [@dmorn](https://github.com/dmorn) for #369 and PR #370.
 
 ## [2.26.0] - 2026-08-14
 

package/README.md

@@ -24,6 +24,8 @@ pi install npm:pi-mcp-adapter
 
 Restart Pi after installation.
 
+> **DeepSeek Harness (third-party bridge):** Run the unmodified adapter in DSH via [pi2dsh](https://github.com/weijiafu14/pi2dsh); see the [verified dsh-TUI and Web MCP guide](https://github.com/weijiafu14/pi2dsh/tree/main/examples/tui-mcp).
+
 ## What happens on first run
 
 The adapter reads standard MCP files automatically. No extra setup needed if you already have them.
@@ -126,6 +128,63 @@ 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
+const MCP_RUNTIME_REGISTER_EVENT = "pi-mcp-adapter:runtime-register:v1";
+type RuntimeRegistrationRequest = {
+  version: 1;
+  name: string;
+  definition: { url: string };
+  result?:
+    | { ok: true; registration: { dispose(): Promise<void> } }
+    | { ok: false; error: Error };
+};
+
+export default function pluginHost(pi) {
+  let registration: { dispose(): Promise<void> } | undefined;
+
+  pi.on("session_start", () => {
+    if (registration) return;
+    const request: RuntimeRegistrationRequest = {
+      version: 1,
+      name: "acme__docs",
+      definition: { url: "https://mcp.example.com/mcp" },
+    };
+    pi.events.emit(MCP_RUNTIME_REGISTER_EVENT, request);
+    if (!request.result) throw new Error("pi-mcp-adapter is not installed");
+    if (!request.result.ok) throw request.result.error;
+    registration = request.result.registration;
+  });
+
+  pi.on("session_shutdown", async () => {
+    const current = registration;
+    registration = undefined;
+    await current?.dispose();
+  });
+}
+```
+
+Cross-extension registration uses Pi's shared event bus and does not require a runtime import from `pi-mcp-adapter`. Emit during `session_start` or later so the adapter listener is installed. The adapter writes `request.result` synchronously; the first adapter listener to respond wins.
+
+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.
+
 ### SDK configuration
 
 Use `createMcpAdapter` when an SDK or server integration already owns its MCP configuration:
@@ -178,7 +237,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 +278,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 +309,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:
@@ -344,6 +406,8 @@ 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. |
+| `strictDirectToolArguments` | Validate direct-tool inputs against their advertised schemas and recover one JSON string layer for object and array properties (default: false). |
+| `directToolResultDetails` | Direct-tool result details: `"lean"` (default) or `"bounded"` to retain the guarded raw MCP result. |
 | `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. |
@@ -399,7 +463,7 @@ Oversized MCP tool/resource results are guarded by default so a single huge resp
 - Inline text output is capped at **50 KiB / 2,000 lines** (matching Pi's built-in `bash` guard). Larger output is truncated to a head preview and the full text is saved to a temp file whose path is included in the result, so the agent can `read`/`grep` it.
 - **Image content blocks pass through unchanged** — only text output is guarded. Images are delivered to the provider as native image content.
 - Binary resource blobs up to **10 MiB** are decoded to private temp files and replaced with file references. Each session is limited to **100 MiB** and **10,000 files**. The files are removed at session teardown.
-- In proxy mode, `details.mcpResult` is kept raw when its JSON is **≤ 16 KiB**; larger results are replaced with a compact summary (block counts, sizes, key previews) and the raw JSON is saved to a temp file. Direct tools keep their lean details and never carry `mcpResult`.
+- In proxy mode, `details.mcpResult` is kept raw when its JSON is **≤ 16 KiB**; larger results are replaced with a compact summary (block counts, sizes, key previews) and the raw JSON is saved to a temp file. Direct tools keep lean details unless `settings.directToolResultDetails` is set to `"bounded"`, which applies the same guarded `mcpResult` limit.
 
 Tune the text and details limits with the object form:
 
@@ -553,6 +617,10 @@ Each direct tool costs ~150-300 tokens in the system prompt (name + description
 
 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>`.
 
+Models sometimes encode an object or array argument as a JSON string. Set `settings.strictDirectToolArguments` to `true` to recover one such layer for schema-declared object and array properties, then validate the complete input against the advertised schema before execution.
+
+Set `settings.directToolResultDetails` to `"bounded"` when an extension needs structured MCP result fields in Pi's direct-tool result details. The same output guard limits apply. Small leading structured fields stay available, while large fields receive bounded summaries and the complete guarded result follows the output guard's spill-file policy. The default `"lean"` mode keeps the existing server and tool metadata only.
+
 If prompt-cache stability matters more than automatic direct-tool hot-loading, set `settings.freezeDirectTools` to `true`. The initial direct-tool sync still runs, but later automatic reconnects, lazy-connects, and list-change notifications keep the registered tool surface unchanged. Deliberate refreshes through `mcp({ connect: "server" })` or `/mcp reconnect <server>` still update direct tools.
 
 When you change direct-tool toggles in `/mcp`, the extension updates direct tool registration in the current session. Broader setup writes from `/mcp setup` still use Pi's normal reload flow because they can add or restructure MCP config files.
@@ -691,15 +759,16 @@ Keys match a tool's original name, prefixed name, or a glob (`*` applies to ever
 
 When `includeSchemas` is enabled, search and describe render common JSON Schema parameters as compact TypeScript shapes like `{ query: string; limit?: number; }`, with the older schema formatter retained as a fallback for unsupported schemas.
 
-For HTTP servers, failed connects run a one-request shape probe that can turn opaque transport errors into setup hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Healthy connections are not probed.
+For HTTP servers, Pi reports HTTP 503 as temporary unavailability and does not add another immediate retry loop. Keep-alive servers keep cached metadata available and retry after 30 seconds, backing off to 5 minutes. Other failed connects run a one-request shape probe that can turn opaque transport errors into setup hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Healthy connections are not probed.
 
-Servers that provide usage guidance via the MCP `instructions` field surface it at three levels: a truncated head in the `mcp` proxy tool description itself (so the model sees it without any call), a longer preview at the end of `mcp({ server: "name" })` listings, and the full text via `mcp({ instructions: "name" })`. Instructions are captured at connect time and cached alongside tool metadata, so they stay available without a live connection.
+Servers that provide usage guidance via the MCP `instructions` field surface it through discovery paths: `mcp({ server: "name" })` includes a preview, and `mcp({ instructions: "name" })` returns the full text. Instructions are captured at connect time and cached alongside tool metadata, so they stay available without a live connection.
 
 ## Commands
 
 | 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 |

package/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/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 {
@@ -16,10 +17,12 @@ import {
   writeStarterProjectConfig,
 } from "./config.ts";
 import { markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateMetadataCache, updateStatusBar, getFailureAgeSeconds, getFailureMessage, clearFailure, recordFailure } from "./init.ts";
+import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 import { loadMetadataCache, reconstructPromptMetadata } from "./metadata-cache.ts";
 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";
@@ -129,6 +132,7 @@ export async function showTools(state: McpExtensionState, ctx: ExtensionContext)
 
   const allTools = [...state.toolMetadata.entries()]
     .filter(([serverName]) => !isServerDisabled(state.config.mcpServers[serverName]))
+    .filter(([serverName]) => !isServerInActiveFailureBackoff(state, serverName))
     .flatMap(([, metadata]) => metadata.map(m => m.name));
 
   if (allTools.length === 0) {
@@ -194,9 +198,9 @@ export async function reconnectServer(
       state.serverInstructions.delete(name);
     }
     updateMetadataCache(state, name);
-    notifyToolMetadataUpdated(state, name, "command-reconnect");
+    const restored = clearFailure(state, name, "command-reconnect");
+    if (!restored) notifyToolMetadataUpdated(state, name, "command-reconnect");
     markKeepAliveAfterConnect(state, name);
-    clearFailure(state, name);
 
     if (ui) {
       ui.notify(
@@ -287,25 +291,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 },
         );
       },
@@ -381,6 +374,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;
 }
@@ -484,6 +546,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
@@ -496,7 +559,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];
@@ -565,7 +637,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;
@@ -591,7 +664,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; },
+      },
     );
   });
 
@@ -630,7 +707,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) => {
@@ -645,7 +723,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; },
+      },
     );
   });