@gtrabanco/pi-nan-provider 0.8.0 → 0.10.2

package/src/commands.ts

@@ -1,45 +1,41 @@
 /**
- * `/nan-mcp` — slash command configuring BOTH MCP bridges this package
- * registers as pi tools:
+ * `/nan-mcp` — slash command configuring both native MCP servers this
+ * package registers:
  *
- * - `web-search` — the official NaN remote MCP server (api.nan.builders/mcp),
- *   exposing `nan_web_search`. Default: enabled.
- * - `nan-mcp-server` — the community stdio media server (image generation /
- *   editing, TTS, STT). Default: enabled, lazy (spawned per tool call).
+ * - `nan-search` — the official NaN remote MCP server (api.nan.builders/mcp),
+ *   exposing `mcp__nan-search__web_search`. Default: enabled.
+ * - `nan-media` — the community stdio media server (flux-2-klein / kokoro /
+ *   whisper), exposing `mcp__nan-media__generate_image` etc. Default: enabled.
  *
- * pi has no MCP client and therefore no `/mcp` command of its own, so this
- * command owns the toggles:
- *
- * - `/nan-mcp` or `/nan-mcp status` — state of both bridges and their source.
- * - `/nan-mcp enable [target]` — enable a bridge (or both, when no target is
- *   given) and persist it in `<agentDir>/nan-provider.json`; enabled bridges
- *   register their tools immediately for the current session.
- * - `/nan-mcp disable [target]` — disable persistently. pi has no
- *   unregisterTool, so already-registered tools remain until the next
- *   session/restart; the persisted toggle governs future sessions.
+ * Both are session-scoped native servers (visible in /mcp, source "extension").
+ * /nan-mcp enables/disables them via pi.registerMcpServer / pi.unregisterMcpServer,
+ * persisting the toggle in nan-provider.json.
  *
  * Targets accept aliases: `web-search` (`search`, `web_search`, `official`,
  * `nan-web-search`) and `nan-mcp-server` (`media`, `media-mcp`, `nan-media`).
  * Explicit env vars (NAN_MCP_TOOLS, NAN_MEDIA_MCP) override the persisted
  * toggles for the session.
+ *
+ * Native behavior changes from the old bridge:
+ * - `disable` IMMEDIATELY hides tools (unregisterMcpServer disconnects the
+ *   server; the MCP extension hides tools when disconnected).
+ * - `enable` IMMEDIATELY registers the server for the current session.
+ * - `status` reads the server state from pi.getMcpServers().
+ * - Missing API key at load: server is NOT registered; guidance notification
+ *   replaces the old "errors at call time" behavior.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { mediaMcpCommand, mediaMcpEnabled, mediaMcpSource } from "./mcp/nan-media.ts";
-import { webSearchBridgeEnabled, webSearchBridgeSource } from "./mcp/nan-search.ts";
-import { NAN_STATE_FILE, readBridgeState, writeBridgeState, type BridgeKey } from "./mcp/state.ts";
-
-export interface NanMcpCommandOptions {
-	/** Register web-search bridge tools now; must skip already-registered tools. */
-	registerWebSearchTools: () => void;
-	/** Register media bridge tools now; must skip already-registered tools. */
-	registerMediaTools: () => void;
-}
+import { mediaMcpCommand, mediaMcpEnabled, mediaMcpSource, mediaMcpEnvExplicit, mediaMcpEnvTruthy, mediaMcpTimeoutSec } from "./mcp/media-server.ts";
+import { webSearchBridgeEnabled, webSearchBridgeSource, mcpToolsEnvExplicit, mcpToolsDisabled } from "./mcp/api-key.ts";
+import { NAN_API_KEY_ENV, tryResolveNanApiKeyViaRegistry, resolveStoredNanApiKey } from "./mcp/api-key.ts";
+import { NAN_STATE_FILE, MCP_SERVER_NAMES, readBridgeState, writeBridgeState, type BridgeKey, readState, writeState } from "./mcp/state.ts";
+import { connectorMissingMessage, hasMcpConnector } from "./mcp/host-support.ts";
 
 const USAGE =
 	"Usage: /nan-mcp [status] · /nan-mcp enable [web-search|nan-mcp-server] · /nan-mcp disable [web-search|nan-mcp-server]";
 
