pi-mcp-adapter 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-06-13
+
+### Added
+- Added manual remote/headless OAuth proxy actions for copying authorization URLs and completing pasted redirect URLs or codes. Thanks @Gabrielgvl for PR #120.
+
+### Fixed
+- Honored user `tui.select.*` keybindings in MCP management, setup, and auth panels. Thanks @owenniles for PR #138.
+- Included configured OAuth scopes in authorization-code flows while preserving token endpoint authentication method selection. Thanks @carlosdagos for PR #140.
+- Fixed MCP elicitation on stock Pi, including form dialogs with validation and review, consent-based URL handling, URL-required errors, completion notifications, and TUI-only browser navigation. Thanks @dmmulroy for PR #139.
+- Expanded MCP schema formatting for nested `anyOf`/`oneOf` variants, `const` discriminators, nested object properties, and array items.
+
+## [2.9.0] - 2026-06-04
+
+### Added
+- Added MCP elicitation support with Pi form prompts and browser-opening URL requests.
+
+### Fixed
+- Rejected non-http/https MCP URL elicitations before prompting or opening a browser.
+- Preserved empty string form values for MCP string elicitations unless schema constraints reject them.
+
 ## [2.8.0] - 2026-05-25
 
 ### Added

package/README.md

@@ -142,6 +142,26 @@ Pi-specific files are the write targets for imported or shared global servers wh
 
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
 
+### Remote/headless OAuth
+
+If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool:
+
+```js
+mcp({ action: "auth-start", server: "linear-server" })
+```
+
+Open the returned authorization URL in your local browser. After approval, your browser redirects to a localhost URL. On a remote server that local page may fail to load; copy the full URL from the browser address bar anyway and complete the flow in the same Pi session:
+
+```js
+mcp({
+  action: "auth-complete",
+  server: "linear-server",
+  args: '{"redirectUrl":"http://localhost:19876/callback?code=...&state=..."}'
+})
+```
+
+You can also pass only the `code` query parameter with `args: '{"code":"..."}'`. Treat authorization URLs and codes as sensitive; they can grant access to the MCP server until the flow expires or completes.
+
 ### Lifecycle Modes
 
 - **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
@@ -169,9 +189,16 @@ For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact c
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
 | `samplingAutoApprove` | Skip sampling confirmation prompts. Required for sampling in non-UI sessions (default: false). |
+| `elicitation` | Allow MCP servers to request user input through Pi dialogs (default: true when Pi UI is available). |
 
 Per-server `idleTimeout` overrides the global setting.
 
+### MCP Elicitation
+
+When Pi exposes dialog-capable UI, the adapter advertises form elicitation support. Forms use Pi's stock `select()` and `input()` dialogs, validate the response, and provide a review/edit step before submission. Explicit refusal maps to MCP `decline`; dismissing a dialog maps to `cancel`.
+
+URL mode is advertised only in TUI mode. The adapter displays the requesting server, target host, and full URL, and always requires consent before opening the browser. It also handles URL-required tool errors (`-32042`) and completion notifications; after completing the browser interaction, retry the original tool call.
+
 ### 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 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.
@@ -339,6 +366,8 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 | Call | `mcp({ tool: "...", args: '{"key": "value"}' })` |
 | Connect | `mcp({ connect: "server-name" })` |
 | UI messages | `mcp({ action: "ui-messages" })` |
