pi-mcp-adapter 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-04-24
+
+### Added
+- Added MCP `sampling/createMessage` support with conservative human approval by default and opt-in `settings.samplingAutoApprove` for non-interactive flows.
+- Added configured Vitest coverage for OAuth provider authorization fallback behavior.
+- Added `test:oauth-provider` for running the root OAuth provider node test with the required TypeScript loader.
+
+### Fixed
+- Applied `settings.authRequiredMessage` to proxy and direct-tool auth-required paths, including non-UI `autoAuth` failures.
+- Fixed `/mcp-auth <server>` reporting success for expired stored OAuth tokens without forcing the SDK refresh/re-auth flow.
+- Kept `mcp` search focused on MCP tools and added a direct-call hint when native Pi tools are accidentally routed through the proxy.
+
 ## [2.4.2] - 2026-04-22
 
 ### Fixed

package/README.md

@@ -158,12 +158,14 @@ Pi-specific files are the write targets for imported or shared global servers wh
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
+| `sampling` | Allow MCP servers to request LLM sampling through Pi's current/default model (default: true when UI approval is available). |
+| `samplingAutoApprove` | Skip sampling confirmation prompts. Required for sampling in non-UI sessions (default: false). |
 
 Per-server `idleTimeout` overrides the global setting.
 
 ### Direct Tools
 
-By default, all MCP tools are accessed through the single `mcp` proxy tool. This keeps context small but means the LLM has to discover tools via search. If you want specific tools to show up directly in the agent's tool list — alongside `read`, `bash`, `edit`, etc. — add `directTools` to your config.
+By default, all MCP tools are accessed through the single `mcp` proxy tool. This keeps context small but means the LLM has to discover MCP tools via proxy search. If you want specific tools to show up directly in the agent's tool list — alongside `read`, `bash`, `edit`, etc. — add `directTools` to your config.
 
 Per-server:
 
@@ -360,3 +362,4 @@ If `settings.autoAuth` is `true`, `mcp({ connect: ... })`, `mcp({ tool: ... })`,
 ## Limitations
 
 - Cross-session server sharing not yet implemented (each Pi session runs its own server processes)
+- MCP sampling support is text-only; context inclusion, tools, stop sequences, audio, and image content are rejected with explicit errors.

package/direct-tools.ts

@@ -10,6 +10,7 @@ import { maybeStartUiSession, type UiSessionRuntime } from "./ui-session.js";
 import { formatToolName, isToolExcluded } from "./types.js";
 import { resourceNameToToolName } from "./resource-tools.js";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.js";
+import { formatAuthRequiredMessage } from "./utils.js";
 
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 
@@ -18,6 +19,22 @@ type DirectAutoAuthResult =
   | { status: "success" }
   | { status: "failed"; message: string };
 