-/** Canonical bridge targets with aliases (e.g. `/mcp enable nan-mcp-server` muscle memory). */
+/** Canonical bridge targets with aliases. */
 const TARGETS: Record<string, BridgeKey> = {
 	"web-search": "webSearch",
 	search: "webSearch",
@@ -67,19 +63,72 @@ function sourceLabel(bridge: BridgeKey, source: "env" | "persisted" | "default")
 	if (source === "persisted") {
 		return `persisted in <agentDir>/${NAN_STATE_FILE} (${targetName(bridge)}: ${readBridgeState(bridge)})`;
 	}
-	return "default (both bridges are enabled and lazy by default)";
+	return "default (both bridges are enabled by default)";
+}
+
+/** Resolve a bridge key to its native server name. */
+function serverName(bridge: BridgeKey): string {
+	return MCP_SERVER_NAMES[bridge];
+}
+
+/** Describe the bridge in the status message. */
+function bridgeDescription(bridge: BridgeKey): string {
+	return bridge === "webSearch"
+		? "web-search bridge (official NaN MCP → mcp__nan-search__web_search)"
+		: "nan-mcp-server bridge (community media MCP → mcp__nan-media__generate_image/edit_image/text_to_speech/list_voices/speech_to_text)";
+}
+
+/** Check if a native server of this name is currently registered. */
+function nativeServerRegistered(pi: ExtensionAPI, name: string): boolean {
+	try {
+		return pi.getMcpServers().some((s) => s.name === name);
+	} catch {
+		return false;
+	}
+}
+
+/** Status message listing both bridges' gate state and native registration.
+ * `ctx` is the command context (provides modelRegistry for key lookup).
+ */
+async function statusMessage(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<string> {
+	const lines: string[] = [];
+
+	if (!hasMcpConnector(pi)) {
+		lines.push(connectorMissingMessage([MCP_SERVER_NAMES.webSearch, MCP_SERVER_NAMES.mediaMcp]));
+	}
+
+	for (const bridge of ["webSearch" as BridgeKey, "mediaMcp" as BridgeKey]) {
+		const enabled = bridge === "webSearch" ? webSearchBridgeEnabled() : mediaMcpEnabled();
+		const source = bridge === "webSearch" ? webSearchBridgeSource() : mediaMcpSource();
+		const regStatus = nativeServerRegistered(pi, serverName(bridge)) ? "registered (native)" : "not registered";
+		lines.push(`${bridgeDescription(bridge)}: ${enabled ? "enabled" : "disabled"} — ${sourceLabel(bridge, source)}, ${regStatus}.`);
+
+		if (bridge === "webSearch") {
+			// Key status for web-search
+			const keyStatus = await resolveKeyStatus(ctx);
+			lines.push(`  API key: ${keyStatus}.`);
+		}
+		if (bridge === "mediaMcp") {
+			lines.push(`  Media spawn command: ${mediaMcpCommand().join(" ")}.`);
+		}
+	}
+
+	lines.push("Configure with /nan-mcp enable|disable [web-search|nan-mcp-server]; no target = both.");
+	return lines.join("\n");
 }
 
-function statusMessage(): string {
-	return [
-		`web-search bridge (official NaN MCP → nan_web_search): ${webSearchBridgeEnabled() ? "enabled" : "disabled"} — ${sourceLabel("webSearch", webSearchBridgeSource())}.`,
-		`nan-mcp-server bridge (community media MCP → nan_generate_image/nan_edit_image/nan_text_to_speech/nan_list_voices/nan_speech_to_text): ${mediaMcpEnabled() ? "enabled" : "disabled"} — ${sourceLabel("mediaMcp", mediaMcpSource())}.`,
-		`Media spawn command: ${mediaMcpCommand().join(" ")} (per tool call, terminated after).`,
-		"Configure with /nan-mcp enable|disable [web-search|nan-mcp-server]; no target = both.",
-	].join("\n");
+/** Check API key resolution status for web-search.
+ * `ctx` is the command context (provides modelRegistry).
+ */
+async function resolveKeyStatus(ctx: ExtensionCommandContext): Promise<string> {
+	const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+	const storedKey = resolveStoredNanApiKey();
+	const envKey = process.env[NAN_API_KEY_ENV];
+	if (registryKey || storedKey || envKey) return "resolved";
+	return "NOT SET — run /login nan or export NAN_API_KEY";
 }
 
-/** Parse an optional target argument; no target = both bridges. Returns undefined target name on unknown. */
+/** Parse an optional target argument; no target = both bridges. */
 function parseTarget(token: string | undefined): { bridges: BridgeKey[]; target?: string } | undefined {
 	if (token === undefined) return { bridges: ["webSearch", "mediaMcp"] };
 	const key = TARGETS[token.toLowerCase()];
@@ -92,18 +141,25 @@ function describeBridges(bridges: BridgeKey[]): string {
 	return names.length === 2 ? "both bridges" : names.join(" and ");
 }
 
-export function registerNanMcpCommand(pi: ExtensionAPI, options: NanMcpCommandOptions): void {
+/**
+ * Check if a bridge is effectively enabled (gate resolved).
+ */
+function bridgeEffectivelyEnabled(bridge: BridgeKey): boolean {
+	return bridge === "webSearch" ? webSearchBridgeEnabled() : mediaMcpEnabled();
+}
+
+export function registerNanMcpCommand(pi: ExtensionAPI): void {
 	pi.registerCommand("nan-mcp", {
 		description:
-			"NaN MCP configuration: enable/disable/status for both bridges (official web-search + community nan-mcp-server)",
+			"NaN MCP configuration: enable/disable/status for both native servers (official web-search + community media)",
 		getArgumentCompletions: (argumentPrefix: string) => {
 			const prefix = argumentPrefix.trim().toLowerCase();
 			const items = [
-				{ value: "enable", label: "enable", description: "Enable a bridge (or both) and persist it" },
-				{ value: "disable", label: "disable", description: "Disable a bridge (or both) persistently" },
-				{ value: "status", label: "status", description: "Show current bridge status" },
-				{ value: "enable web-search", label: "enable web-search", description: "Enable the official NaN web-search bridge" },
-				{ value: "enable nan-mcp-server", label: "enable nan-mcp-server", description: "Enable the community media bridge" },
+				{ value: "enable", label: "enable", description: "Enable a native server (or both) and persist it" },
+				{ value: "disable", label: "disable", description: "Disable a native server (or both) persistently" },
+				{ value: "status", label: "status", description: "Show current server status and registration" },
+				{ value: "enable web-search", label: "enable web-search", description: "Enable the official NaN web-search server" },
+				{ value: "enable nan-mcp-server", label: "enable nan-mcp-server", description: "Enable the community media server" },
 			];
 			const filtered = items.filter((item) => item.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -114,12 +170,11 @@ export function registerNanMcpCommand(pi: ExtensionAPI, options: NanMcpCommandOp
 			const subcommand = rawSubcommand.toLowerCase();
 
 			if (subcommand === "status") {
-				ctx.ui.notify(statusMessage(), "info");
+				ctx.ui.notify(await statusMessage(pi, ctx), "info");
 				return;
 			}
 
 			if (subcommand === "enable" || subcommand === "disable") {
-				// Trailing tokens beyond the target (e.g. duplicate target names) are ignored.
 				const parsed = parseTarget(rawTarget);
 				if (parsed === undefined || rest.length > 0) {
 					ctx.ui.notify(
@@ -136,23 +191,94 @@ export function registerNanMcpCommand(pi: ExtensionAPI, options: NanMcpCommandOp
 				for (const bridge of bridges) {
 					writeBridgeState(bridge, enabled);
 				}
-				if (enabled) {
-					if (bridges.includes("webSearch")) options.registerWebSearchTools();
-					if (bridges.includes("mediaMcp")) options.registerMediaTools();
-				}
 
 				const where = target ? `for "${target}"` : "for both bridges";
 				const persistence = `persisted in <agentDir>/${NAN_STATE_FILE}`;
-				if (enabled) {
+
+				// Without an extension that handles `mcp_servers_change` pi cannot connect the
+				// servers; registering would only trigger its "no loaded extension connects MCP
+				// servers" error (see src/mcp/host-support.ts). The toggle above still persists,
+				// so it applies as soon as a connector (built-in `mcp`) is available.
+				if (enabled && !hasMcpConnector(pi)) {
 					ctx.ui.notify(
-						`Enabled ${describeBridges(bridges)} ${where}, ${persistence}. Tools are available now; both bridges are lazy (web-search calls the endpoint per request, nan-mcp-server spawns per call), so nothing runs until invoked.` +
-							" An explicit NAN_MCP_TOOLS / NAN_MEDIA_MCP env var would override this toggle.",
-						"info",
+						`Enabled ${describeBridges(bridges)} ${where}, ${persistence} — NOT registered. ` +
+							connectorMissingMessage(bridges.map(serverName)),
+						"warning",
+					);
+					return;
+				}
+
+				// Immediate native registration/unregistration.
+				for (const bridge of bridges) {
+					const name = serverName(bridge);
+					if (enabled) {
+						// Only register if gate allows it.
+						if (bridgeEffectivelyEnabled(bridge)) {
+							if (bridge === "webSearch") {
+								// Resolve key: stored credential → registry → env.
+								const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+								const storedKey = resolveStoredNanApiKey();
+								const apiKey = storedKey ?? registryKey ?? process.env[NAN_API_KEY_ENV];
+								if (apiKey) {
+									pi.registerMcpServer(name, {
+										type: "http",
+										url: "https://api.nan.builders/mcp",
+										headers: { Authorization: `Bearer ${apiKey}` },
+										exposure: "direct",
+									});
+								} else {
+									ctx.ui.notify(
+										`${NAN_API_KEY_ENV} is not set. Export it or run /login nan.`,
+										"warning",
+									);
+								}
+							} else {
+								// Resolve key for media: stored credential → registry → env.
+								const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+								const storedKey = resolveStoredNanApiKey();
+								const apiKey = storedKey ?? registryKey ?? process.env[NAN_API_KEY_ENV];
+								if (apiKey) {
+									const mediaArgs = mediaMcpCommand();
+									pi.registerMcpServer(name, {
+										type: "stdio",
+										command: mediaArgs[0]!,
+										args: mediaArgs.slice(1),
+										env: { [NAN_API_KEY_ENV]: apiKey },
+										exposure: "direct",
+										timeout: mediaMcpTimeoutSec(),
+									});
+								} else {
+									ctx.ui.notify(
+										`${NAN_API_KEY_ENV} is not set. Export it or run /login nan.`,
+										"warning",
+									);
+								}
+							}
+						}
+					} else {
+						pi.unregisterMcpServer(name);
+					}
+				}
+
+				if (enabled) {
+					// Only claim success if servers were actually registered.
+					const allRegistered = bridges.every((b: BridgeKey) =>
+						nativeServerRegistered(pi, serverName(b)),
 					);
+					if (allRegistered) {
+						ctx.ui.notify(
+							`Enabled ${describeBridges(bridges)} ${where}, ${persistence}. Native servers registered for this session.`,
+							"info",
+						);
+					} else {
+						ctx.ui.notify(
+							`Enabled ${describeBridges(bridges)} ${where}, ${persistence} — API key missing; servers not registered.`,
+							"warning",
+						);
+					}
 				} else {
 					ctx.ui.notify(
-						`Disabled ${describeBridges(bridges)} ${where}, ${persistence}. pi has no unregisterTool, so tools already registered in this session remain until restart (or /reload); future sessions will not register them.` +
-							" An explicit NAN_MCP_TOOLS / NAN_MEDIA_MCP env var overrides this toggle.",
+						`Disabled ${describeBridges(bridges)} ${where}, ${persistence}. Native servers unregistered — tools hidden immediately.`,
 						"warning",
 					);
 				}

package/src/context-overflow-classifier.ts

@@ -1,7 +1,7 @@
 /**
  * NaN-aware context-overflow classification.
  *
- * Root cause (pi-ai, still present on 0.85.1 / main): when history is replayed
+ * Root cause (pi-ai, verified on 0.87.1): when history is replayed
  * into a DIFFERENT model, `transformMessages` downgrades every non-redacted
  * `thinking` block to plain `text` verbatim, with no size bound — and nothing
  * bounds the SUM across messages. Switching from a 1M-context model

package/src/cross-model-thinking-guard.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-model thinking guard.
  *
- * Root cause this guards against (pi-ai, still present on 0.85.1 / main): when
+ * Root cause this guards against (pi-ai, verified on 0.87.1): when
  * history is replayed into a DIFFERENT model, `transformMessages` downgrades
  * every non-redacted `thinking` block to a plain `text` block verbatim
  * (`packages/ai/src/api/transform-messages.ts`), and `openai-completions`
@@ -65,6 +65,14 @@ export function crossModelThinkingGuardEnabled(env: NodeJS.ProcessEnv = process.
 	return value !== "0" && value !== "false" && value !== "no" && value !== "off";
 }
 
+/**
+ * API id pi 0.99 assigns to virtual catalog entries (`core/virtual-models.js`,
+ * `VIRTUAL_MODEL_API`). A virtual selection routes each request to a physical
+ * model; the physical target is not exposed to the `context` hook, so the guard
+ * cannot tell which physical model will answer.
+ */
+const VIRTUAL_MODEL_API = "pi-virtual";
+
 function isGuardMessage(value: unknown): value is GuardMessage {
 	return typeof value === "object" && value !== null;
 }
@@ -85,6 +93,16 @@ export function stripCrossModelThinking<T>(
 ): readonly T[] {
 	if (!target?.provider || !options.providerIds.has(target.provider)) return messages;
 
+	// Virtual selection (pi 0.99): `ctx.model` is the selectable virtual entry
+	// (api "pi-virtual"), not the physical model the router picks for this
+	// request. Its api/id never match a physical assistant message, so the
+	// same-model check below would strip reasoning on EVERY continuation —
+	// including when the router keeps the same physical model — losing the
+	// prompt cache and thinking continuity the guard promises to preserve.
+	// The routed physical model is not available here, so skip virtual
+	// selections entirely; cross-model trimming is the router's concern there.
+	if (target.api === VIRTUAL_MODEL_API) return messages;
+
 	let changed = false;
 
 	const next = messages.map((raw) => {

package/src/fetch-models.ts

@@ -22,6 +22,7 @@
  */
 
 import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
+import type { ThinkingLevelMap } from "@earendil-works/pi-ai";
 import { GENERATED_CATALOG_META, NAN_GENERATED_MODELS } from "../scripts/models.generated.ts";
 
 export type { Model };
@@ -46,6 +47,15 @@ export interface GeneratedModelEntry {
 	 * An undefined array means the field was not set (legacy / uncatalogued).
 	 */
 	reasoningEffortValues?: string[];
+	/**
+	 * Mapping from pi-ai's user-facing thinking levels to model-specific effort
+	 * strings. When `reasoning: "off"` maps to undefined in pi-ai,
+	 * thinkingLevelMap.off supplies the effort value that NaN understands
+	 * (e.g. "none" for deepseek-v4-flash, "minimal" for glm5.3-flash).
+	 * Without this, no reasoning_effort is sent and NaN does NOT disable
+	 * reasoning, causing runaway reasoning (issue #16).
+	 */
+	thinkingLevelMap?: ThinkingLevelMap;
 	/** Compat applied to every NaN-compatible model (LiteLLM-confirmed, see scripts/generate-models.ts). */
 	compat?: OpenAICompletionsCompat;
 	/** Provenance notes for values overriding models.dev or needing manual confirmation. */
@@ -92,6 +102,7 @@ export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Mode
 		contextWindow: entry.contextWindow,
 		maxTokens: entry.maxTokens,
 		...(entry.compat ? { compat: { ...entry.compat } } : {}),
+		...(entry.thinkingLevelMap ? { thinkingLevelMap: { ...entry.thinkingLevelMap } } : {}),
 	};
 }
 

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @gtrabanco/pi-nan-provider — NaN Builders provider + MCP bridges for pi.
+ * @gtrabanco/pi-nan-provider — NaN Builders provider + native MCP servers for pi.
  *
  * What this extension registers:
  *
@@ -15,14 +15,17 @@
  *     0.84 alike), and the openai-completions streaming implementation is
  *     resolved dynamically — see provider-factory.ts for why.
  *
- *  2. MCP tools over pi's registerTool (pi intentionally has no MCP client):
- *     - `nan_web_search` via NaN's official remote MCP server
- *       (https://api.nan.builders/mcp) — on by default, NAN_MCP_TOOLS=0 to
- *       disable.
- *     - Media tools bridging the optional community `nan-mcp-server`
- *       (stdio, spawned per call) — on by default, NAN_MEDIA_MCP=0 to
- *       disable. The server spawns per tool call, so nothing runs unless
- *       audio/image/transcription is actually invoked.
+ *  2. MCP servers via pi's native registerMcpServer (pi >=0.99):
+ *     - `nan-search` — the official NaN remote MCP server
+ *       (https://api.nan.builders/mcp), exposing `mcp__nan-search__web_search`.
+ *       Default: enabled. NAN_MCP_TOOLS=0 to disable.
+ *     - `nan-media` — the community stdio media server
+ *       (flux-2-klein / kokoro / whisper), exposing
+ *       `mcp__nan-media__generate_image` etc. Default: enabled,
+ *       NAN_MEDIA_MCP=0 to disable.
+ *
+ *     Both are session-scoped (visible in /mcp with source "extension").
+ *     Exposure: `direct` — tools are declared to the model like built-ins.
  */
 
 import type { ContextEvent, ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
@@ -34,10 +37,11 @@ import {
 	stripCrossModelThinking,
 } from "./cross-model-thinking-guard.ts";
 import { baselineModels } from "./fetch-models.ts";
-import { createNanWebSearchTool, webSearchBridgeEnabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
-import { createNanMediaTools, mediaMcpEnabled } from "./mcp/nan-media.ts";
 import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
 import { PROVIDERS } from "./providers.ts";
+import { NAN_API_KEY_ENV, mcpToolsDisabled, mcpToolsEnvExplicit, resolveNanApiKey, tryResolveNanApiKeyViaRegistry, resolveStoredNanApiKey, NAN_MCP_TOOLS_ENV, webSearchBridgeEnabled } from "./mcp/api-key.ts";
+import { mediaMcpCommand, mediaMcpEnabled, mediaMcpEnvExplicit, mediaMcpEnvTruthy, mediaMcpTimeoutSec } from "./mcp/media-server.ts";
+import { registerMcpHostGuard } from "./mcp/host-support.ts";
 
 /**
  * Register a provider on any pi version: the native full-Provider overload
@@ -75,50 +79,97 @@ async function registerProviderCompat(
 			contextWindow: model.contextWindow,
 			maxTokens: model.maxTokens,
 			...(model.compat ? { compat: { ...model.compat } } : {}),
+			...(model.thinkingLevelMap ? { thinkingLevelMap: { ...model.thinkingLevelMap } } : {}),
 		})),
 	};
 	pi.registerProvider(config.id, legacy);
 }
 
+// ── Native MCP registration ──────────────────────────────────────────────
+
 /**
- * Register MCP-bridged tools when the runtime supports them. Both bridges
- * are enabled by default and lazy (nothing runs until a tool is invoked);
- * `/nan-mcp` (and the NAN_MCP_TOOLS / NAN_MEDIA_MCP env vars) toggle them.
- * Old pi versions without registerTool/registerCommand skip gracefully.
- *
- * Registration is tracked in `registeredToolNames` so `/nan-mcp enable` can
- * add tools mid-session without double-registering.
+ * Guard message shown when pi lacks native MCP support (pi <0.99 despite peers).
+ * Matches the loud-skip style of existing guards (pi-ai, registerTool).
  */
-function registerMcpToolsCompat(pi: ExtensionAPI): void {
-	if (typeof pi.registerTool !== "function") return;
-	const registeredToolNames = new Set<string>();
-	const registerSearchTool = () => {
-		const search = createNanWebSearchTool();
-		if (registeredToolNames.has(search.name)) return;
-		registeredToolNames.add(search.name);
-		pi.registerTool(search);
-	};
-	const registerMediaTools = () => {
-		for (const tool of createNanMediaTools()) {
-			if (registeredToolNames.has(tool.name)) continue;
-			registeredToolNames.add(tool.name);
-			pi.registerTool(tool);
-		}
-	};
+const NO_NATIVE_MCP_GUARD_MSG =
+	"pi-nan-provider 0.10+ requires pi >= 0.99 for MCP tools (native MCP); upgrade pi or stay on package 0.9.x";
 
-	if (webSearchBridgeEnabled()) registerSearchTool();
-	if (mediaMcpEnabled()) registerMediaTools();
-	if (typeof pi.registerCommand === "function") {
-		registerNanMcpCommand(pi, { registerWebSearchTools: registerSearchTool, registerMediaTools });
-		registerNanUsageCommand(pi);
+/** Register the official NaN web-search MCP server (session-scoped). */
+async function registerWebSearchMcpServer(pi: ExtensionAPI, apiKey: string | undefined): Promise<boolean> {
+	if (!webSearchBridgeEnabled()) return false;
+	if (!apiKey) {
+		console.warn(
+			"[pi-nan-provider] NAN_API_KEY is not set — web-search server not registered. " +
+				"Run `/login nan` in pi or export `NAN_API_KEY=<your-key>`.",
+		);
+		return false;
+	}
+	pi.registerMcpServer("nan-search", {
+		type: "http",
+		url: "https://api.nan.builders/mcp",
+		headers: { Authorization: `Bearer ${apiKey}` },
+		exposure: "direct",
+	});
+	return true;
+}
+
+/** Register the community media stdio MCP server (session-scoped). */
+function registerMediaMcpServer(pi: ExtensionAPI, apiKey: string | undefined): boolean {
+	if (!mediaMcpEnabled()) return false;
+	if (!apiKey) {
+		console.warn(
+			"[pi-nan-provider] NAN_API_KEY is not set — media server not registered. " +
+				"Run `/login nan` in pi or export `NAN_API_KEY=<your-key>`.",
+		);
+		return false;
 	}
+	const mediaArgs = mediaMcpCommand();
+	pi.registerMcpServer("nan-media", {
+		type: "stdio",
+		command: mediaArgs[0]!,
+		args: mediaArgs.slice(1),
+		env: { [NAN_API_KEY_ENV]: apiKey },
+		exposure: "direct",
+		timeout: mediaMcpTimeoutSec(),
+	});
+	return true;
 }
 
+/**
+ * Register MCP servers via pi's native registerMcpServer.
+ *
+ * Session-scoped: servers appear in /mcp with source "extension", are
+ * visible to the model (exposure: "direct"), and user mcp.json entries
+ * with the same name take precedence.
+ *
+ * On pi <0.99 (registerMcpServer absent) this does NOT bridge — it
+ * notifies once and skips (same loud-skip style as existing guards).
+ * Hard cutover: users on older pi stay on package 0.9.x.
+ */
+async function registerMcpServersNative(pi: ExtensionAPI): Promise<void> {
+	// Guard: pi >= 0.99 required for native MCP.
+	if (typeof pi.registerMcpServer !== "function") {
+		console.warn(NO_NATIVE_MCP_GUARD_MSG);
+		return;
+	}
+
+	// Resolve the API key ONCE: stored credential (auth.json) → env fallback.
+	// The factory-time ExtensionAPI has NO modelRegistry; stored credentials
+	// must be read through the coding-agent's readStoredCredential API.
+	const storedKey = resolveStoredNanApiKey();
+	const apiKey = storedKey ?? process.env[NAN_API_KEY_ENV];
+
+	await registerWebSearchMcpServer(pi, apiKey);
+	registerMediaMcpServer(pi, apiKey);
+}
+
+// ── Extension entrypoint ─────────────────────────────────────────────────
+
 /**
  * Drop the reasoning pi-ai replays across a model switch.
  *
  * pi-ai's `transformMessages` downgrades a previous model's `thinking` blocks
- * to plain text with no size bound (still true on 0.85.1 / main), and nothing
+ * to plain text with no size bound (verified on 0.87.1), and nothing
  * bounds the sum across messages — measured at 30–60% of the whole context on
  * real sessions. Switching from a 1M-context model to a 262K one (`qwen3.6`)
  * then overflows the window, and NaN's gateway answers a generic
@@ -143,10 +194,17 @@ export function registerCrossModelThinkingGuard(pi: ExtensionAPI): void {
 
 export default async function nanProviderExtension(pi: ExtensionAPI): Promise<void> {
 	registerCrossModelThinkingGuard(pi);
+	// Replaces pi's cryptic "no loaded extension connects MCP servers" error with
+	// actionable guidance when the host loads no built-in `mcp` extension (PI WEB).
+	registerMcpHostGuard(pi);
 	for (const config of PROVIDERS) {
 		await registerProviderCompat(pi, config);
 	}
-	registerMcpToolsCompat(pi);
+	await registerMcpServersNative(pi);
+	if (typeof pi.registerCommand === "function") {
+		registerNanMcpCommand(pi);
+		registerNanUsageCommand(pi);
+	}
 }
 
 /** Exposed for tests: the env var this package uses for every NaN surface. */