+| Auth start | `mcp({ action: "auth-start", server: "name" })` |
+| Auth complete | `mcp({ action: "auth-complete", server: "name", args: '{"redirectUrl":"..."}' })` |
 
 MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `Ctrl+O to expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
@@ -361,7 +390,7 @@ Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_li
 
 If `settings.autoAuth` is `true`, `mcp({ connect: ... })`, `mcp({ tool: ... })`, and direct tool calls automatically run OAuth when needed and retry once.
 
-In interactive sessions, you can also authenticate from `/mcp` with `ctrl+a` or Enter on a server that needs auth. In non-interactive sessions, browser-based OAuth still requires `/mcp-auth <server>`. `/mcp-auth` without a server only opens a picker in the interactive UI.
+In interactive sessions, you can also authenticate from `/mcp` with `ctrl+a` or Enter on a server that needs auth. In remote/headless sessions, use the proxy tool's `auth-start` and `auth-complete` actions to copy the authorization URL locally and paste the redirect URL back into Pi. `/mcp-auth` without a server only opens a picker in the interactive UI.
 
 ## How It Works
 

package/commands.ts

@@ -286,8 +286,8 @@ export async function openMcpSetup(
 
   return new Promise<PanelFlowResult>((resolve) => {
     ctx.ui.custom(
-      (tui, _theme, _keybindings, done) => {
-        return createMcpSetupPanel(discovery, callbacks, { mode, onboardingState }, tui, () => {
+      (tui, _theme, keybindings, done) => {
+        return createMcpSetupPanel(discovery, callbacks, { mode, onboardingState, keybindings }, tui, () => {
           done(undefined);
           resolve({ configChanged });
         });
@@ -358,7 +358,7 @@ export async function openMcpPanel(
 
   await new Promise<void>((resolve) => {
     ctx.ui.custom(
-      (tui, _theme, _keybindings, done) => {
+      (tui, _theme, keybindings, done) => {
         return createMcpPanel(config, cache, provenanceMap, callbacks, tui, (result: McpPanelResult) => {
           if (!result.cancelled && result.changes.size > 0) {
             writeDirectToolsConfig(result.changes, provenanceMap, config);
@@ -367,7 +367,7 @@ export async function openMcpPanel(
           }
           done(undefined);
           resolve();
-        }, { noticeLines });
+        }, { noticeLines, keybindings });
       },
       { overlay: true, overlayOptions: { anchor: "center", width: 82 } },
     );
@@ -403,12 +403,13 @@ export async function openMcpAuthPanel(
 
   await new Promise<void>((resolve) => {
     ctx.ui.custom(
-      (tui, _theme, _keybindings, done) => {
+      (tui, _theme, keybindings, done) => {
         return createMcpPanel(config, cache, provenanceMap, callbacks, tui, () => {
           done(undefined);
           resolve();
         }, {
           authOnly: true,
+          keybindings,
           noticeLines: ["Select an OAuth MCP server and press Enter or ctrl+a to authenticate."],
         });
       },

package/direct-tools.ts

@@ -1,4 +1,5 @@
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { UrlElicitationRequiredError } from "@modelcontextprotocol/sdk/types.js";
 import type { McpExtensionState } from "./state.ts";
 import type { DirectToolSpec, McpConfig, McpContent } from "./types.ts";
 import type { MetadataCache } from "./metadata-cache.ts";
@@ -22,7 +23,7 @@ type DirectAutoAuthResult =
 function getDirectAuthRequiredMessage(
   state: McpExtensionState,
   serverName: string,
-  defaultMessage = `MCP server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} first.`,
+  defaultMessage = `MCP server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`,
 ): string {
   return formatAuthRequiredMessage(state.config, serverName, defaultMessage);
 }
@@ -32,7 +33,7 @@ function getDirectAuthFailedMessage(state: McpExtensionState, serverName: string
   if (customGuidance) {
     return `OAuth authentication failed for "${serverName}": ${message}. ${getDirectAuthRequiredMessage(state, serverName)}`;
   }
-  return `OAuth authentication failed for "${serverName}": ${message}. Run /mcp-auth ${serverName} first.`;
+  return `OAuth authentication failed for "${serverName}": ${message}. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
 }
 
 async function attemptDirectAutoAuth(
@@ -55,7 +56,7 @@ async function attemptDirectAutoAuth(
       message: getDirectAuthRequiredMessage(
         state,
         serverName,
-        `MCP server "${serverName}" requires OAuth authentication. Run /mcp-auth ${serverName} in an interactive session.`,
+        `MCP server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`,
       ),
     };
   }