+function getDirectAuthRequiredMessage(
+  state: McpExtensionState,
+  serverName: string,
+  defaultMessage = `MCP server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} first.`,
+): string {
+  return formatAuthRequiredMessage(state.config, serverName, defaultMessage);
+}
+
+function getDirectAuthFailedMessage(state: McpExtensionState, serverName: string, message: string): string {
+  const customGuidance = state.config.settings?.authRequiredMessage;
+  if (customGuidance) {
+    return `OAuth authentication failed for "${serverName}": ${message}. ${getDirectAuthRequiredMessage(state, serverName)}`;
+  }
+  return `OAuth authentication failed for "${serverName}": ${message}. Run /mcp-auth ${serverName} first.`;
+}
+
 async function attemptDirectAutoAuth(
   state: McpExtensionState,
   serverName: string,
@@ -35,7 +52,11 @@ async function attemptDirectAutoAuth(
   if (!state.ui && grantType !== "client_credentials") {
     return {
       status: "failed",
-      message: `MCP server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} in an interactive session.`,
+      message: getDirectAuthRequiredMessage(
+        state,
+        serverName,
+        `MCP server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} in an interactive session.`,
+      ),
     };
   }
 
@@ -46,7 +67,7 @@ async function attemptDirectAutoAuth(
     const message = error instanceof Error ? error.message : String(error);
     return {
       status: "failed",
-      message: `OAuth authentication failed for "${serverName}": ${message}. Run /mcp-auth ${serverName} first.`,
+      message: getDirectAuthFailedMessage(state, serverName, message),
     };
   }
 }
@@ -187,7 +208,7 @@ export function buildProxyDescription(
   directSpecs: DirectToolSpec[],
 ): string {
   const prefix = config.settings?.toolPrefix ?? "server";
-  let desc = `MCP gateway - connect to MCP servers and call their tools.\n`;
+  let desc = `MCP gateway - connect to MCP servers and call their tools. Non-MCP Pi tools should be called directly, not through mcp.\n`;
 
   const directByServer = new Map<string, number>();
   for (const spec of directSpecs) {
@@ -229,7 +250,7 @@ export function buildProxyDescription(
   desc += `\nUsage:\n`;
   desc += `  mcp({ })                              → Show server status\n`;
   desc += `  mcp({ server: "name" })               → List tools from server\n`;
-  desc += `  mcp({ search: "query" })              → Search for tools (MCP + pi, space-separated words OR'd)\n`;
+  desc += `  mcp({ search: "query" })              → Search MCP tools by name/description\n`;
   desc += `  mcp({ describe: "tool_name" })        → Show tool details and parameters\n`;
   desc += `  mcp({ connect: "server-name" })       → Connect to a server and refresh metadata\n`;
   desc += `  mcp({ tool: "name", args: '{"key": "value"}' })    → Call a tool (args is JSON string)\n`;
@@ -290,7 +311,7 @@ export function createDirectToolExecutor(
     if (!connected) {
       const authConnection = state.manager.getConnection(spec.serverName);
       if (authConnection?.status === "needs-auth") {
-        const message = `MCP server "${spec.serverName}" requires OAuth authentication. Run /mcp-auth ${spec.serverName} first.`;
+        const message = getDirectAuthRequiredMessage(state, spec.serverName);
         return {
           content: [{ type: "text" as const, text: message }],
           details: { error: "auth_required", server: spec.serverName, message, autoAuthAttempted },

package/index.ts

@@ -296,7 +296,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           return executeUiMessages(state);
         }
         if (params.tool) {
-          return executeCall(state, params.tool, parsedArgs, params.server);
+          return executeCall(state, params.tool, parsedArgs, params.server, getPiTools);
         }
         if (params.connect) {
           return executeConnect(state, params.connect);
@@ -305,7 +305,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           return executeDescribe(state, params.describe);
         }
         if (params.search) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, getPiTools);
+          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas);
         }
         if (params.server) {
           return executeList(state, params.server);

package/init.ts

@@ -33,6 +33,16 @@ export async function initializeMcp(
   const config = loadMcpConfig(configPath);
 
   const manager = new McpServerManager();
+  const samplingAutoApprove = config.settings?.samplingAutoApprove === true;
+  if (config.settings?.sampling !== false && (ctx.hasUI || samplingAutoApprove)) {
+    manager.setSamplingConfig({
+      autoApprove: samplingAutoApprove,
+      ui: ctx.hasUI ? ctx.ui : undefined,
+      modelRegistry: ctx.modelRegistry,
+      getCurrentModel: () => ctx.model,
+      getSignal: () => ctx.signal,
+    });
+  }
   const lifecycle = new McpLifecycleManager(manager);
   const toolMetadata = new Map<string, ToolMetadata[]>();
   const failureTracker = new Map<string, number>();

package/mcp-auth-flow.ts

@@ -2,14 +2,13 @@
  * MCP Auth Flow
  * 
  * High-level OAuth flow management using the MCP SDK's built-in auth functions.
- * Follows the OpenCode pattern: let the SDK handle discovery internally via transport.
  */
 
 import {
+  auth as runSdkAuth,
   UnauthorizedError,
 } from "@modelcontextprotocol/sdk/client/auth.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
-import { Client } from "@modelcontextprotocol/sdk/client/index.js"
 import open from "open"
 import { McpOAuthProvider, type McpOAuthConfig } from "./mcp-oauth-provider.js"
 import {
@@ -66,18 +65,13 @@ function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
 
 /**
  * Start OAuth authentication flow for a server.
- * Returns the authorization URL that should be opened in a browser.
- * 
- * This follows the OpenCode pattern:
- * 1. Create transport with auth provider
- * 2. Try to connect - SDK handles discovery internally
- * 3. If UnauthorizedError, capture the auth URL from onRedirect
+ * Returns the authorization URL when browser authorization is required.
  */
 export async function startAuth(
   serverName: string,
   serverUrl: string,
   definition?: ServerEntry
-): Promise<{ authorizationUrl: string; transport: StreamableHTTPClientTransport }> {
+): Promise<{ authorizationUrl: string }> {
   const config = definition ? extractOAuthConfig(definition) : {}
 
   if (config.grantType === "client_credentials") {
@@ -86,33 +80,20 @@ export async function startAuth(
         throw new Error("Browser redirect is not used for client_credentials flow")
       },
     })
-    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
-      authProvider,
-    })
-    const client = new Client({
-      name: "pi-mcp",
-      version: "3.0.0",
-    })
-
-    try {
-      await client.connect(transport)
-      return { authorizationUrl: "", transport }
-    } finally {
-      await client.close().catch(() => {})
-      await transport.close().catch(() => {})
+    const result = await runSdkAuth(authProvider, { serverUrl })
+    if (result !== "AUTHORIZED") {
+      throw new UnauthorizedError("Failed to authorize")
     }
+    return { authorizationUrl: "" }
   }
 
   // Start the callback server.
   // Pre-registered OAuth clients require an exact redirect URI, so enforce strict port binding.
   await ensureCallbackServer({ strictPort: Boolean(config.clientId) })
 
-  // Generate and store OAuth state BEFORE creating the provider
-  // The SDK will call provider.state() to read this value
   const oauthState = generateState()
   await updateOAuthState(serverName, oauthState)
 
-  // Create the auth provider
   let capturedUrl: URL | undefined
   const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
     onRedirect: async (url) => {
@@ -120,32 +101,22 @@ export async function startAuth(
     },
   })
 
-  // Create transport with auth provider
-  // The SDK handles OAuth discovery internally when connecting
-  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
-    authProvider,
-  })
-  const client = new Client({
-    name: "pi-mcp",
-    version: "3.0.0",
-  })
-
-  // Try to connect - this triggers the OAuth flow
   try {
-    await client.connect(transport)
-    // If we get here, we're already authenticated
-    await client.close().catch(() => {})
-    await transport.close().catch(() => {})
-    return { authorizationUrl: "", transport }
-  } catch (error) {
-    if (error instanceof UnauthorizedError && capturedUrl) {
-      await client.close().catch(() => {})
-      // Store transport for later finishAuth
-      pendingTransports.set(serverName, transport)
-      return { authorizationUrl: capturedUrl.toString(), transport }
+    const result = await runSdkAuth(authProvider, { serverUrl })
+    if (result === "AUTHORIZED") {
+      await clearOAuthState(serverName)
+      return { authorizationUrl: "" }
     }
-    await client.close().catch(() => {})
-    await transport.close().catch(() => {})
+    if (!capturedUrl) {
+      throw new UnauthorizedError("OAuth authorization URL was not provided")
+    }
+    pendingTransports.set(
+      serverName,
+      new StreamableHTTPClientTransport(new URL(serverUrl), { authProvider }),
+    )
+    return { authorizationUrl: capturedUrl.toString() }
+  } catch (error) {
+    await clearOAuthState(serverName)
     throw error
   }
 }
@@ -208,19 +179,19 @@ export async function authenticate(
     // Register the callback BEFORE opening the browser
     const callbackPromise = waitForCallback(oauthState)
 
-    // Open browser
-    console.log(`MCP Auth: Opening browser for ${serverName}`)
     try {
-      await open(authorizationUrl)
-    } catch (error) {
-      console.warn(`MCP Auth: Failed to open browser for ${serverName}`, { error })
-      throw new Error(
-        `Could not open browser. Please open this URL manually: ${authorizationUrl}`,
-        { cause: error },
-      )
-    }
+      // Open browser
+      console.log(`MCP Auth: Opening browser for ${serverName}`)
+      try {
+        await open(authorizationUrl)
+      } catch (error) {
+        console.warn(`MCP Auth: Failed to open browser for ${serverName}`, { error })
+        throw new Error(
+          `Could not open browser. Please open this URL manually: ${authorizationUrl}`,
+          { cause: error },
+        )
+      }
 
-    try {
       // Wait for callback
       const code = await callbackPromise
 
@@ -236,6 +207,7 @@ export async function authenticate(
       return await completeAuth(serverName, code)
     } catch (error) {
       cancelPendingCallback(oauthState)
+      await clearOAuthState(serverName)
       const pendingTransport = pendingTransports.get(serverName)
       if (pendingTransport) {
         pendingTransports.delete(serverName)
@@ -295,31 +267,12 @@ export async function getValidToken(
         return null
       }
 
-      // Try to get tokens to find the token endpoint
-      const existingTokens = await authProvider.tokens()
-      if (!existingTokens) {
-        return null
-      }
-
-      // Create transport to trigger refresh
-      const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
-        authProvider,
-      })
-
-      // Try to connect - SDK will attempt token refresh internally
-      const client = new Client({ name: "pi-mcp", version: "3.0.0" })
-      try {
-        await client.connect(transport)
-        // Get refreshed tokens
-        const refreshed = await getAuthForUrl(serverName, serverUrl)
-        return refreshed?.tokens ?? null
-      } catch (error) {
-        console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error })
+      const result = await runSdkAuth(authProvider, { serverUrl })
+      if (result !== "AUTHORIZED") {
         return null
-      } finally {
-        await client.close().catch(() => {})
-        await transport.close().catch(() => {})
       }
+      const refreshed = await getAuthForUrl(serverName, serverUrl)
+      return refreshed?.tokens ?? null
     } catch (error) {
       console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error })
       return null

package/mcp-oauth-provider.ts

@@ -6,6 +6,7 @@
  */
 
 import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js"
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js"
 import type {
   OAuthClientMetadata,
   OAuthTokens,
@@ -200,11 +201,23 @@ export class McpOAuthProvider implements OAuthClientProvider {
   /**
    * Redirect the user to the authorization URL.
    * This opens the browser for the user to authenticate.
+   *
+   * Throws UnauthorizedError when called outside of a user-initiated flow
+   * (no oauthState saved by startAuth). That path is reached when the SDK
+   * falls through from a failed refresh into a fresh authorization_code
+   * flow, which library hosts cannot complete in-process.
    */
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
     if (this.usesClientCredentials) {
       throw new Error("redirectToAuthorization is not used for client_credentials flow")
     }
+    // No saved oauthState means we're on the post-refresh authorize fallback.
+    const entry = await getAuthEntry(this.serverName)
+    if (!entry?.oauthState) {
+      throw new UnauthorizedError(
+        `Re-authentication required for MCP server: ${this.serverName}`,
+      )
+    }
     // URL is passed to callback, not logged (may contain sensitive params)
     await this.callbacks.onRedirect(authorizationUrl)
   }
@@ -240,7 +253,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   /**
    * Get the stored OAuth state parameter.
-   * @throws Error if no state is stored
+   * @throws UnauthorizedError if no flow is in progress (see redirectToAuthorization)
    */
   async state(): Promise<string> {
     if (this.usesClientCredentials) {
@@ -248,7 +261,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }
     const entry = await getAuthEntry(this.serverName)
     if (!entry?.oauthState) {
-      throw new Error(`No OAuth state saved for MCP server: ${this.serverName}`)
+      throw new UnauthorizedError(
+        `Re-authentication required for MCP server: ${this.serverName}`,
+      )
     }
     return entry.oauthState
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,8 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "test:oauth-provider": "node --import tsx --test mcp-oauth-provider.test.ts"
   },
   "repository": {
     "type": "git",
@@ -51,6 +52,7 @@
     "ui-stream-types.ts",
     "config.ts",
     "server-manager.ts",
+    "sampling-handler.ts",
     "tool-registrar.ts",
     "resource-tools.ts",
     "lifecycle.ts",
@@ -77,6 +79,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@mariozechner/pi-ai": "^0.70.2",
     "typebox": "^1.1.24",
     "open": "^10.2.0",
     "zod": "^3.25.0 || ^4.0.0"

package/proxy-modes.ts

@@ -6,7 +6,7 @@ import { lazyConnect, updateServerMetadata, updateMetadataCache, getFailureAgeSe
 import { buildToolMetadata, getToolNames, findToolByName, formatSchema } from "./tool-metadata.js";
 import { transformMcpContent } from "./tool-registrar.js";
 import { maybeStartUiSession, type UiSessionRuntime } from "./ui-session.js";
-import { truncateAtWord } from "./utils.js";
+import { formatAuthRequiredMessage, truncateAtWord } from "./utils.js";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.js";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
@@ -16,8 +16,20 @@ type AutoAuthResult =
   | { status: "success" }
   | { status: "failed"; message: string };
 
-function getAuthRequiredMessage(serverName: string): string {
-  return `Server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} first.`;
+function getAuthRequiredMessage(
+  state: McpExtensionState,
+  serverName: string,
+  defaultMessage = `Server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} first.`,
+): string {
+  return formatAuthRequiredMessage(state.config, serverName, defaultMessage);
+}
+
+function getAuthFailedMessage(state: McpExtensionState, serverName: string, message: string): string {
+  const customGuidance = state.config.settings?.authRequiredMessage;
+  if (customGuidance) {
+    return `OAuth authentication failed for "${serverName}": ${message}. ${getAuthRequiredMessage(state, serverName)}`;
+  }
+  return `OAuth authentication failed for "${serverName}": ${message}. Run /mcp-auth ${serverName} first.`;
 }
 
 async function attemptAutoAuth(
@@ -37,7 +49,11 @@ async function attemptAutoAuth(
   if (!state.ui && grantType !== "client_credentials") {
     return {
       status: "failed",
-      message: `Server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} in an interactive session.`,
+      message: getAuthRequiredMessage(
+        state,
+        serverName,
+        `Server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} in an interactive session.`,
+      ),
     };
   }
 
@@ -48,7 +64,7 @@ async function attemptAutoAuth(
     const message = error instanceof Error ? error.message : String(error);
     return {
       status: "failed",
-      message: `OAuth authentication failed for "${serverName}": ${message}. Run /mcp-auth ${serverName} first.`,
+      message: getAuthFailedMessage(state, serverName, message),
     };
   }
 }
@@ -234,7 +250,6 @@ export function executeSearch(
   regex?: boolean,
   server?: string,
   includeSchemas?: boolean,
-  getPiTools?: () => ToolInfo[]
 ): ProxyToolResult {
   const showSchemas = includeSchemas !== false;
 
@@ -262,21 +277,6 @@ export function executeSearch(
     };
   }
 
-  const piMatches: Array<{ name: string; description: string }> = [];
-  if (!server && getPiTools) {
-    const piTools = getPiTools();
-    for (const tool of piTools) {
-      if (tool.name === "mcp") continue;
-
-      if (pattern.test(tool.name) || pattern.test(tool.description ?? "")) {
-        piMatches.push({
-          name: tool.name,
-          description: tool.description ?? "",
-        });
-      }
-    }
-  }
-
   for (const [serverName, metadata] of state.toolMetadata.entries()) {
     if (server && serverName !== server) continue;
     for (const tool of metadata) {
@@ -289,7 +289,7 @@ export function executeSearch(
     }
   }
 
-  const totalCount = piMatches.length + matches.length;
+  const totalCount = matches.length;
 
   if (totalCount === 0) {
     const msg = server
@@ -303,21 +303,6 @@ export function executeSearch(
 
   let text = `Found ${totalCount} tool${totalCount === 1 ? "" : "s"} matching "${query}":\n\n`;
 
-  for (const match of piMatches) {
-    if (showSchemas) {
-      text += `[pi tool] ${match.name}\n`;
-      text += `  ${match.description || "(no description)"}\n`;
-      text += `  No parameters (call directly).\n`;
-      text += "\n";
-    } else {
-      text += `[pi tool] ${match.name}`;
-      if (match.description) {
-        text += ` - ${truncateAtWord(match.description, 50)}`;
-      }
-      text += "\n";
-    }
-  }
-
   for (const match of matches) {
     if (showSchemas) {
       text += `${match.tool.name}\n`;
@@ -341,10 +326,7 @@ export function executeSearch(
     content: [{ type: "text" as const, text: text.trim() }],
     details: {
       mode: "search",
-      matches: [
-        ...piMatches.map(m => ({ server: "pi", tool: m.name })),
-        ...matches.map(m => ({ server: m.server, tool: m.tool.name })),
-      ],
+      matches: matches.map(m => ({ server: m.server, tool: m.tool.name })),
       count: totalCount,
       query,
     },
@@ -433,7 +415,7 @@ export async function executeConnect(state: McpExtensionState, serverName: strin
         connection = await state.manager.connect(serverName, definition);
       }
       if (connection.status === "needs-auth") {
-        const message = getAuthRequiredMessage(serverName);
+        const message = getAuthRequiredMessage(state, serverName);
         return {
           content: [{ type: "text" as const, text: message }],
           details: { mode: "connect", error: "auth_required", server: serverName, message },
@@ -463,6 +445,7 @@ export async function executeCall(
   toolName: string,
   args?: Record<string, unknown>,
   serverOverride?: string,
+  getPiTools?: () => ToolInfo[],
 ): Promise<ProxyToolResult> {
   let serverName: string | undefined = serverOverride;
   let toolMeta: ToolMetadata | undefined;
@@ -522,7 +505,7 @@ export async function executeCall(
         }
 
         if (!toolMeta && state.manager.getConnection(serverName)?.status === "needs-auth") {
-          const message = getAuthRequiredMessage(serverName);
+          const message = getAuthRequiredMessage(state, serverName);
           return {
             content: [{ type: "text" as const, text: message }],
             details: { mode: "call", error: "auth_required", server: serverName, message },
@@ -583,6 +566,16 @@ export async function executeCall(
   }
 
   if (!serverName || !toolMeta) {
+    const nativeTool = !serverOverride
+      ? getPiTools?.().find((tool) => tool.name === toolName && tool.name !== "mcp")
+      : undefined;
+    if (nativeTool) {
+      return {
+        content: [{ type: "text" as const, text: `"${toolName}" is a native Pi tool. Call ${toolName} directly instead of using mcp({ tool: "${toolName}" }).` }],
+        details: { mode: "call", error: "native_tool", requestedTool: toolName },
+      };
+    }
+
     const hintServer = serverName ?? prefixMatchedServer;
     const available = hintServer ? getToolNames(state, hintServer) : [];
     let msg = `Tool "${toolName}" not found.`;
@@ -616,7 +609,7 @@ export async function executeCall(
     }
 
     if (connection?.status === "needs-auth") {
-      const message = getAuthRequiredMessage(serverName);
+      const message = getAuthRequiredMessage(state, serverName);
       return {
         content: [{ type: "text" as const, text: message }],
         details: { mode: "call", error: "auth_required", server: serverName, message },
@@ -662,7 +655,7 @@ export async function executeCall(
         }
 
         if (connection.status === "needs-auth") {
-          const message = getAuthRequiredMessage(serverName);
+          const message = getAuthRequiredMessage(state, serverName);
           return {
             content: [{ type: "text" as const, text: message }],
             details: { mode: "call", error: "auth_required", server: serverName, message },

package/sampling-handler.ts

@@ -0,0 +1,246 @@
+import { complete, type AssistantMessage, type Message, type Model, type TextContent } from "@mariozechner/pi-ai";
+import { truncateAtWord } from "./utils.js";
+import type { ExtensionUIContext, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  CreateMessageRequestSchema,
+  type CreateMessageRequest,
+  type CreateMessageResult,
+  type SamplingMessage,
+  type SamplingMessageContentBlock,
+} from "@modelcontextprotocol/sdk/types.js";
+
+export interface SamplingHandlerOptions {
+  serverName: string;
+  autoApprove: boolean;
+  ui?: ExtensionUIContext;
+  modelRegistry: ModelRegistry;
+  getCurrentModel: () => Model<any> | undefined;
+  getSignal: () => AbortSignal | undefined;
+}
+
+export type ServerSamplingConfig = Omit<SamplingHandlerOptions, "serverName">;
+
+export function registerSamplingHandler(client: Client, options: SamplingHandlerOptions): void {
+  client.setRequestHandler(CreateMessageRequestSchema, (request) => {
+    return handleSamplingRequest(options, request as CreateMessageRequest);
+  });
+}
+
+export async function handleSamplingRequest(
+  options: SamplingHandlerOptions,
+  request: CreateMessageRequest,
+): Promise<CreateMessageResult> {
+  const params = request.params;
+
+  if ("task" in params && params.task) {
+    throw new Error("MCP sampling tasks are not supported");
+  }
+  if (params.includeContext && params.includeContext !== "none") {
+    throw new Error("MCP sampling context inclusion is not supported");
+  }
+  if (params.tools?.length) {
+    throw new Error("MCP sampling tool use is not supported");
+  }
+  if (params.toolChoice) {
+    throw new Error("MCP sampling tool choice is not supported");
+  }
+  if (params.stopSequences?.length) {
+    throw new Error("MCP sampling stop sequences are not supported");
+  }
+
+  const messages = params.messages.map(convertSamplingMessage);
+  const { model, apiKey, headers } = await resolveSamplingModel(options);
+  await confirmSampling(
+    options,
+    "Approve MCP sampling request",
+    formatRequestApproval(options.serverName, `${model.provider}/${model.id}`, params.systemPrompt, messages),
+  );
+
+  const result = await complete(
+    model,
+    {
+      systemPrompt: params.systemPrompt,
+      messages,
+    },
+    {
+      apiKey,
+      headers,
+      maxTokens: params.maxTokens,
+      temperature: params.temperature,
+      metadata: params.metadata as Record<string, unknown> | undefined,
+      signal: options.getSignal(),
+    },
+  );
+
+  const converted = convertAssistantResult(result);
+  await confirmSampling(
+    options,
+    "Return MCP sampling response",
+    formatResponseApproval(options.serverName, converted),
+  );
+  return converted;
+}
+
+function formatRequestApproval(
+  serverName: string,
+  modelName: string,
+  systemPrompt: string | undefined,
+  messages: Message[],
+): string {
+  const lines = [`${serverName} wants to sample ${messages.length} message${messages.length === 1 ? "" : "s"} with ${modelName}.`];
+  if (systemPrompt) {
+    lines.push(`System: ${truncateAtWord(systemPrompt, 400)}`);
+  }
+  for (const [index, message] of messages.entries()) {
+    lines.push(`${index + 1}. ${message.role}: ${truncateAtWord(messageText(message), 400)}`);
+  }
+  return lines.join("\n\n");
+}
+
+function formatResponseApproval(serverName: string, response: CreateMessageResult): string {
+  const text = response.content.type === "text" ? response.content.text : `[${response.content.type} content]`;
+  return `${serverName} will receive this response from ${response.model}:\n\n${truncateAtWord(text, 1000)}`;
+}
+
+function messageText(message: Message): string {
+  if (typeof message.content === "string") return message.content;
+  return message.content.map((block) => {
+    if (block.type === "text") return block.text;
+    if (block.type === "image") return `[image: ${block.mimeType}]`;
+    if (block.type === "thinking") return "[thinking]";
+    if (block.type === "toolCall") return `[tool call: ${block.name}]`;
+    return "[content]";
+  }).join("\n");
+}
+
+async function resolveSamplingModel(options: SamplingHandlerOptions): Promise<{
+  model: Model<any>;
+  apiKey?: string;
+  headers?: Record<string, string>;
+}> {
+  const candidates: Model<any>[] = [];
+  const currentModel = options.getCurrentModel();
+  if (currentModel) candidates.push(currentModel);
+
+  for (const model of options.modelRegistry.getAvailable()) {
+    if (!candidates.some((candidate) => candidate.provider === model.provider && candidate.id === model.id)) {
+      candidates.push(model);
+    }
+  }
+
+  const errors: string[] = [];
+  for (const model of candidates) {
+    const auth = await options.modelRegistry.getApiKeyAndHeaders(model);
+    if (auth.ok) {
+      return { model, apiKey: auth.apiKey, headers: auth.headers };
+    }
+    errors.push(`${model.provider}/${model.id}: ${auth.error}`);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`No configured auth for MCP sampling model. ${errors.join("; ")}`);
+  }
+  throw new Error("No Pi model is available for MCP sampling");
+}
+
+async function confirmSampling(options: SamplingHandlerOptions, title: string, message: string): Promise<void> {
+  if (options.autoApprove) return;
+  if (!options.ui) {
+    throw new Error("MCP sampling requires interactive approval. Set settings.samplingAutoApprove to true to allow it without UI.");
+  }
+  const approved = await options.ui.confirm(title, message);
+  if (!approved) {
+    throw new Error("MCP sampling request was declined");
+  }
+}
+
+function convertSamplingMessage(message: SamplingMessage): Message {
+  const blocks = Array.isArray(message.content) ? message.content : [message.content];
+  if (message.role === "user") {
+    return {
+      role: "user",
+      content: blocks.map(convertUserContent),
+      timestamp: Date.now(),
+    };
+  }
+
+  return {
+    role: "assistant",
+    content: blocks.map(convertAssistantContent),
+    api: "mcp-sampling",
+    provider: "mcp",
+    model: "sampling-request",
+    usage: zeroUsage(),
+    stopReason: "stop",
+    timestamp: Date.now(),
+  };
+}
+
+function convertUserContent(block: SamplingMessageContentBlock): TextContent {
+  if (block.type === "text") {
+    return { type: "text", text: block.text };
+  }
+  throw new Error(`MCP sampling ${block.type} content is not supported`);
+}
+
+function convertAssistantContent(block: SamplingMessageContentBlock): TextContent {
+  if (block.type === "text") {
+    return { type: "text", text: block.text };
+  }
+  throw new Error(`MCP sampling assistant ${block.type} content is not supported`);
+}
+
+function convertAssistantResult(message: AssistantMessage): CreateMessageResult {
+  if (message.stopReason === "error") {
+    throw new Error(message.errorMessage ?? "MCP sampling model call failed");
+  }
+  if (message.stopReason === "aborted") {
+    throw new Error(message.errorMessage ?? "MCP sampling model call was aborted");
+  }
+
+  const text = message.content
+    .map((block) => {
+      if (block.type === "text") return block.text;
+      if (block.type === "thinking") return undefined;
+      throw new Error(`MCP sampling result ${block.type} content is not supported`);
+    })
+    .filter((value): value is string => value !== undefined)
+    .join("\n\n")
+    .trim();
+
+  if (!text) {
+    throw new Error("MCP sampling result did not contain text content");
+  }
+
+  return {
+    role: "assistant",
+    content: { type: "text", text },
+    model: `${message.provider}/${message.model}`,
+    stopReason: mapStopReason(message.stopReason),
+  };
+}
+
+function mapStopReason(reason: AssistantMessage["stopReason"]): CreateMessageResult["stopReason"] {
+  if (reason === "stop") return "endTurn";
+  if (reason === "length") return "maxTokens";
+  if (reason === "toolUse") return "toolUse";
+  return reason;
+}
+
+function zeroUsage(): AssistantMessage["usage"] {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 0,
+    },
+  };
+}

package/server-manager.ts

@@ -16,6 +16,7 @@ import { resolveNpxBinary } from "./npx-resolver.js";
 import { logger } from "./logger.js";
 import { McpOAuthProvider } from "./mcp-oauth-provider.js";
 import { supportsOAuth } from "./mcp-auth-flow.js";
+import { registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.js";
 
 interface ServerConnection {
   client: Client;
@@ -34,6 +35,11 @@ export class McpServerManager {
   private connections = new Map<string, ServerConnection>();
   private connectPromises = new Map<string, Promise<ServerConnection>>();
   private uiStreamListeners = new Map<string, UiStreamListener>();
+  private samplingConfig: ServerSamplingConfig | undefined;
+
+  setSamplingConfig(config: ServerSamplingConfig | undefined): void {
+    this.samplingConfig = config;
+  }
   
   async connect(name: string, definition: ServerDefinition): Promise<ServerConnection> {
     // Dedupe concurrent connection attempts
@@ -64,7 +70,7 @@ export class McpServerManager {
     name: string,
     definition: ServerDefinition
   ): Promise<ServerConnection> {
-    const client = new Client({ name: `pi-mcp-${name}`, version: "1.0.0" });
+    const client = this.createClient(name);
     
     let transport: Transport;
     
@@ -141,6 +147,17 @@ export class McpServerManager {
     }
   }
   
+  private createClient(serverName: string): Client {
+    const client = new Client(
+      { name: `pi-mcp-${serverName}`, version: "1.0.0" },
+      this.samplingConfig ? { capabilities: { sampling: {} } } : undefined,
+    );
+    if (this.samplingConfig) {
+      registerSamplingHandler(client, { ...this.samplingConfig, serverName });
+    }
+    return client;
+  }
+
   private async createHttpTransport(
     definition: ServerDefinition, 
     serverName: string

package/types.ts

@@ -318,6 +318,14 @@ export interface McpSettings {
   directTools?: boolean;
   disableProxyTool?: boolean;
   autoAuth?: boolean;
+  sampling?: boolean;
+  samplingAutoApprove?: boolean;
+  /**
+   * Message returned in tool results when a server needs (re-)authentication.
+   * "${server}" is substituted with the server name. Defaults to a TUI
+   * instruction when unset.
+   */
+  authRequiredMessage?: string;
 }
 
 // Root config

package/utils.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { platform } from "node:os";
+import type { McpConfig } from "./types.js";
 
 async function execOpen(pi: ExtensionAPI, target: string, browser?: string) {
   const os = platform();
@@ -70,6 +71,15 @@ export function truncateAtWord(text: string, target: number): string {
   return truncated + "...";
 }
 
+export function formatAuthRequiredMessage(
+  config: Pick<McpConfig, "settings">,
+  serverName: string,
+  defaultMessage: string,
+): string {
+  const template = config.settings?.authRequiredMessage;
+  return template ? template.replaceAll("${server}", serverName) : defaultMessage;
+}
+
 /**
  * Extract the adapter-owned UI stream mode from tool metadata.
  */