@@ -255,7 +256,9 @@ export function buildProxyDescription(
   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`;
   desc += `  mcp({ action: "ui-messages" })        → Retrieve accumulated messages from completed UI sessions\n`;
-  desc += `\nMode: tool (call) > connect > describe > search > server (list) > action > nothing (status)`;
+  desc += `  mcp({ action: "auth-start", server: "name" })      → Start manual OAuth and get a browser URL\n`;
+  desc += `  mcp({ action: "auth-complete", server: "name", args: '{"redirectUrl":"..."}' }) → Complete manual OAuth\n`;
+  desc += `\nMode: action > tool (call) > connect > describe > search > server (list) > nothing (status)`;
 
   return desc;
 }
@@ -406,6 +409,17 @@ export function createDirectToolExecutor(
         details: { server: spec.serverName, tool: spec.originalName },
       };
     } catch (error) {
+      if (error instanceof UrlElicitationRequiredError) {
+        const action = await state.manager.handleUrlElicitationRequired(spec.serverName, error);
+        const message = action === "accept"
+          ? "The original MCP tool did not run. Complete the opened browser interaction, then retry the tool."
+          : `The URL interaction was ${action === "decline" ? "declined" : "cancelled"}.`;
+        uiSession?.sendToolCancelled(message);
+        return {
+          content: [{ type: "text" as const, text: message }],
+          details: { error: "url_elicitation_required", server: spec.serverName, action },
+        };
+      }
       const message = error instanceof Error ? error.message : String(error);
       uiSession?.sendToolCancelled(message);
       let errorText = `Failed to call tool: ${message}`;

package/elicitation-handler.ts

@@ -0,0 +1,347 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  ElicitRequestSchema,
+  ErrorCode,
+  McpError,
+  type ElicitRequest,
+  type ElicitRequestFormParams,
+  type ElicitRequestURLParams,
+  type ElicitResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+import type { JsonSchemaType } from "@modelcontextprotocol/sdk/validation/types.js";
+import open from "open";
+
+export type ElicitationValue = string | number | boolean | string[] | undefined;
+type FormProperty = ElicitRequestFormParams["requestedSchema"]["properties"][string];
+
+export type ElicitationUIContext = ExtensionUIContext;
+
+export interface ElicitationHandlerOptions {
+  serverName: string;
+  ui: ElicitationUIContext;
+  allowUrl: boolean;
+  onUrlAccepted?: (elicitationId: string) => void;
+}
+
+export type ServerElicitationConfig = Omit<ElicitationHandlerOptions, "serverName" | "onUrlAccepted">;
+
+export function registerElicitationHandler(client: Client, options: ElicitationHandlerOptions): void {
+  client.setRequestHandler(ElicitRequestSchema, (request) =>
+    handleElicitationRequest(options, request));
+}
+
+export async function handleElicitationRequest(
+  options: ElicitationHandlerOptions,
+  request: ElicitRequest,
+): Promise<ElicitResult> {
+  return request.params.mode === "url"
+    ? handleUrlElicitation(options, request.params)
+    : handleFormElicitation(options, request.params);
+}
+
+export async function handleFormElicitation(
+  options: ElicitationHandlerOptions,
+  params: ElicitRequestFormParams,
+): Promise<ElicitResult> {
+  const decision = await options.ui.select(
+    `MCP Input Request\nServer: ${options.serverName}\n\n${params.message}`,
+    ["Continue", "Decline"],
+  );
+  if (decision === undefined) return { action: "cancel" };
+  if (decision === "Decline") return { action: "decline" };
+
+  const values: Record<string, ElicitationValue> = {};
+  const properties = Object.entries(params.requestedSchema.properties);
+  for (const [name, schema] of properties) {
+    const value = await collectValidField(options.ui, params, name, schema);
+    if (!("value" in value)) return { action: "cancel" };
+    values[name] = value.value;
+  }
+
+  while (true) {
+    const content = coerceAndValidateFormValues(params, values);
+    const action = await options.ui.select(
+      formatReview(options.serverName, properties, content),
+      properties.length > 0 ? ["Submit", "Edit", "Decline"] : ["Submit", "Decline"],
+    );
+    if (action === undefined) return { action: "cancel" };
+    if (action === "Decline") return { action: "decline" };
+    if (action === "Submit") return { action: "accept", content };
+
+    const labels = properties.map(([name, schema]) => `${schema.title ?? humanizeName(name)} (${name})`);
+    const selected = await options.ui.select("Choose a field to edit", labels);
+    if (selected === undefined) return { action: "cancel" };
+    const property = properties[labels.indexOf(selected)];
+    if (!property) continue;
+    const [name, schema] = property;
+    const value = await collectValidField(options.ui, params, name, schema, values[name]);
+    if (!("value" in value)) return { action: "cancel" };
+    values[name] = value.value;
+  }
+}
+
+async function collectValidField(
+  ui: ElicitationUIContext,
+  params: ElicitRequestFormParams,
+  name: string,
+  schema: FormProperty,
+  current?: ElicitationValue,
+): Promise<{ cancelled: true } | { cancelled: false; value: ElicitationValue }> {
+  const required = params.requestedSchema.required?.includes(name) === true;
+  while (true) {
+    const result = await collectField(ui, params, name, schema, current);
+    if (!("value" in result)) return result;
+    try {
+      coerceAndValidateFormValues({
+        ...params,
+        requestedSchema: {
+          type: "object",
+          properties: { [name]: schema },
+          ...(required ? { required: [name] } : {}),
+        },
+      }, { [name]: result.value });
+      return result;
+    } catch (error) {
+      ui.notify(error instanceof Error ? error.message : String(error), "error");
+      current = result.value;
+    }
+  }
+}
+
+async function collectField(
+  ui: ElicitationUIContext,
+  params: ElicitRequestFormParams,
+  name: string,
+  schema: FormProperty,
+  current?: ElicitationValue,
+): Promise<{ cancelled: true } | { cancelled: false; value: ElicitationValue }> {
+  const required = params.requestedSchema.required?.includes(name) === true;
+  const title = [schema.title ?? humanizeName(name), required ? "(required)" : "", schema.description]
+    .filter(Boolean)
+    .join(" ");
+
+  if (schema.type === "string" && ("enum" in schema || "oneOf" in schema)) {
+    const choices = "oneOf" in schema
+      ? schema.oneOf.map(option => ({ value: option.const, display: formatChoice(option.const, option.title) }))
+      : schema.enum.map((value, index) => ({
+          value,
+          display: formatChoice(value, "enumNames" in schema ? schema.enumNames?.[index] : undefined),
+        }));
+    const displays = uniqueLabels(choices.map(choice => choice.display));
+    const actions = [...displays];
+    const useDefault = schema.default === undefined ? undefined : uniqueAction("Use default", actions);
+    if (useDefault) actions.push(useDefault);
+    const omit = required ? undefined : uniqueAction("Omit", actions);
+    if (omit) actions.push(omit);
+    const action = await ui.select(title, actions);
+    if (action === undefined) return { cancelled: true };
+    if (action === useDefault) return { cancelled: false, value: schema.default };
+    if (action === omit) return { cancelled: false, value: undefined };
+    return { cancelled: false, value: choices[displays.indexOf(action)]?.value };
+  }
+
+  if (schema.type === "boolean") {
+    const actions = ["Yes", "No"];
+    if (schema.default !== undefined) actions.push("Use default");
+    if (!required) actions.push("Omit");
+    const action = await ui.select(title, actions);
+    if (action === undefined) return { cancelled: true };
+    if (action === "Use default") return { cancelled: false, value: schema.default };
+    if (action === "Omit") return { cancelled: false, value: undefined };
+    return { cancelled: false, value: action === "Yes" };
+  }
+
+  if (schema.type === "array") {
+    const actions = ["Choose values"];
+    if (schema.default !== undefined) actions.push("Use default");
+    if (!required) actions.push("Omit");
+    const action = await ui.select(title, actions);
+    if (action === undefined) return { cancelled: true };
+    if (action === "Use default") return { cancelled: false, value: schema.default };
+    if (action === "Omit") return { cancelled: false, value: undefined };
+
+    const choices = extractMultiSelectOptions(schema);
+    const selected = new Set(Array.isArray(current) ? current : []);
+    while (true) {
+      const displays = uniqueLabels(choices.map(choice => selected.has(choice.value) ? `✓ ${choice.display}` : choice.display));
+      const done = uniqueAction("Done", displays);
+      const picked = await ui.select(title, [...displays, done]);
+      if (picked === undefined) return { cancelled: true };
+      if (picked === done) return { cancelled: false, value: [...selected] };
+      const choice = choices[displays.indexOf(picked)];
+      if (!choice) continue;
+      if (selected.has(choice.value)) selected.delete(choice.value);
+      else selected.add(choice.value);
+    }
+  }
+
+  const actions = ["Enter value"];
+  if (schema.default !== undefined) actions.push("Use default");
+  if (!required) actions.push("Omit");
+  const action = await ui.select(title, actions);
+  if (action === undefined) return { cancelled: true };
+  if (action === "Use default") return { cancelled: false, value: schema.default };
+  if (action === "Omit") return { cancelled: false, value: undefined };
+  const entered = await ui.input(title, current === undefined ? undefined : String(current));
+  return entered === undefined ? { cancelled: true } : { cancelled: false, value: entered };
+}
+
+export function coerceAndValidateFormValues(
+  params: ElicitRequestFormParams,
+  values: Record<string, ElicitationValue>,
+): Record<string, string | number | boolean | string[]> {
+  const output: Record<string, string | number | boolean | string[]> = {};
+  const required = new Set(params.requestedSchema.required ?? []);
+  for (const [name, schema] of Object.entries(params.requestedSchema.properties)) {
+    const value = values[name];
+    if (value === undefined) {
+      if (required.has(name)) throw new Error(`Missing required elicitation field: ${name}`);
+      continue;
+    }
+    if (schema.type === "string") {
+      const stringValue = String(value);
+      const limits = schema as typeof schema & { minLength?: number; maxLength?: number };
+      if (limits.minLength !== undefined && stringValue.length < limits.minLength) {
+        throw new Error(`Elicitation field ${name} is shorter than minimum length ${limits.minLength}`);
+      }
+      if (limits.maxLength !== undefined && stringValue.length > limits.maxLength) {
+        throw new Error(`Elicitation field ${name} is longer than maximum length ${limits.maxLength}`);
+      }
+      if ("enum" in schema && !schema.enum.includes(stringValue)) {
+        throw new Error(`Elicitation field ${name} is not an allowed value`);
+      }
+      if ("oneOf" in schema && !schema.oneOf.some(option => option.const === stringValue)) {
+        throw new Error(`Elicitation field ${name} is not an allowed value`);
+      }
+      output[name] = stringValue;
+      continue;
+    }
+    if (schema.type === "number" || schema.type === "integer") {
+      if (typeof value === "string" && value.trim() === "") {
+        throw new Error(`Elicitation field ${name} must be a number`);
+      }
+      const numberValue = typeof value === "number" ? value : Number(value);
+      if (!Number.isFinite(numberValue)) throw new Error(`Elicitation field ${name} must be a number`);
+      if (schema.type === "integer" && !Number.isInteger(numberValue)) {
+        throw new Error(`Elicitation field ${name} must be an integer`);
+      }
+      if (schema.minimum !== undefined && numberValue < schema.minimum) {
+        throw new Error(`Elicitation field ${name} is below minimum ${schema.minimum}`);
+      }
+      if (schema.maximum !== undefined && numberValue > schema.maximum) {
+        throw new Error(`Elicitation field ${name} is above maximum ${schema.maximum}`);
+      }
+      output[name] = numberValue;
+      continue;
+    }
+    if (schema.type === "boolean") {
+      output[name] = typeof value === "boolean" ? value : value === "true";
+      continue;
+    }
+    if (schema.type === "array") {
+      if (!Array.isArray(value)) throw new Error(`Elicitation field ${name} must be a list`);
+      const allowed = new Set(extractMultiSelectOptions(schema).map(option => option.value));
+      const arrayValue = value.map(String);
+      if (schema.minItems !== undefined && arrayValue.length < schema.minItems) {
+        throw new Error(`Elicitation field ${name} has fewer than ${schema.minItems} selections`);
+      }
+      if (schema.maxItems !== undefined && arrayValue.length > schema.maxItems) {
+        throw new Error(`Elicitation field ${name} has more than ${schema.maxItems} selections`);
+      }
+      if (arrayValue.some(item => !allowed.has(item))) {
+        throw new Error(`Elicitation field ${name} contains an invalid selection`);
+      }
+      output[name] = arrayValue;
+    }
+  }
+  const validation = new AjvJsonSchemaValidator()
+    .getValidator(params.requestedSchema as JsonSchemaType)(output);
+  if (!validation.valid) {
+    throw new Error(`Invalid elicitation response: ${validation.errorMessage}`);
+  }
+  return output;
+}
+
+function formatChoice(value: string, title?: string): string {
+  return title && title !== value ? `${title} (${value})` : value;
+}
+
+function uniqueLabels(labels: string[]): string[] {
+  const used = new Set<string>();
+  return labels.map(label => {
+    let unique = label;
+    while (used.has(unique)) unique += "…";
+    used.add(unique);
+    return unique;
+  });
+}
+
+function uniqueAction(label: string, choices: string[]): string {
+  let unique = label;
+  while (choices.includes(unique)) unique += "…";
+  return unique;
+}
+
+function extractMultiSelectOptions(schema: Extract<FormProperty, { type: "array" }>): Array<{ value: string; display: string }> {
+  const items = schema.items as { enum?: string[]; anyOf?: Array<{ const: string; title: string }> };
+  return items.anyOf
+    ? items.anyOf.map(option => ({ value: option.const, display: formatChoice(option.const, option.title) }))
+    : (items.enum ?? []).map(value => ({ value, display: value }));
+}
+
+function formatReview(
+  serverName: string,
+  properties: Array<[string, FormProperty]>,
+  content: Record<string, string | number | boolean | string[]>,
+): string {
+  const rows = properties.map(([name, schema]) =>
+    `${schema.title ?? humanizeName(name)}: ${content[name] === undefined ? "(omitted)" : String(content[name])}`);
+  return [`Review input for ${serverName}`, "", ...rows].join("\n");
+}
+
+export async function handleUrlElicitation(
+  options: ElicitationHandlerOptions,
+  params: ElicitRequestURLParams,
+): Promise<ElicitResult> {
+  if (!options.allowUrl) throw new McpError(ErrorCode.InvalidParams, "URL elicitation is not supported");
+
+  let parsed: URL;
+  try {
+    parsed = new URL(params.url);
+  } catch {
+    throw new McpError(ErrorCode.InvalidParams, "URL elicitation supplied an invalid URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new McpError(ErrorCode.InvalidParams, "URL elicitation only supports HTTP and HTTPS URLs");
+  }
+
+  const decision = await options.ui.select([
+    "MCP Browser Request",
+    `Server: ${options.serverName}`,
+    "",
+    params.message,
+    "",
+    `Host: ${parsed.host}`,
+    `Full URL: ${params.url}`,
+    "",
+    "Open this URL in your browser?",
+  ].join("\n"), ["Open", "Decline"]);
+  if (decision === undefined) return { action: "cancel" };
+  if (decision === "Decline") return { action: "decline" };
+
+  try {
+    await open(params.url);
+  } catch (error) {
+    options.ui.notify(`Could not open MCP elicitation URL: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return { action: "cancel" };
+  }
+  options.onUrlAccepted?.(params.elicitationId);
+  options.ui.notify("Opened browser for MCP elicitation.", "info");
+  return { action: "accept" };
+}
+
+function humanizeName(name: string): string {
+  return name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, char => char.toUpperCase());
+}

package/index.ts

@@ -6,7 +6,7 @@ import { loadMcpConfig } from "./config.ts";
 import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.ts";
 import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
 import { loadMetadataCache } from "./metadata-cache.ts";
-import { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.ts";
+import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.ts";
 import { getConfigPathFromArgv, truncateAtWord } from "./utils.ts";
 import { initializeOAuth, shutdownOAuth } from "./mcp-auth-flow.ts";
 import { createMcpDirectToolCallRenderer, renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.ts";
@@ -263,7 +263,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         regex: Type.Optional(Type.Boolean({ description: "Treat search as regex (default: substring match)" })),
         includeSchemas: Type.Optional(Type.Boolean({ description: "Include parameter schemas in search results (default: true)" })),
         server: Type.Optional(Type.String({ description: "Filter to specific server (also disambiguates tool calls)" })),
-        action: Type.Optional(Type.String({ description: "Action: 'ui-messages' to retrieve prompts/intents from UI sessions" })),
+        action: Type.Optional(Type.String({ description: "Action: 'ui-messages', 'auth-start', or 'auth-complete'" })),
       }),
       renderResult: renderMcpToolResult,
       async execute(_toolCallId, params: {
@@ -314,6 +314,31 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         if (params.action === "ui-messages") {
           return executeUiMessages(state);
         }
+        if (params.action === "auth-start") {
+          if (!params.server) {
+            return {
+              content: [{ type: "text" as const, text: "auth-start requires `server`. Example: mcp({ action: \"auth-start\", server: \"linear-server\" })" }],
+              details: { mode: "auth-start", error: "missing_server" },
+            };
+          }
+          return executeAuthStart(state, params.server);
+        }
+        if (params.action === "auth-complete") {
+          if (!params.server) {
+            return {
+              content: [{ type: "text" as const, text: "auth-complete requires `server`." }],
+              details: { mode: "auth-complete", error: "missing_server" },
+            };
+          }
+          const input = parsedArgs?.redirectUrl ?? parsedArgs?.code ?? parsedArgs?.input;
+          if (typeof input !== "string" || input.trim().length === 0) {
+            return {
+              content: [{ type: "text" as const, text: "auth-complete requires args with `redirectUrl`, `code`, or `input`." }],
+              details: { mode: "auth-complete", error: "missing_input" },
+            };
+          }
+          return executeAuthComplete(state, params.server, input);
+        }
         if (params.tool) {
           return executeCall(state, params.tool, parsedArgs, params.server, getPiTools);
         }

package/init.ts

@@ -25,6 +25,10 @@ import { getMissingConfiguredDirectToolServers } from "./direct-tools.ts";
 
 const FAILURE_BACKOFF_MS = 60 * 1000;
 
+export function isTuiMode(ctx: Pick<ExtensionContext, "hasUI" | "mode">): boolean {
+  return ctx.hasUI && ctx.mode === "tui";
+}
+
 export async function initializeMcp(
   pi: ExtensionAPI,
   ctx: ExtensionContext
@@ -43,6 +47,13 @@ export async function initializeMcp(
       getSignal: () => ctx.signal,
     });
   }
+  const elicitationEnabled = config.settings?.elicitation !== false && ctx.hasUI;
+  if (elicitationEnabled) {
+    manager.setElicitationConfig({
+      ui: ctx.ui,
+      allowUrl: isTuiMode(ctx),
+    });
+  }
   const lifecycle = new McpLifecycleManager(manager);
   const toolMetadata = new Map<string, ToolMetadata[]>();
   const failureTracker = new Map<string, number>();