@wrongstack/mcp 1.0.24 → 1.0.26

package/dist/index.js

@@ -1,5 +1,7 @@
 // src/authorization.ts
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+// src/authorization-discovery.ts
 import * as dns from "node:dns/promises";
 import * as http from "node:http";
 import * as https from "node:https";
@@ -29,22 +31,6 @@ function canonicalMcpResource(rawUrl) {
   if (url.pathname === "/" && !url.search) return url.origin;
   return url.toString();
 }
-function authorizationHeaderForToken(token, expectedResource, now = Date.now()) {
-  if (canonicalMcpResource(token.resource) !== expectedResource) {
-    throw new Error("MCP access token resource does not match the target server");
-  }
-  if (token.expiresAt !== void 0 && token.expiresAt <= now) {
-    throw new Error("MCP access token is expired");
-  }
-  const tokenType = token.tokenType ?? "Bearer";
-  if (tokenType.toLowerCase() !== "bearer") {
-    throw new Error(`Unsupported MCP OAuth token type "${tokenType}"`);
-  }
-  if (!token.accessToken || token.accessToken.length > 16384 || /[\r\n]/.test(token.accessToken)) {
-    throw new Error("MCP access token is empty, oversized, or contains invalid characters");
-  }
-  return `Bearer ${token.accessToken}`;
-}
 function parseMcpBearerChallenge(header, resource) {
   const challenge = {
     status: 401,
@@ -154,36 +140,6 @@ function parseAuthorizationServerMetadata(value, expectedIssuer) {
     scopesSupported: optionalStringArray(metadata["scopes_supported"], "scopes_supported", 128)
   };
 }
-function validateMcpAuthorizationServerMetadata(value) {
-  const metadata = record(value, "stored authorization server metadata");
-  const registration = optionalString(metadata["registrationEndpoint"], "registrationEndpoint");
-  const issuer = secureOAuthUrl(requiredString(metadata["issuer"], "issuer"), "issuer").toString();
-  const authorizationEndpoint = secureOAuthUrl(
-    requiredString(metadata["authorizationEndpoint"], "authorizationEndpoint"),
-    "authorization endpoint"
-  ).toString();
-  const tokenEndpoint = secureOAuthUrl(
-    requiredString(metadata["tokenEndpoint"], "tokenEndpoint"),
-    "token endpoint"
-  ).toString();
-  const issuerParameterSupported = optionalBoolean(
-    metadata["authorizationResponseIssuerParameterSupported"],
-    "authorizationResponseIssuerParameterSupported"
-  );
-  if (issuerParameterSupported !== true && (new URL(authorizationEndpoint).origin !== new URL(issuer).origin || new URL(tokenEndpoint).origin !== new URL(issuer).origin)) {
-    throw new Error(
-      "MCP authorization server with cross-origin endpoints must support the authorization response issuer parameter"
-    );
-  }
-  return {
-    issuer,
-    authorizationEndpoint,
-    tokenEndpoint,
-    registrationEndpoint: registration ? secureOAuthUrl(registration, "registration endpoint").toString() : void 0,
-    authorizationResponseIssuerParameterSupported: issuerParameterSupported,
-    scopesSupported: optionalStringArray(metadata["scopesSupported"], "scopesSupported", 128)
-  };
-}
 async function discoverMcpAuthorization(resource, options = {}) {
   const canonicalResource = canonicalMcpResource(resource);
   const resourceUrl = new URL(canonicalResource);
@@ -219,124 +175,6 @@ async function discoverMcpAuthorization(resource, options = {}) {
     authorizationServer: authorizationDiscovery.value
   };
 }
-function createMcpAuthorizationRequest(options) {
-  const resource = canonicalMcpResource(options.resource);
-  const clientId = boundedCredential(options.clientId, "client id");
-  const redirectUri = validateRedirectUri(options.redirectUri);
-  const scopes = validateScopes(options.scopes ?? []);
-  const codeVerifier = base64Url(randomBytes(32));
-  const codeChallenge = base64Url(createHash("sha256").update(codeVerifier).digest());
-  const state = base64Url(randomBytes(32));
-  const authorizationUrl = secureOAuthUrl(
-    options.authorizationServer.authorizationEndpoint,
-    "authorization endpoint"
-  );
-  authorizationUrl.searchParams.set("response_type", "code");
-  authorizationUrl.searchParams.set("client_id", clientId);
-  authorizationUrl.searchParams.set("redirect_uri", redirectUri);
-  authorizationUrl.searchParams.set("state", state);
-  authorizationUrl.searchParams.set("code_challenge", codeChallenge);
-  authorizationUrl.searchParams.set("code_challenge_method", "S256");
-  authorizationUrl.searchParams.set("resource", resource);
-  if (scopes.length > 0) authorizationUrl.searchParams.set("scope", scopes.join(" "));
-  return {
-    authorizationUrl: authorizationUrl.toString(),
-    state,
-    codeVerifier,
-    redirectUri,
-    clientId,
-    resource,
-    issuer: options.authorizationServer.issuer,
-    requireIssuerParameter: options.authorizationServer.authorizationResponseIssuerParameterSupported === true
-  };
-}
-function parseMcpAuthorizationCallback(callbackUrl, session) {
-  let callback;
-  try {
-    callback = new URL(callbackUrl);
-  } catch {
-    throw new Error("MCP OAuth callback must be an absolute URL");
-  }
-  const expected = new URL(validateRedirectUri(session.redirectUri));
-  if (callback.protocol !== expected.protocol || callback.hostname !== expected.hostname || callback.port !== expected.port || callback.pathname !== expected.pathname) {
-    throw new Error("MCP OAuth callback redirect URI does not match the authorization session");
-  }
-  const returnedStates = callback.searchParams.getAll("state");
-  if (returnedStates.length !== 1) {
-    throw new Error("MCP OAuth callback must contain exactly one state parameter");
-  }
-  const returnedState = returnedStates[0];
-  if (!constantTimeEqual(returnedState, session.state)) {
-    throw new Error("MCP OAuth callback state mismatch");
-  }
-  const returnedIssuers = callback.searchParams.getAll("iss");
-  if (session.requireIssuerParameter && returnedIssuers.length !== 1) {
-    throw new Error("MCP OAuth callback must contain exactly one issuer parameter");
-  }
-  if (returnedIssuers.length > 0 && returnedIssuers.some((issuer) => issuer !== session.issuer)) {
-    throw new Error("MCP OAuth callback issuer mismatch");
-  }
-  const oauthErrors = callback.searchParams.getAll("error");
-  const codes = callback.searchParams.getAll("code");
-  if (oauthErrors.length > 1 || codes.length > 1 || oauthErrors.length === 1 && codes.length > 0) {
-    throw new Error("MCP OAuth callback contains ambiguous response parameters");
-  }
-  if (oauthErrors.length === 1) {
-    throw new Error(`MCP OAuth authorization failed: ${boundedErrorCode(oauthErrors[0])}`);
-  }
-  if (codes.length !== 1) {
-    throw new Error("MCP OAuth callback must contain exactly one authorization code");
-  }
-  return boundedCredential(codes[0], "authorization code");
-}
-async function exchangeMcpAuthorizationCode(options) {
-  const resource = canonicalMcpResource(options.resource);
-  const body = new URLSearchParams({
-    grant_type: "authorization_code",
-    code: boundedCredential(options.code, "authorization code"),
-    client_id: boundedCredential(options.clientId, "client id"),
-    redirect_uri: validateRedirectUri(options.redirectUri),
-    code_verifier: validateCodeVerifier(options.codeVerifier),
-    resource
-  }).toString();
-  const response = await requestPinnedJson(options.authorizationServer.tokenEndpoint, {
-    method: "POST",
-    body,
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    signal: options.signal,
-    timeoutMs: options.timeoutMs,
-    maxResponseBytes: options.maxResponseBytes,
-    lookup: options.lookup,
-    allowedLoopbackHostname: loopbackHostnameForResource(resource),
-    label: "token endpoint"
-  });
-  if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
-  return parseTokenResponse(response, resource);
-}
-async function refreshMcpAccessToken(options) {
-  const resource = canonicalMcpResource(options.resource);
-  const previousRefreshToken = boundedCredential(options.refreshToken, "refresh token");
-  const body = new URLSearchParams({
-    grant_type: "refresh_token",
-    refresh_token: previousRefreshToken,
-    client_id: boundedCredential(options.clientId, "client id"),
-    resource
-  }).toString();
-  const response = await requestPinnedJson(options.authorizationServer.tokenEndpoint, {
-    method: "POST",
-    body,
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    signal: options.signal,
-    timeoutMs: options.timeoutMs,
-    maxResponseBytes: options.maxResponseBytes,
-    lookup: options.lookup,
-    allowedLoopbackHostname: loopbackHostnameForResource(resource),
-    label: "token endpoint"
-  });
-  if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
-  const parsed = parseTokenResponse(response, resource);
-  return { ...parsed, refreshToken: parsed.refreshToken ?? previousRefreshToken };
-}
 function challengeParameter(parameters, name) {
   const pattern = new RegExp(
     `(?:^|,)\\s*${name}\\s*=\\s*(?:"((?:\\\\.|[^"\\\\])*)"|([^,\\s]+))`,
@@ -356,9 +194,9 @@ function validateMetadataUrl(value) {
     return void 0;
   }
 }
-function record(value, label) {
+function record(value, label2) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`MCP ${label} must be an object`);
+    throw new Error(`MCP ${label2} must be an object`);
   }
   return value;
 }
@@ -387,23 +225,23 @@ function boundedStringArray(value, field, maxItems) {
 function optionalStringArray(value, field, maxItems) {
   return value === void 0 ? [] : boundedStringArray(value, field, maxItems);
 }
-function secureOAuthUrl(value, label) {
+function secureOAuthUrl(value, label2) {
   let url;
   try {
     url = new URL(value);
   } catch {
-    throw new Error(`MCP ${label} must be an absolute URL`);
+    throw new Error(`MCP ${label2} must be an absolute URL`);
   }
   if (url.protocol !== "https:" && !isLoopbackHttp(url)) {
-    throw new Error(`MCP ${label} must use HTTPS (except loopback development)`);
+    throw new Error(`MCP ${label2} must use HTTPS (except loopback development)`);
   }
   if (url.username || url.password || url.search || url.hash) {
-    throw new Error(`MCP ${label} must not contain credentials, query, or fragment components`);
+    throw new Error(`MCP ${label2} must not contain credentials, query, or fragment components`);
   }
   if (url.pathname === "/") return new URL(url.origin);
   return url;
 }
-async function discoverFirst(candidates, fetchJson, signal, parse, label) {
+async function discoverFirst(candidates, fetchJson, signal, parse, label2) {
   const failures = [];
   for (const candidate of candidates) {
     signal?.throwIfAborted();
@@ -419,11 +257,11 @@ async function discoverFirst(candidates, fetchJson, signal, parse, label) {
       failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  throw new Error(`MCP ${label} discovery failed (${failures.join("; ")})`);
+  throw new Error(`MCP ${label2} discovery failed (${failures.join("; ")})`);
 }
 async function requestPinnedJson(rawUrl, options) {
-  const label = options.label ?? "discovery";
-  const url = secureOAuthUrl(rawUrl, `${label} URL`);
+  const label2 = options.label ?? "discovery";
+  const url = secureOAuthUrl(rawUrl, `${label2} URL`);
   const target = await resolvePinnedAddress(url, options);
   const timeoutMs = options.timeoutMs ?? 1e4;
   const maxBytes = options.maxResponseBytes ?? 64 * 1024;
@@ -467,12 +305,12 @@ async function requestPinnedJson(rawUrl, options) {
       }
       if (status >= 300 && status < 400) {
         response.resume();
-        finish(new Error(`MCP OAuth ${label} redirects are not allowed`));
+        finish(new Error(`MCP OAuth ${label2} redirects are not allowed`));
         return;
       }
       if (status < 200 || status >= 300) {
         response.resume();
-        finish(new MCPOAuthHttpError(`MCP OAuth ${label} HTTP ${status}`, status));
+        finish(new MCPOAuthHttpError(`MCP OAuth ${label2} HTTP ${status}`, status));
         return;
       }
       const contentType = response.headers["content-type"] ?? "";
@@ -516,21 +354,21 @@ async function requestPinnedJson(rawUrl, options) {
   });
 }
 async function resolvePinnedAddress(url, options) {
-  const hostname = unbracket(url.hostname).toLowerCase();
-  const literalFamily = net.isIP(hostname);
+  const hostname2 = unbracket(url.hostname).toLowerCase();
+  const literalFamily = net.isIP(hostname2);
   if (literalFamily === 4 || literalFamily === 6) {
     assertDiscoveryAddressAllowed(
-      hostname,
+      hostname2,
       literalFamily,
-      hostname,
+      hostname2,
       options.allowedLoopbackHostname
     );
-    return { address: hostname, family: literalFamily };
+    return { address: hostname2, family: literalFamily };
   }
   const lookup3 = options.lookup ?? ((host) => dns.lookup(host, { all: true }));
-  const records = await lookup3(hostname);
+  const records = await lookup3(hostname2);
   if (records.length === 0)
-    throw new Error(`MCP OAuth discovery DNS returned no addresses for ${hostname}`);
+    throw new Error(`MCP OAuth discovery DNS returned no addresses for ${hostname2}`);
   for (const record3 of records) {
     if (record3.family !== 4 && record3.family !== 6) {
       throw new Error("MCP OAuth discovery DNS returned an unsupported address family");
@@ -538,22 +376,194 @@ async function resolvePinnedAddress(url, options) {
     assertDiscoveryAddressAllowed(
       record3.address,
       record3.family,
-      hostname,
+      hostname2,
       options.allowedLoopbackHostname
     );
   }
   const selected = records[0];
   return { address: selected.address, family: selected.family };
 }
-function assertDiscoveryAddressAllowed(address, family, hostname, allowedLoopbackHostname) {
+function assertDiscoveryAddressAllowed(address, family, hostname2, allowedLoopbackHostname) {
   const isPrivate = family === 4 ? isPrivateIPv4(address) : isPrivateIPv6(address);
   if (!isPrivate) return;
   const loopback = family === 4 ? address.startsWith("127.") : address === "::1";
-  if (loopback && hostname === allowedLoopbackHostname) return;
+  if (loopback && hostname2 === allowedLoopbackHostname) return;
   throw new Error(`MCP OAuth discovery blocked private address ${address}`);
 }
-function unbracket(hostname) {
-  return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+function unbracket(hostname2) {
+  return hostname2.startsWith("[") && hostname2.endsWith("]") ? hostname2.slice(1, -1) : hostname2;
+}
+function isLoopbackHttp(url) {
+  if (url.protocol !== "http:") return false;
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+}
+
+// src/authorization.ts
+function authorizationHeaderForToken(token, expectedResource, now = Date.now()) {
+  if (canonicalMcpResource(token.resource) !== expectedResource) {
+    throw new Error("MCP access token resource does not match the target server");
+  }
+  if (token.expiresAt !== void 0 && token.expiresAt <= now) {
+    throw new Error("MCP access token is expired");
+  }
+  const tokenType = token.tokenType ?? "Bearer";
+  if (tokenType.toLowerCase() !== "bearer") {
+    throw new Error(`Unsupported MCP OAuth token type "${tokenType}"`);
+  }
+  if (!token.accessToken || token.accessToken.length > 16384 || /[\r\n]/.test(token.accessToken)) {
+    throw new Error("MCP access token is empty, oversized, or contains invalid characters");
+  }
+  return `Bearer ${token.accessToken}`;
+}
+function validateMcpAuthorizationServerMetadata(value) {
+  const metadata = record(value, "stored authorization server metadata");
+  const registration = optionalString(metadata["registrationEndpoint"], "registrationEndpoint");
+  const issuer = secureOAuthUrl(requiredString(metadata["issuer"], "issuer"), "issuer").toString();
+  const authorizationEndpoint = secureOAuthUrl(
+    requiredString(metadata["authorizationEndpoint"], "authorizationEndpoint"),
+    "authorization endpoint"
+  ).toString();
+  const tokenEndpoint = secureOAuthUrl(
+    requiredString(metadata["tokenEndpoint"], "tokenEndpoint"),
+    "token endpoint"
+  ).toString();
+  const issuerParameterSupported = optionalBoolean(
+    metadata["authorizationResponseIssuerParameterSupported"],
+    "authorizationResponseIssuerParameterSupported"
+  );
+  if (issuerParameterSupported !== true && (new URL(authorizationEndpoint).origin !== new URL(issuer).origin || new URL(tokenEndpoint).origin !== new URL(issuer).origin)) {
+    throw new Error(
+      "MCP authorization server with cross-origin endpoints must support the authorization response issuer parameter"
+    );
+  }
+  return {
+    issuer,
+    authorizationEndpoint,
+    tokenEndpoint,
+    registrationEndpoint: registration ? secureOAuthUrl(registration, "registration endpoint").toString() : void 0,
+    authorizationResponseIssuerParameterSupported: issuerParameterSupported,
+    scopesSupported: optionalStringArray(metadata["scopesSupported"], "scopesSupported", 128)
+  };
+}
+function createMcpAuthorizationRequest(options) {
+  const resource = canonicalMcpResource(options.resource);
+  const clientId = boundedCredential(options.clientId, "client id");
+  const redirectUri = validateRedirectUri(options.redirectUri);
+  const scopes = validateScopes(options.scopes ?? []);
+  const codeVerifier = base64Url(randomBytes(32));
+  const codeChallenge = base64Url(createHash("sha256").update(codeVerifier).digest());
+  const state = base64Url(randomBytes(32));
+  const authorizationUrl = secureOAuthUrl(
+    options.authorizationServer.authorizationEndpoint,
+    "authorization endpoint"
+  );
+  authorizationUrl.searchParams.set("response_type", "code");
+  authorizationUrl.searchParams.set("client_id", clientId);
+  authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizationUrl.searchParams.set("state", state);
+  authorizationUrl.searchParams.set("code_challenge", codeChallenge);
+  authorizationUrl.searchParams.set("code_challenge_method", "S256");
+  authorizationUrl.searchParams.set("resource", resource);
+  if (scopes.length > 0) authorizationUrl.searchParams.set("scope", scopes.join(" "));
+  return {
+    authorizationUrl: authorizationUrl.toString(),
+    state,
+    codeVerifier,
+    redirectUri,
+    clientId,
+    resource,
+    issuer: options.authorizationServer.issuer,
+    requireIssuerParameter: options.authorizationServer.authorizationResponseIssuerParameterSupported === true
+  };
+}
+function parseMcpAuthorizationCallback(callbackUrl, session) {
+  let callback;
+  try {
+    callback = new URL(callbackUrl);
+  } catch {
+    throw new Error("MCP OAuth callback must be an absolute URL");
+  }
+  const expected = new URL(validateRedirectUri(session.redirectUri));
+  if (callback.protocol !== expected.protocol || callback.hostname !== expected.hostname || callback.port !== expected.port || callback.pathname !== expected.pathname) {
+    throw new Error("MCP OAuth callback redirect URI does not match the authorization session");
+  }
+  const returnedStates = callback.searchParams.getAll("state");
+  if (returnedStates.length !== 1) {
+    throw new Error("MCP OAuth callback must contain exactly one state parameter");
+  }
+  const returnedState = returnedStates[0];
+  if (!constantTimeEqual(returnedState, session.state)) {
+    throw new Error("MCP OAuth callback state mismatch");
+  }
+  const returnedIssuers = callback.searchParams.getAll("iss");
+  if (session.requireIssuerParameter && returnedIssuers.length !== 1) {
+    throw new Error("MCP OAuth callback must contain exactly one issuer parameter");
+  }
+  if (returnedIssuers.length > 0 && returnedIssuers.some((issuer) => issuer !== session.issuer)) {
+    throw new Error("MCP OAuth callback issuer mismatch");
+  }
+  const oauthErrors = callback.searchParams.getAll("error");
+  const codes = callback.searchParams.getAll("code");
+  if (oauthErrors.length > 1 || codes.length > 1 || oauthErrors.length === 1 && codes.length > 0) {
+    throw new Error("MCP OAuth callback contains ambiguous response parameters");
+  }
+  if (oauthErrors.length === 1) {
+    throw new Error(`MCP OAuth authorization failed: ${boundedErrorCode(oauthErrors[0])}`);
+  }
+  if (codes.length !== 1) {
+    throw new Error("MCP OAuth callback must contain exactly one authorization code");
+  }
+  return boundedCredential(codes[0], "authorization code");
+}
+async function exchangeMcpAuthorizationCode(options) {
+  const resource = canonicalMcpResource(options.resource);
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: boundedCredential(options.code, "authorization code"),
+    client_id: boundedCredential(options.clientId, "client id"),
+    redirect_uri: validateRedirectUri(options.redirectUri),
+    code_verifier: validateCodeVerifier(options.codeVerifier),
+    resource,
+    ...options.clientSecret ? { client_secret: boundedCredential(options.clientSecret, "client secret") } : {}
+  }).toString();
+  const response = await requestPinnedJson(options.authorizationServer.tokenEndpoint, {
+    method: "POST",
+    body,
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxResponseBytes: options.maxResponseBytes,
+    lookup: options.lookup,
+    allowedLoopbackHostname: loopbackHostnameForResource(resource),
+    label: "token endpoint"
+  });
+  if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
+  return parseTokenResponse(response, resource);
+}
+async function refreshMcpAccessToken(options) {
+  const resource = canonicalMcpResource(options.resource);
+  const previousRefreshToken = boundedCredential(options.refreshToken, "refresh token");
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: previousRefreshToken,
+    client_id: boundedCredential(options.clientId, "client id"),
+    resource,
+    ...options.clientSecret ? { client_secret: boundedCredential(options.clientSecret, "client secret") } : {}
+  }).toString();
+  const response = await requestPinnedJson(options.authorizationServer.tokenEndpoint, {
+    method: "POST",
+    body,
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxResponseBytes: options.maxResponseBytes,
+    lookup: options.lookup,
+    allowedLoopbackHostname: loopbackHostnameForResource(resource),
+    label: "token endpoint"
+  });
+  if (response === void 0) throw new Error("MCP OAuth token endpoint returned no response");
+  const parsed = parseTokenResponse(response, resource);
+  return { ...parsed, refreshToken: parsed.refreshToken ?? previousRefreshToken };
 }
 function validateRedirectUri(value) {
   let url;
@@ -586,9 +596,9 @@ function validateCodeVerifier(value) {
   }
   return value;
 }
-function boundedCredential(value, label) {
+function boundedCredential(value, label2) {
   if (!value || value.length > 16384 || /[\r\n]/.test(value)) {
-    throw new Error(`MCP OAuth ${label} is empty, oversized, or invalid`);
+    throw new Error(`MCP OAuth ${label2} is empty, oversized, or invalid`);
   }
   return value;
 }
@@ -638,14 +648,213 @@ function loopbackHostnameForResource(resource) {
   const url = new URL(resource);
   return isLoopbackHttp(url) ? unbracket(url.hostname).toLowerCase() : void 0;
 }
-function isLoopbackHttp(url) {
-  if (url.protocol !== "http:") return false;
-  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+
+// src/authorization-callback-server.ts
+import * as http2 from "node:http";
+var DEFAULT_PATH = "/callback";
+var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+var MAX_REQUESTS = 16;
+async function startMcpOAuthCallbackServer(options = {}) {
+  const path2 = normalizePath(options.path ?? DEFAULT_PATH);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("MCP OAuth callback timeout must be a positive finite number");
+  }
+  options.signal?.throwIfAborted();
+  let settle;
+  let fail;
+  let finished = false;
+  let requests = 0;
+  const callback = new Promise((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+  callback.catch(() => void 0);
+  const server = http2.createServer((req, res) => {
+    if (finished || ++requests > MAX_REQUESTS) {
+      res.writeHead(429).end();
+      return;
+    }
+    const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (req.method !== "GET" || requestUrl.pathname !== path2) {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found");
+      return;
+    }
+    finished = true;
+    res.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      // The URL carries a one-shot authorization code; keep it out of caches
+      // and out of the next site the user visits.
+      "cache-control": "no-store",
+      "referrer-policy": "no-referrer"
+    }).end(SUCCESS_PAGE);
+    const address2 = server.address();
+    const port = address2?.port ?? 0;
+    settle?.(`http://127.0.0.1:${port}${req.url ?? path2}`);
+  });
+  server.on("error", (error) => {
+    finished = true;
+    fail?.(error);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 0, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address) {
+    server.close();
+    throw new Error("MCP OAuth callback listener failed to bind a loopback port");
+  }
+  const redirectUri = `http://127.0.0.1:${address.port}${path2}`;
+  const timer = setTimeout(() => {
+    finished = true;
+    fail?.(new Error(`MCP OAuth callback was not received within ${timeoutMs}ms`));
+    close();
+  }, timeoutMs);
+  timer.unref?.();
+  const onAbort = () => {
+    finished = true;
+    fail?.(
+      options.signal?.reason instanceof Error ? options.signal.reason : new Error("MCP OAuth callback wait was aborted")
+    );
+    close();
+  };
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  function close() {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    server.closeAllConnections?.();
+    server.close(() => void 0);
+  }
+  return {
+    redirectUri,
+    waitForCallback: () => callback.finally(close),
+    close
+  };
+}
+function normalizePath(value) {
+  if (!value.startsWith("/") || value.length > 256 || /[?#\s]/.test(value)) {
+    throw new Error("MCP OAuth callback path must be a bounded absolute path without query");
+  }
+  return value;
+}
+var SUCCESS_PAGE = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Authorized</title></head>
+<body style="font-family:system-ui,sans-serif;padding:3rem;text-align:center">
+<h1>Authorization complete</h1>
+<p>You can close this tab and return to WrongStack.</p>
+</body></html>
+`;
+
+// src/authorization-registration.ts
+var DEFAULT_CLIENT_NAME = "WrongStack";
+var MAX_REDIRECT_URIS = 8;
+async function registerMcpOAuthClient(options) {
+  const endpoint = options.authorizationServer.registrationEndpoint;
+  if (!endpoint) {
+    throw new Error(
+      "MCP authorization server does not support dynamic client registration; pass an explicit client id"
+    );
+  }
+  const redirectUris = validateRedirectUris(options.redirectUris);
+  const scopes = options.scopes?.filter(Boolean) ?? [];
+  const body = JSON.stringify({
+    client_name: boundedClientName(options.clientName ?? DEFAULT_CLIENT_NAME),
+    redirect_uris: redirectUris,
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    // A CLI is a public client: it cannot hold a secret that the user could not
+    // also read. Asking for `none` keeps the PKCE-only exchange we implement.
+    token_endpoint_auth_method: "none",
+    application_type: "native",
+    ...options.clientUri ? { client_uri: options.clientUri } : {},
+    ...scopes.length > 0 ? { scope: scopes.join(" ") } : {}
+  });
+  const request3 = options.requestJson ?? requestPinnedJson;
+  const response = await request3(endpoint, {
+    method: "POST",
+    body,
+    headers: { "content-type": "application/json" },
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxResponseBytes: options.maxResponseBytes,
+    lookup: options.lookup,
+    allowedLoopbackHostname: loopbackHostnameForResource2(options.resource),
+    label: "client registration endpoint"
+  });
+  if (response === void 0) {
+    throw new Error("MCP OAuth client registration endpoint returned no response");
+  }
+  return parseRegistrationResponse(response, options.authorizationServer.issuer);
+}
+function parseRegistrationResponse(value, issuer) {
+  const metadata = record(value, "client registration response");
+  const clientId = requiredString(metadata["client_id"], "client_id");
+  if (/[\r\n]/.test(clientId)) {
+    throw new Error("MCP OAuth client registration returned an invalid client_id");
+  }
+  const clientSecret = optionalString(metadata["client_secret"], "client_secret");
+  if (clientSecret !== void 0 && /[\r\n]/.test(clientSecret)) {
+    throw new Error("MCP OAuth client registration returned an invalid client_secret");
+  }
+  const expiresAt = metadata["client_secret_expires_at"];
+  if (clientSecret !== void 0 && typeof expiresAt === "number" && expiresAt !== 0) {
+    if (!Number.isFinite(expiresAt) || expiresAt * 1e3 <= Date.now()) {
+      throw new Error("MCP OAuth client registration returned an already-expired client secret");
+    }
+  }
+  return {
+    clientId,
+    ...clientSecret !== void 0 ? { clientSecret } : {},
+    issuer,
+    registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function validateRedirectUris(values) {
+  if (values.length === 0 || values.length > MAX_REDIRECT_URIS) {
+    throw new Error(
+      `MCP OAuth client registration requires between 1 and ${MAX_REDIRECT_URIS} redirect URIs`
+    );
+  }
+  return values.map((value) => {
+    let url;
+    try {
+      url = new URL(value);
+    } catch {
+      throw new Error("MCP OAuth redirect URI must be an absolute URL");
+    }
+    if (url.protocol !== "https:" && !isLoopbackHttp(url)) {
+      throw new Error("MCP OAuth redirect URI must use HTTPS or loopback HTTP");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+      throw new Error("MCP OAuth redirect URI must not contain credentials, query, or fragment");
+    }
+    return url.toString();
+  });
+}
+function boundedClientName(value) {
+  if (!value || value.length > 128 || /[\r\n]/.test(value)) {
+    throw new Error("MCP OAuth client name must be a bounded single-line string");
+  }
+  return value;
+}
+function loopbackHostnameForResource2(resource) {
+  if (!resource) return void 0;
+  try {
+    const url = new URL(resource);
+    return isLoopbackHttp(url) ? unbracket(url.hostname).toLowerCase() : void 0;
+  } catch {
+    return void 0;
+  }
 }
 
 // src/authorization-manager.ts
 var DEFAULT_PENDING_TTL_MS = 10 * 6e4;
 var MAX_PENDING_AUTHORIZATIONS = 32;
+var MAX_CACHED_REGISTRATIONS = 32;
 var MCPAuthorizationManager = class {
   constructor(options) {
     this.options = options;
@@ -655,14 +864,18 @@ var MCPAuthorizationManager = class {
     }
     this.discover = options.discover ?? discoverMcpAuthorization;
     this.exchange = options.exchange ?? exchangeMcpAuthorizationCode;
+    this.register = options.register ?? registerMcpOAuthClient;
     this.now = options.now ?? Date.now;
   }
   options;
   pending = /* @__PURE__ */ new Map();
   starting = /* @__PURE__ */ new Map();
+  /** Registrations reused across servers that share one authorization server. */
+  registrations = /* @__PURE__ */ new Map();
   pendingTtlMs;
   discover;
   exchange;
+  register;
   now;
   async begin(input) {
     const resource = canonicalMcpResource(input.resource);
@@ -689,23 +902,42 @@ var MCPAuthorizationManager = class {
         resource
       ).scopes;
       const scopes = input.scopes ? [...input.scopes] : challengeScopes;
+      const identity = await this.resolveClientIdentity({
+        serverName: input.serverName,
+        resource,
+        discovery,
+        redirectUri: input.redirectUri,
+        explicitClientId: input.clientId,
+        scopes,
+        signal: input.signal
+      });
+      if (this.starting.get(key) !== attempt) {
+        throw new Error("MCP authorization discovery was cancelled");
+      }
       const session = createMcpAuthorizationRequest({
         authorizationServer: discovery.authorizationServer,
-        clientId: input.clientId,
+        clientId: identity.clientId,
         redirectUri: input.redirectUri,
         resource,
         scopes
       });
       const normalizedScopes = new URL(session.authorizationUrl).searchParams.get("scope")?.split(" ").filter(Boolean) ?? [];
       const expiresAt = this.now() + this.pendingTtlMs;
-      this.pending.set(key, { session, discovery, scopes: normalizedScopes, expiresAt });
+      this.pending.set(key, {
+        session,
+        discovery,
+        scopes: normalizedScopes,
+        expiresAt,
+        clientSecret: identity.clientSecret
+      });
       return {
         serverName: boundedServerName(input.serverName),
         resource,
         authorizationUrl: session.authorizationUrl,
         redirectUri: session.redirectUri,
         scopes: [...normalizedScopes],
-        expiresAt
+        expiresAt,
+        clientIdSource: identity.source
       };
     } finally {
       if (this.starting.get(key) === attempt) this.starting.delete(key);
@@ -725,6 +957,7 @@ var MCPAuthorizationManager = class {
     const tokenSet = await this.exchange({
       authorizationServer: pending.discovery.authorizationServer,
       clientId: pending.session.clientId,
+      clientSecret: pending.clientSecret,
       redirectUri: pending.session.redirectUri,
       resource,
       code,
@@ -735,13 +968,95 @@ var MCPAuthorizationManager = class {
       serverName,
       resource,
       clientId: pending.session.clientId,
+      ...pending.clientSecret ? { clientSecret: pending.clientSecret } : {},
       authorizationServer: pending.discovery.authorizationServer,
       tokenSet,
       updatedAt: new Date(this.now()).toISOString()
     };
-    await this.options.store.save(stored);
-    this.emit("authorized", stored);
-    return statusFromStored(stored, this.now());
+    await this.options.store.save(stored);
+    this.emit("authorized", stored);
+    return statusFromStored(stored, this.now());
+  }
+  /**
+   * Bind a loopback receiver and start the flow, returning as soon as the URL
+   * exists so a surface can show it without blocking. Completion is awaited
+   * separately — a slash command returns its message immediately and reports
+   * the outcome through `onStateChange`. The two-step `begin`/`complete` pair
+   * stays for surfaces that cannot host a listener.
+   */
+  async beginLogin(input) {
+    const callbackOptions = {
+      port: input.port,
+      timeoutMs: input.timeoutMs,
+      signal: input.signal
+    };
+    const listener = await startMcpOAuthCallbackServer(callbackOptions);
+    let started;
+    try {
+      started = await this.begin({
+        serverName: input.serverName,
+        resource: input.resource,
+        clientId: input.clientId,
+        redirectUri: listener.redirectUri,
+        scopes: input.scopes,
+        challengeHeader: input.challengeHeader,
+        signal: input.signal
+      });
+    } catch (error) {
+      listener.close();
+      throw error;
+    }
+    const completion = listener.waitForCallback().then(
+      (callbackUrl) => this.complete({
+        serverName: input.serverName,
+        resource: input.resource,
+        callbackUrl,
+        signal: input.signal
+      })
+    ).finally(() => listener.close());
+    return { started, completion, cancel: () => listener.close() };
+  }
+  /**
+   * Identity precedence: an explicit id, then the one already stored for this
+   * server (so re-authorizing does not orphan a registration), then the
+   * per-issuer cache, then a fresh dynamic registration.
+   */
+  async resolveClientIdentity(input) {
+    if (input.explicitClientId) {
+      return { clientId: input.explicitClientId, source: "explicit" };
+    }
+    const issuer = normalizeIssuer(input.discovery.authorizationServer.issuer);
+    const stored = await this.options.store.load(boundedServerName(input.serverName), input.resource).catch(() => void 0);
+    if (stored && normalizeIssuer(stored.authorizationServer.issuer) === issuer) {
+      return {
+        clientId: stored.clientId,
+        clientSecret: stored.clientSecret,
+        source: "stored"
+      };
+    }
+    const registrationKey = `${issuer}\0${input.redirectUri}`;
+    const cached = this.registrations.get(registrationKey);
+    if (cached) {
+      return { clientId: cached.clientId, clientSecret: cached.clientSecret, source: "registered" };
+    }
+    const registration = await this.register({
+      authorizationServer: input.discovery.authorizationServer,
+      redirectUris: [input.redirectUri],
+      clientName: this.options.clientName,
+      scopes: input.scopes,
+      resource: input.resource,
+      signal: input.signal
+    });
+    if (this.registrations.size >= MAX_CACHED_REGISTRATIONS) {
+      const oldest = this.registrations.keys().next();
+      if (!oldest.done) this.registrations.delete(oldest.value);
+    }
+    this.registrations.set(registrationKey, registration);
+    return {
+      clientId: registration.clientId,
+      clientSecret: registration.clientSecret,
+      source: "registered"
+    };
   }
   async status(serverName, resource) {
     const normalizedName = boundedServerName(serverName);
@@ -816,6 +1131,9 @@ function statusFromStored(value, now) {
     canRefresh: !!value.tokenSet.refreshToken
   };
 }
+function normalizeIssuer(value) {
+  return secureOAuthUrl(value, "authorization server issuer").toString();
+}
 function authorizationKey(serverName, resource) {
   return `${boundedServerName(serverName)}\0${resource}`;
 }
@@ -833,17 +1151,17 @@ import { buildChildEnv as buildChildEnv2, buildWin32CmdShimInvocation, toErrorMe
 
 // src/client-protocol-helpers.ts
 var MAX_PROTOCOL_INPUT_CHARS = 8192;
-function validateProtocolString(value, label, allowEmpty = false) {
+function validateProtocolString(value, label2, allowEmpty = false) {
   if (typeof value !== "string" || !allowEmpty && value.length === 0) {
-    throw new Error(`MCP ${label} must be ${allowEmpty ? "a string" : "a non-empty string"}`);
+    throw new Error(`MCP ${label2} must be ${allowEmpty ? "a string" : "a non-empty string"}`);
   }
   if (value.length > MAX_PROTOCOL_INPUT_CHARS) {
-    throw new Error(`MCP ${label} exceeds ${MAX_PROTOCOL_INPUT_CHARS} characters`);
+    throw new Error(`MCP ${label2} exceeds ${MAX_PROTOCOL_INPUT_CHARS} characters`);
   }
 }
-function pageParams(cursor, label) {
+function pageParams(cursor, label2) {
   if (cursor === void 0) return {};
-  validateProtocolString(cursor, label);
+  validateProtocolString(cursor, label2);
   return { cursor };
 }
 function parseEmptyResult(value) {
@@ -853,29 +1171,29 @@ function parseEmptyResult(value) {
 }
 
 // src/protocol.ts
-function record2(value, label) {
+function record2(value, label2) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`Malformed MCP ${label}: expected object`);
+    throw new Error(`Malformed MCP ${label2}: expected object`);
   }
   return value;
 }
-function requiredString2(value, label) {
+function requiredString2(value, label2) {
   if (typeof value !== "string" || value.length === 0) {
-    throw new Error(`Malformed MCP ${label}: expected non-empty string`);
+    throw new Error(`Malformed MCP ${label2}: expected non-empty string`);
   }
   return value;
 }
-function optionalString2(value, label) {
+function optionalString2(value, label2) {
   if (value === void 0) return void 0;
-  if (typeof value !== "string") throw new Error(`Malformed MCP ${label}: expected string`);
+  if (typeof value !== "string") throw new Error(`Malformed MCP ${label2}: expected string`);
   return value;
 }
-function optionalRecord(value, label) {
+function optionalRecord(value, label2) {
   if (value === void 0) return void 0;
-  return record2(value, label);
+  return record2(value, label2);
 }
-function optionalCursor(value, label) {
-  return optionalString2(value, `${label}.nextCursor`);
+function optionalCursor(value, label2) {
+  return optionalString2(value, `${label2}.nextCursor`);
 }
 function parseServerMetadata(value) {
   const input = record2(value, "initialize result");
@@ -1052,6 +1370,13 @@ function parseGetPromptResult(value) {
     })
   };
 }
+function resourceUpdatedUri(params) {
+  if (!params || typeof params !== "object" || Array.isArray(params)) return void 0;
+  const uri = params.uri;
+  if (typeof uri !== "string" || uri.length === 0 || uri.length > 4096) return void 0;
+  if (/[\r\n]/.test(uri)) return void 0;
+  return uri;
+}
 
 // src/client-capabilities.ts
 var MCPCapabilityClient = class {
@@ -1188,116 +1513,6 @@ function forceKillTree(child) {
   }
 }
 
-// src/constants.ts
-var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2024-11-05"]);
-function negotiateProtocolVersion(requested) {
-  if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
-    return requested;
-  }
-  return MCP_CONSTANTS.PROTOCOL_VERSION;
-}
-var MCP_CONSTANTS = Object.freeze({
-  /** MCP protocol version advertised during handshake: the newest we implement. */
-  PROTOCOL_VERSION: SUPPORTED_PROTOCOL_VERSIONS[0],
-  /** Identity announced to MCP servers during `initialize`. */
-  CLIENT_INFO: Object.freeze({
-    name: "wrongstack",
-    version: "0.1.10"
-  }),
-  /** Reconnection behaviour when a transport disconnects. */
-  RECONNECT: Object.freeze({
-    /** Max full reconnect cycles before the slot is marked `failed`. */
-    MAX_CYCLES: 5,
-    /** Base delay between cycles (exponential backoff applied on top). */
-    BASE_DELAY_MS: 1e3,
-    /** Jitter factor applied to the backoff (0 = no jitter, 1 = full). */
-    JITTER_FACTOR: 0.2,
-    /** Max connection attempts within a single cycle. */
-    MAX_ATTEMPTS: 3,
-    /** Base multiplier for the exponential backoff formula (`delay = BASE * multiplier^attempt`). */
-    BACKOFF_MULTIPLIER: 2
-  }),
-  /** Timing for graceful / forced disconnect. */
-  DISCONNECT: Object.freeze({
-    /** Ms to wait for in-flight requests to complete before force-closing. */
-    GRACEFUL_MS: 800,
-    /** Ms after which the force disconnect is triggered. */
-    FORCE_TIMEOUT_MS: 1200
-  }),
-  /** Lazy-connect idle lifecycle. */
-  IDLE: Object.freeze({
-    /** Default ms a lazy server stays connected with no tool calls before auto-sleep. */
-    DEFAULT_TIMEOUT_MS: 3e5,
-    /** How often the idle sweep runs (kept well below the timeout). */
-    SWEEP_INTERVAL_MS: 3e4
-  }),
-  /** JSON-RPC response timeout for outstanding requests. */
-  RESPONSE_TIMEOUT_MS: 500,
-  /** Max buffer size for the SSE reader. */
-  SSE_READER_MAX_BUFFER: 256 * 1024,
-  /** Max characters logged from a request body. */
-  REQUEST_LOG_CAP: 1024
-});
-
-// src/tool-schema.ts
-var MAX_TOOL_PAGES = 100;
-var MAX_TOOLS = 1e4;
-async function listAllTools(requestPage) {
-  const tools = [];
-  const seenCursors = /* @__PURE__ */ new Set();
-  let cursor;
-  for (let page = 0; page < MAX_TOOL_PAGES; page++) {
-    let response;
-    try {
-      response = await requestPage(cursor ? { cursor } : {});
-    } catch (err) {
-      if (page === 0) throw err;
-      break;
-    }
-    if (response.error) {
-      if (page === 0) return null;
-      break;
-    }
-    const result = response.result;
-    tools.push(...normalizeMCPTools(result?.tools));
-    const next = result?.nextCursor;
-    if (typeof next !== "string" || next.length === 0) break;
-    if (seenCursors.has(next) || tools.length >= MAX_TOOLS) break;
-    seenCursors.add(next);
-    cursor = next;
-  }
-  return tools.slice(0, MAX_TOOLS);
-}
-function normalizeMCPTools(value) {
-  if (!Array.isArray(value)) return [];
-  const tools = [];
-  for (const raw of value) {
-    if (!raw || typeof raw !== "object") continue;
-    const t = raw;
-    if (typeof t.name !== "string") continue;
-    const name = t.name.trim();
-    if (name.length === 0) continue;
-    const inputSchema = t.inputSchema && typeof t.inputSchema === "object" && !Array.isArray(t.inputSchema) ? t.inputSchema : { type: "object", properties: {} };
-    if (!t.inputSchema || typeof t.inputSchema !== "object" || Array.isArray(t.inputSchema)) {
-      console.warn(
-        JSON.stringify({
-          level: "warn",
-          event: "mcp.tool_schema_invalid",
-          tool: name,
-          message: "no/invalid inputSchema \u2014 defaulting to empty object",
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      );
-    }
-    tools.push({
-      name,
-      ...typeof t.description === "string" ? { description: t.description } : {},
-      inputSchema
-    });
-  }
-  return tools;
-}
-
 // src/sse-reader.ts
 import { ToolError } from "@wrongstack/core/types";
 var SSE_READER_MAX_BUFFER = 256 * 1024;
@@ -1360,78 +1575,451 @@ var SSEReader = class {
     }
     if (start > 0) this.buffer = this.buffer.slice(start);
   }
-  processLine(line) {
-    if (line === "") {
-      this.flush();
-      return;
+  processLine(line) {
+    if (line === "") {
+      this.flush();
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const colonIdx = line.indexOf(":");
+    const field = colonIdx === -1 ? line : line.slice(0, colonIdx);
+    let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") {
+      this.eventName = value;
+    } else if (field === "data") {
+      if (this.dataLines.length >= SSE_READER_MAX_DATA_LINES) {
+        throw new ToolError({
+          message: `SSE: exceeded ${SSE_READER_MAX_DATA_LINES} data lines per event \u2014 upstream is not sending blank-line delimiters`,
+          code: "TOOL_EXECUTION_FAILED",
+          toolName: "mcp_transport_sse_reader",
+          context: {
+            phase: "processLine",
+            dataLineCount: this.dataLines.length,
+            maxDataLines: SSE_READER_MAX_DATA_LINES
+          }
+        });
+      }
+      this.dataLines.push(value);
+    }
+  }
+  flush() {
+    const eventName = this.eventName;
+    this.eventName = "";
+    if (this.dataLines.length === 0) {
+      return;
+    }
+    const data = this.dataLines.join("\n").trim();
+    this.dataLines = [];
+    if (!data) return;
+    if (eventName === "endpoint") {
+      for (const cb of this.endpointListeners) {
+        try {
+          cb(data);
+        } catch {
+        }
+      }
+      return;
+    }
+    try {
+      const parsed = JSON.parse(data);
+      this.dispatch(parsed);
+    } catch {
+    }
+  }
+  dispatch(msg) {
+    for (const cb of this.listeners) {
+      try {
+        cb(msg);
+      } catch {
+      }
+    }
+  }
+  reset() {
+    this.buffer = "";
+    this.dataLines = [];
+    this.eventName = "";
+    this.listeners = [];
+    this.endpointListeners = [];
+  }
+};
+
+// src/transport-base.ts
+import * as https2 from "node:https";
+import { ConfigError as ConfigError2 } from "@wrongstack/core/types";
+
+// src/elicitation.ts
+var ELICITATION_MAX_WAIT_MS = 10 * 6e4;
+var MAX_FIELDS = 32;
+var MAX_MESSAGE_CHARS = 4e3;
+var MAX_OPTIONS = 100;
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function optionalString3(v) {
+  return typeof v === "string" && v.trim() ? v : void 0;
+}
+function optionalNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function optionalCount(v) {
+  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : void 0;
+}
+function parseOptions(schema) {
+  const values = schema["enum"];
+  if (Array.isArray(values)) {
+    if (!values.every((v) => typeof v === "string")) return void 0;
+    const names = Array.isArray(schema["enumNames"]) ? schema["enumNames"] : [];
+    return values.map((value, i) => ({
+      value,
+      label: typeof names[i] === "string" && names[i] ? names[i] : value
+    }));
+  }
+  const titled = Array.isArray(schema["oneOf"]) ? schema["oneOf"] : Array.isArray(schema["anyOf"]) ? schema["anyOf"] : void 0;
+  if (!titled) return void 0;
+  const options = [];
+  for (const entry of titled) {
+    if (!isRecord(entry) || typeof entry["const"] !== "string") return void 0;
+    options.push({
+      value: entry["const"],
+      label: optionalString3(entry["title"]) ?? entry["const"]
+    });
+  }
+  return options;
+}
+function parseField(name, schema, required) {
+  if (!isRecord(schema)) return { ok: false, error: `property "${name}" is not a schema object` };
+  const base = {
+    name,
+    title: optionalString3(schema["title"]),
+    description: optionalString3(schema["description"]),
+    required
+  };
+  const type = schema["type"];
+  if (type === "array") {
+    const items = schema["items"];
+    const options = isRecord(items) ? parseOptions(items) : void 0;
+    if (!options || options.length === 0 || options.length > MAX_OPTIONS) {
+      return { ok: false, error: `property "${name}": arrays must be a list of enum values` };
+    }
+    const defaults = Array.isArray(schema["default"]) ? schema["default"].filter((v) => typeof v === "string") : void 0;
+    return {
+      ok: true,
+      value: {
+        ...base,
+        kind: "multi-enum",
+        options,
+        minItems: optionalCount(schema["minItems"]),
+        maxItems: optionalCount(schema["maxItems"]),
+        default: defaults
+      }
+    };
+  }
+  if (type === "string") {
+    const options = parseOptions(schema);
+    if (options) {
+      if (options.length === 0 || options.length > MAX_OPTIONS) {
+        return { ok: false, error: `property "${name}": enum needs 1-${MAX_OPTIONS} values` };
+      }
+      return {
+        ok: true,
+        value: { ...base, kind: "enum", options, default: optionalString3(schema["default"]) }
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        ...base,
+        kind: "string",
+        minLength: optionalCount(schema["minLength"]),
+        maxLength: optionalCount(schema["maxLength"]),
+        format: optionalString3(schema["format"]),
+        default: typeof schema["default"] === "string" ? schema["default"] : void 0
+      }
+    };
+  }
+  if (type === "number" || type === "integer") {
+    return {
+      ok: true,
+      value: {
+        ...base,
+        kind: type,
+        minimum: optionalNumber(schema["minimum"]),
+        maximum: optionalNumber(schema["maximum"]),
+        default: optionalNumber(schema["default"])
+      }
+    };
+  }
+  if (type === "boolean") {
+    return {
+      ok: true,
+      value: {
+        ...base,
+        kind: "boolean",
+        default: typeof schema["default"] === "boolean" ? schema["default"] : void 0
+      }
+    };
+  }
+  return {
+    ok: false,
+    error: `property "${name}" has unsupported type ${JSON.stringify(type)} \u2014 only flat primitive fields can be elicited`
+  };
+}
+function parseUrlElicitation(params) {
+  if (!isRecord(params)) return { ok: false, error: "params must be an object" };
+  const message = params["message"];
+  if (typeof message !== "string" || !message.trim()) {
+    return { ok: false, error: "message is required" };
+  }
+  const elicitationId = params["elicitationId"];
+  if (typeof elicitationId !== "string" || !elicitationId) {
+    return { ok: false, error: "elicitationId is required in URL mode" };
+  }
+  const raw = params["url"];
+  let url;
+  try {
+    url = new URL(typeof raw === "string" ? raw : "");
+  } catch {
+    return { ok: false, error: "url must be a valid URL" };
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return { ok: false, error: `url must be http(s), not ${url.protocol}` };
+  }
+  return {
+    ok: true,
+    value: {
+      mode: "url",
+      message: message.slice(0, MAX_MESSAGE_CHARS),
+      url: url.href,
+      elicitationId
+    }
+  };
+}
+function parseElicitationParams(params) {
+  if (!isRecord(params)) return { ok: false, error: "params must be an object" };
+  const message = params["message"];
+  if (typeof message !== "string" || !message.trim()) {
+    return { ok: false, error: "message is required" };
+  }
+  if (params["mode"] === "url") return parseUrlElicitation(params);
+  if (params["mode"] !== void 0 && params["mode"] !== "form") {
+    return { ok: false, error: `unsupported mode ${JSON.stringify(params["mode"])}` };
+  }
+  const schema = params["requestedSchema"];
+  if (!isRecord(schema) || schema["type"] !== "object" || !isRecord(schema["properties"])) {
+    return { ok: false, error: "requestedSchema must be an object schema with properties" };
+  }
+  const required = new Set(
+    Array.isArray(schema["required"]) ? schema["required"].filter((v) => typeof v === "string") : []
+  );
+  const entries = Object.entries(schema["properties"]);
+  if (entries.length > MAX_FIELDS) {
+    return { ok: false, error: `requestedSchema has more than ${MAX_FIELDS} properties` };
+  }
+  const fields = [];
+  for (const [name, property] of entries) {
+    const parsed = parseField(name, property, required.has(name));
+    if (!parsed.ok) return parsed;
+    fields.push(parsed.value);
+  }
+  return { ok: true, value: { message: message.slice(0, MAX_MESSAGE_CHARS), fields } };
+}
+function label(field) {
+  return field.title ?? field.name;
+}
+function checkValue(field, raw) {
+  const name = label(field);
+  switch (field.kind) {
+    case "string": {
+      if (typeof raw !== "string") return { ok: false, error: `${name} must be text` };
+      if (field.minLength !== void 0 && raw.length < field.minLength) {
+        return { ok: false, error: `${name} needs at least ${field.minLength} characters` };
+      }
+      if (field.maxLength !== void 0 && raw.length > field.maxLength) {
+        return { ok: false, error: `${name} allows at most ${field.maxLength} characters` };
+      }
+      return { ok: true, value: raw };
+    }
+    case "number":
+    case "integer": {
+      const n = typeof raw === "string" && raw.trim() ? Number(raw.trim()) : raw;
+      if (typeof n !== "number" || !Number.isFinite(n)) {
+        return { ok: false, error: `${name} must be a number` };
+      }
+      if (field.kind === "integer" && !Number.isInteger(n)) {
+        return { ok: false, error: `${name} must be a whole number` };
+      }
+      if (field.minimum !== void 0 && n < field.minimum) {
+        return { ok: false, error: `${name} must be at least ${field.minimum}` };
+      }
+      if (field.maximum !== void 0 && n > field.maximum) {
+        return { ok: false, error: `${name} must be at most ${field.maximum}` };
+      }
+      return { ok: true, value: n };
+    }
+    case "boolean":
+      return typeof raw === "boolean" ? { ok: true, value: raw } : { ok: false, error: `${name} must be yes or no` };
+    case "enum":
+      return typeof raw === "string" && field.options.some((o) => o.value === raw) ? { ok: true, value: raw } : { ok: false, error: `${name} must be one of the offered choices` };
+    case "multi-enum": {
+      if (!Array.isArray(raw) || !raw.every((v) => field.options.some((o) => o.value === v))) {
+        return { ok: false, error: `${name} must be picked from the offered choices` };
+      }
+      const picked = [...new Set(raw)];
+      if (field.minItems !== void 0 && picked.length < field.minItems) {
+        return { ok: false, error: `${name} needs at least ${field.minItems} choices` };
+      }
+      if (field.maxItems !== void 0 && picked.length > field.maxItems) {
+        return { ok: false, error: `${name} allows at most ${field.maxItems} choices` };
+      }
+      return { ok: true, value: picked };
+    }
+  }
+}
+function validateElicitationContent(fields, content) {
+  const out = {};
+  for (const field of fields) {
+    const raw = content[field.name];
+    if (Array.isArray(raw) && raw.length === 0 && field.kind === "multi-enum" && field.minItems === 0) {
+      out[field.name] = [];
+      continue;
     }
-    if (line.startsWith(":")) return;
-    const colonIdx = line.indexOf(":");
-    const field = colonIdx === -1 ? line : line.slice(0, colonIdx);
-    let value = colonIdx === -1 ? "" : line.slice(colonIdx + 1);
-    if (value.startsWith(" ")) value = value.slice(1);
-    if (field === "event") {
-      this.eventName = value;
-    } else if (field === "data") {
-      if (this.dataLines.length >= SSE_READER_MAX_DATA_LINES) {
-        throw new ToolError({
-          message: `SSE: exceeded ${SSE_READER_MAX_DATA_LINES} data lines per event \u2014 upstream is not sending blank-line delimiters`,
-          code: "TOOL_EXECUTION_FAILED",
-          toolName: "mcp_transport_sse_reader",
-          context: {
-            phase: "processLine",
-            dataLineCount: this.dataLines.length,
-            maxDataLines: SSE_READER_MAX_DATA_LINES
-          }
-        });
-      }
-      this.dataLines.push(value);
+    if (raw === void 0 || raw === null || raw === "" || Array.isArray(raw) && raw.length === 0) {
+      if (field.required) return { ok: false, error: `${label(field)} is required` };
+      continue;
     }
+    const checked = checkValue(field, raw);
+    if (!checked.ok) return checked;
+    out[field.name] = checked.value;
   }
-  flush() {
-    const eventName = this.eventName;
-    this.eventName = "";
-    if (this.dataLines.length === 0) {
-      return;
+  return { ok: true, value: out };
+}
+var ServerRequestResponder = class {
+  constructor(elicitation) {
+    this.elicitation = elicitation;
+  }
+  elicitation;
+  pending = /* @__PURE__ */ new Map();
+  /** Client capabilities to declare in `initialize` — only what can be answered. */
+  capabilities() {
+    return this.elicitation ? { elicitation: { form: {}, url: {} } } : {};
+  }
+  /** True while an elicitation waits on the user; request timeouts hold meanwhile. */
+  get awaitingUser() {
+    return this.pending.size > 0;
+  }
+  async answer(request3) {
+    const { id, method } = request3;
+    const error = (code, message) => ({
+      jsonrpc: "2.0",
+      id,
+      error: { code, message }
+    });
+    if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
+    if (method === "sampling/createMessage") {
+      return error(-32601, "Client sampling is disabled by policy");
     }
-    const data = this.dataLines.join("\n").trim();
-    this.dataLines = [];
-    if (!data) return;
-    if (eventName === "endpoint") {
-      for (const cb of this.endpointListeners) {
-        try {
-          cb(data);
-        } catch {
-        }
-      }
-      return;
+    if (method !== "elicitation/create" || !this.elicitation) {
+      return error(-32601, `Method not found: ${method}`);
     }
+    const form = parseElicitationParams(request3.params);
+    if (!form.ok) return error(-32602, `Invalid elicitation request: ${form.error}`);
+    if (this.pending.size > 0) {
+      return error(-32603, "Another elicitation from this server is still waiting on the user");
+    }
+    const controller = new AbortController();
+    this.pending.set(id, controller);
+    const deadline = setTimeout(
+      () => controller.abort(new Error("elicitation timed out")),
+      ELICITATION_MAX_WAIT_MS
+    );
+    deadline.unref?.();
     try {
-      const parsed = JSON.parse(data);
-      this.dispatch(parsed);
+      const prompt = form.value;
+      const result = await this.elicitation({ ...prompt, signal: controller.signal });
+      if (controller.signal.aborted) return { jsonrpc: "2.0", id, result: { action: "cancel" } };
+      if (result.action !== "accept")
+        return { jsonrpc: "2.0", id, result: { action: result.action } };
+      if (prompt.mode === "url") return { jsonrpc: "2.0", id, result: { action: "accept" } };
+      const content = validateElicitationContent(prompt.fields, result.content);
+      if (!content.ok) return error(-32603, `Elicitation answer rejected: ${content.error}`);
+      return { jsonrpc: "2.0", id, result: { action: "accept", content: content.value } };
     } catch {
+      return { jsonrpc: "2.0", id, result: { action: "cancel" } };
+    } finally {
+      clearTimeout(deadline);
+      this.pending.delete(id);
     }
   }
-  dispatch(msg) {
-    for (const cb of this.listeners) {
-      try {
-        cb(msg);
-      } catch {
+  /**
+   * Pages a tool call's `-32042` (URL elicitation required) error names, put
+   * to the user one at a time. Returns what the user chose for each; nothing
+   * is opened without their consent, and without a handler every one is
+   * `cancel`.
+   */
+  async presentUrl(elicitations, signal) {
+    const outcomes = [];
+    for (const elicitation of elicitations) {
+      let action = "cancel";
+      if (this.elicitation && !signal.aborted) {
+        try {
+          action = (await this.elicitation({ ...elicitation, signal })).action;
+        } catch {
+          action = "cancel";
+        }
       }
+      outcomes.push({ elicitation, action });
     }
+    return outcomes;
   }
-  reset() {
-    this.buffer = "";
-    this.dataLines = [];
-    this.eventName = "";
-    this.listeners = [];
-    this.endpointListeners = [];
+  /** `notifications/cancelled` from the server: stop waiting for that answer. */
+  cancel(params) {
+    if (!isRecord(params)) return;
+    const requestId = params["requestId"];
+    if (typeof requestId !== "number" && typeof requestId !== "string") return;
+    this.pending.get(requestId)?.abort(new Error("cancelled by server"));
+  }
+  /** The connection is gone: abandon every open form. */
+  dispose() {
+    for (const controller of this.pending.values())
+      controller.abort(new Error("connection closed"));
+    this.pending.clear();
   }
 };
 
-// src/transport-base.ts
-import * as https2 from "node:https";
-import { ConfigError as ConfigError2 } from "@wrongstack/core/types";
+// src/read-body.ts
+import { ToolError as ToolError2 } from "@wrongstack/core/types";
+var MAX_MCP_HTTP_BODY_BYTES = 16 * 1024 * 1024;
+async function readBodyCapped(res, maxBytes = MAX_MCP_HTTP_BODY_BYTES) {
+  const body = res.body;
+  if (!body || typeof body.getReader !== "function") {
+    return await res.text();
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => void 0);
+        throw new ToolError2({
+          message: `MCP response body exceeded ${maxBytes} bytes \u2014 refusing to buffer`,
+          code: "TOOL_EXECUTION_FAILED",
+          toolName: "mcp_transport",
+          context: { maxBytes, received: total }
+        });
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
 
 // src/transport-security.ts
 import * as dns2 from "node:dns/promises";
@@ -1459,16 +2047,16 @@ function validateTransportUrl(rawUrl) {
       context: { field: "url", rawUrl, protocol: url.protocol }
     });
   }
-  const hostname = url.hostname;
-  const host = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  const hostname2 = url.hostname;
+  const host = hostname2.startsWith("[") && hostname2.endsWith("]") ? hostname2.slice(1, -1) : hostname2;
   const ipVersion = net2.isIP(host);
   if (ipVersion !== 0) {
     const classification = classifyTransportAddress(host, ipVersion);
     if (classification === "blocked") {
       throw new ConfigError({
-        message: `MCP transport: blocked link-local/IMDS address "${hostname}" \u2014 likely not a valid MCP server`,
+        message: `MCP transport: blocked link-local/IMDS address "${hostname2}" \u2014 likely not a valid MCP server`,
         code: "CONFIG_INVALID",
-        context: { field: "url", rawUrl, hostname }
+        context: { field: "url", rawUrl, hostname: hostname2 }
       });
     }
   }
@@ -1476,9 +2064,9 @@ function validateTransportUrl(rawUrl) {
     const isLoopback = host === "localhost" || ipVersion !== 0 && classifyTransportAddress(host, ipVersion) === "loopback";
     if (!isLoopback) {
       throw new ConfigError({
-        message: `MCP transport: http:// is only allowed for loopback addresses; use https:// for "${hostname}"`,
+        message: `MCP transport: http:// is only allowed for loopback addresses; use https:// for "${hostname2}"`,
         code: "CONFIG_INVALID",
-        context: { field: "url", rawUrl, hostname, protocol: url.protocol }
+        context: { field: "url", rawUrl, hostname: hostname2, protocol: url.protocol }
       });
     }
   }
@@ -1489,6 +2077,11 @@ if (ALLOW_MCP_PRIVATE_NETWORKS && !process.env["CI"]) {
     "[WrongStack] WARNING: WRONGSTACK_MCP_ALLOW_PRIVATE=1 is active \u2014\n  MCP HTTP transports may dial private/LAN addresses (10.x, 192.168.x,\n  172.16-31.x, ULA) when a server config sets allowPrivateNetworks. Link-local/IMDS targets stay blocked."
   );
 }
+function isImdsIpv6Literal(v6) {
+  const groups = expandIPv6(v6);
+  if (groups === null) return false;
+  return groups[0] === 64768 && groups[1] === 3778 && groups[2] === 0 && groups[3] === 0 && groups[4] === 0 && groups[5] === 0 && groups[6] === 0 && groups[7] === 596;
+}
 function classifyTransportAddress(address, family) {
   if (family === 4) {
     const v4 = address.toLowerCase();
@@ -1499,7 +2092,7 @@ function classifyTransportAddress(address, family) {
   if (family === 6) {
     const v6 = address.toLowerCase();
     if (v6 === "::1") return "loopback";
-    if (/^fe[89ab]/.test(v6) || v6 === "fd00:ec2::254") return "blocked";
+    if (/^fe[89ab]/.test(v6) || isImdsIpv6Literal(v6)) return "blocked";
     if (v6.startsWith("::ffff:")) {
       const tail = v6.slice("::ffff:".length);
       if (tail.includes(".")) return classifyTransportAddress(tail, 4);
@@ -1525,30 +2118,30 @@ function classifyTransportAddress(address, family) {
   }
   return "blocked";
 }
-function assertTransportAddressAllowed(address, family, hostname, allowPrivateNetworks) {
+function assertTransportAddressAllowed(address, family, hostname2, allowPrivateNetworks) {
   const classification = classifyTransportAddress(address, family);
   if (classification === "blocked") {
     throw new ConfigError({
-      message: `MCP transport: resolved address "${address}" for "${hostname}" is link-local/IMDS \u2014 never a valid MCP target`,
+      message: `MCP transport: resolved address "${address}" for "${hostname2}" is link-local/IMDS \u2014 never a valid MCP target`,
       code: "CONFIG_INVALID",
-      context: { hostname, address }
+      context: { hostname: hostname2, address }
     });
   }
   if (classification === "private" && !allowPrivateNetworks) {
     throw new ConfigError({
-      message: `MCP transport: "${hostname}" resolved to private address ${address}. Private/LAN targets are blocked by default; if this server really runs on your private network, set allowPrivateNetworks: true on its config (or WRONGSTACK_MCP_ALLOW_PRIVATE=1 globally).`,
+      message: `MCP transport: "${hostname2}" resolved to private address ${address}. Private/LAN targets are blocked by default; if this server really runs on your private network, set allowPrivateNetworks: true on its config (or WRONGSTACK_MCP_ALLOW_PRIVATE=1 globally).`,
       code: "CONFIG_INVALID",
-      context: { hostname, address }
+      context: { hostname: hostname2, address }
     });
   }
 }
 function transportPinnedLookup(options) {
   const lookup3 = options.lookup ?? (async (host) => dns2.lookup(host, { all: true }));
-  return (hostname, connectOptions, callback) => {
-    lookup3(hostname).then((records) => {
+  return (hostname2, connectOptions, callback) => {
+    lookup3(hostname2).then((records) => {
       if (records.length === 0) {
         callback(
-          Object.assign(new Error(`MCP transport: no addresses for "${hostname}"`), {
+          Object.assign(new Error(`MCP transport: no addresses for "${hostname2}"`), {
             code: "ENOTFOUND"
           })
         );
@@ -1558,7 +2151,7 @@ function transportPinnedLookup(options) {
         assertTransportAddressAllowed(
           record3.address,
           record3.family,
-          hostname,
+          hostname2,
           options.allowPrivateNetworks
         );
       }
@@ -1606,7 +2199,7 @@ function makeAbortError(method) {
 function nextJsonRpcId(id) {
   return id >= Number.MAX_SAFE_INTEGER ? 1 : id + 1;
 }
-function createTimeoutSignal(parent, timeoutMs) {
+function createTimeoutSignal(parent, timeoutMs, hold) {
   const ctrl = new AbortController();
   const onAbort = () => ctrl.abort(parent?.reason);
   if (parent?.aborted) {
@@ -1614,10 +2207,15 @@ function createTimeoutSignal(parent, timeoutMs) {
   } else {
     parent?.addEventListener("abort", onAbort, { once: true });
   }
-  const timer = setTimeout(
-    () => ctrl.abort(new Error(`MCP HTTP request timed out after ${timeoutMs}ms`)),
-    timeoutMs
-  );
+  const onTimeout = () => {
+    if (hold?.()) {
+      timer = setTimeout(onTimeout, timeoutMs);
+      timer.unref?.();
+      return;
+    }
+    ctrl.abort(new Error(`MCP HTTP request timed out after ${timeoutMs}ms`));
+  };
+  let timer = setTimeout(onTimeout, timeoutMs);
   timer.unref?.();
   return {
     signal: ctrl.signal,
@@ -1648,9 +2246,12 @@ var BaseHTTPTransport = class {
   disconnectHandlers = [];
   toolsChangedListeners = /* @__PURE__ */ new Set();
   resourcesChangedListeners = /* @__PURE__ */ new Set();
+  resourceUpdatedListeners = /* @__PURE__ */ new Set();
   promptsChangedListeners = /* @__PURE__ */ new Set();
   protocolVersion;
+  serverRequests;
   constructor(opts, transportName) {
+    this.serverRequests = opts.serverRequests ?? new ServerRequestResponder();
     validateTransportUrl(opts.url);
     this.name = opts.name;
     this.url = opts.url;
@@ -1774,6 +2375,10 @@ var BaseHTTPTransport = class {
     this.promptsChangedListeners.add(cb);
     return () => this.promptsChangedListeners.delete(cb);
   }
+  onResourceUpdated(cb) {
+    this.resourceUpdatedListeners.add(cb);
+    return () => this.resourceUpdatedListeners.delete(cb);
+  }
   /**
    * Fire all disconnect handlers. Subclasses call this when the connection
    * drops so the registry can schedule reconnects.
@@ -1802,6 +2407,14 @@ var BaseHTTPTransport = class {
       }
     }
   }
+  notifyResourceUpdated(uri) {
+    for (const cb of this.resourceUpdatedListeners) {
+      try {
+        cb(uri);
+      } catch {
+      }
+    }
+  }
   async dispatcherFetch() {
     if (globalThis.fetch !== nativeGlobalFetch) return globalThis.fetch;
     const undici = await ensureUndici();
@@ -1853,10 +2466,40 @@ var BaseHTTPTransport = class {
       fetchOpts.dispatcher = this.tlsAgent;
     }
   }
+  /**
+   * Request timeout for a call. It holds while the server waits on the user's
+   * elicitation answer — that wait is the user typing, not the server stalling.
+   */
+  requestTimeoutSignal(parent, timeoutMs) {
+    return createTimeoutSignal(parent, timeoutMs, () => this.serverRequests.awaitingUser);
+  }
+  /**
+   * Answer a server→client request. Over HTTP the reply is POSTed back like
+   * any client message; the server acknowledges it with 202. A failed reply is
+   * not retried — the server times its request out on its side.
+   */
+  async replyToServer(request3, url, headers) {
+    const response = await this.serverRequests.answer(request3);
+    const timeoutSignal = createTimeoutSignal(this.abortController?.signal, this.requestTimeout);
+    const init = {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(response),
+      signal: timeoutSignal.signal
+    };
+    this.applyTlsAgent(init);
+    try {
+      const res = await this.fetchWithAuthorization(url, init, timeoutSignal.signal);
+      await readBodyCapped(res).catch(() => void 0);
+    } catch {
+    } finally {
+      timeoutSignal.dispose();
+    }
+  }
 };
 
 // src/transport-jsonrpc.ts
-import { ToolError as ToolError2 } from "@wrongstack/core/types";
+import { ToolError as ToolError3 } from "@wrongstack/core/types";
 function encodeJsonRpcMessage(id, method, params) {
   return JSON.stringify(
     method.startsWith("notifications/") ? { jsonrpc: "2.0", method, params } : { jsonrpc: "2.0", id, method, params }
@@ -1930,7 +2573,7 @@ function extractJsonRpcResults(text) {
 }
 function assertMatchingJsonRpcResult(data, expectedId, method) {
   if (!isJsonRpcResult(data)) {
-    throw new ToolError2({
+    throw new ToolError3({
       message: "Invalid JSON-RPC response: not a JSON-RPC 2.0 envelope",
       code: "TOOL_EXECUTION_FAILED",
       toolName: "mcp_transport_jsonrpc",
@@ -1938,7 +2581,7 @@ function assertMatchingJsonRpcResult(data, expectedId, method) {
     });
   }
   if (data.id !== expectedId) {
-    throw new ToolError2({
+    throw new ToolError3({
       message: `Invalid JSON-RPC response: id mismatch for ${method} (expected ${expectedId}, got ${data.id})`,
       code: "TOOL_EXECUTION_FAILED",
       toolName: "mcp_transport_jsonrpc",
@@ -1952,38 +2595,147 @@ function assertMatchingJsonRpcResult(data, expectedId, method) {
 import { randomBytes as randomBytes2 } from "node:crypto";
 import { ToolError as ToolError4 } from "@wrongstack/core/types";
 
-// src/read-body.ts
-import { ToolError as ToolError3 } from "@wrongstack/core/types";
-var MAX_MCP_HTTP_BODY_BYTES = 16 * 1024 * 1024;
-async function readBodyCapped(res, maxBytes = MAX_MCP_HTTP_BODY_BYTES) {
-  const body = res.body;
-  if (!body || typeof body.getReader !== "function") {
-    return await res.text();
+// src/constants.ts
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2024-11-05"]);
+function negotiateProtocolVersion(requested) {
+  if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+    return requested;
   }
-  const reader = body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (!value) continue;
-      total += value.byteLength;
-      if (total > maxBytes) {
-        await reader.cancel().catch(() => void 0);
-        throw new ToolError3({
-          message: `MCP response body exceeded ${maxBytes} bytes \u2014 refusing to buffer`,
-          code: "TOOL_EXECUTION_FAILED",
-          toolName: "mcp_transport",
-          context: { maxBytes, received: total }
-        });
-      }
-      chunks.push(value);
+  return MCP_CONSTANTS.PROTOCOL_VERSION;
+}
+var MCP_CONSTANTS = Object.freeze({
+  /** MCP protocol version advertised during handshake: the newest we implement. */
+  PROTOCOL_VERSION: SUPPORTED_PROTOCOL_VERSIONS[0],
+  /** Identity announced to MCP servers during `initialize`. */
+  CLIENT_INFO: Object.freeze({
+    name: "wrongstack",
+    version: "0.1.10"
+  }),
+  /** Reconnection behaviour when a transport disconnects. */
+  RECONNECT: Object.freeze({
+    /** Max full reconnect cycles before the slot is marked `failed`. */
+    MAX_CYCLES: 5,
+    /** Base delay between cycles (exponential backoff applied on top). */
+    BASE_DELAY_MS: 1e3,
+    /** Jitter factor applied to the backoff (0 = no jitter, 1 = full). */
+    JITTER_FACTOR: 0.2,
+    /** Max connection attempts within a single cycle. */
+    MAX_ATTEMPTS: 3,
+    /** Base multiplier for the exponential backoff formula (`delay = BASE * multiplier^attempt`). */
+    BACKOFF_MULTIPLIER: 2
+  }),
+  /** Timing for graceful / forced disconnect. */
+  DISCONNECT: Object.freeze({
+    /** Ms to wait for in-flight requests to complete before force-closing. */
+    GRACEFUL_MS: 800,
+    /** Ms after which the force disconnect is triggered. */
+    FORCE_TIMEOUT_MS: 1200
+  }),
+  /** Lazy-connect idle lifecycle. */
+  IDLE: Object.freeze({
+    /** Default ms a lazy server stays connected with no tool calls before auto-sleep. */
+    DEFAULT_TIMEOUT_MS: 3e5,
+    /** How often the idle sweep runs (kept well below the timeout). */
+    SWEEP_INTERVAL_MS: 3e4
+  }),
+  /** JSON-RPC response timeout for outstanding requests. */
+  RESPONSE_TIMEOUT_MS: 500,
+  /** Max buffer size for the SSE reader. */
+  SSE_READER_MAX_BUFFER: 256 * 1024,
+  /** Max characters logged from a request body. */
+  REQUEST_LOG_CAP: 1024
+});
+
+// src/tool-schema.ts
+var URL_ELICITATION_REQUIRED = -32042;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toToolCallResult(response) {
+  if (response.error) {
+    const pages = urlElicitationsOf(response.error);
+    return {
+      content: response.error.message,
+      isError: true,
+      ...pages.length > 0 ? { urlElicitations: pages } : {}
+    };
+  }
+  const result = isPlainObject(response.result) ? response.result : {};
+  const structured = result["structuredContent"];
+  return {
+    content: result["content"] ?? "",
+    isError: Boolean(result["isError"]),
+    ...isPlainObject(structured) ? { structuredContent: structured } : {}
+  };
+}
+function urlElicitationsOf(error) {
+  if (error.code !== URL_ELICITATION_REQUIRED || !isPlainObject(error.data)) return [];
+  const listed = error.data["elicitations"];
+  if (!Array.isArray(listed)) return [];
+  const pages = [];
+  for (const entry of listed) {
+    const parsed = parseUrlElicitation(entry);
+    if (parsed.ok) pages.push(parsed.value);
+  }
+  return pages;
+}
+var MAX_TOOL_PAGES = 100;
+var MAX_TOOLS = 1e4;
+async function listAllTools(requestPage) {
+  const tools = [];
+  const seenCursors = /* @__PURE__ */ new Set();
+  let cursor;
+  for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+    let response;
+    try {
+      response = await requestPage(cursor ? { cursor } : {});
+    } catch (err) {
+      if (page === 0) throw err;
+      break;
+    }
+    if (response.error) {
+      if (page === 0) return null;
+      break;
+    }
+    const result = response.result;
+    tools.push(...normalizeMCPTools(result?.tools));
+    const next = result?.nextCursor;
+    if (typeof next !== "string" || next.length === 0) break;
+    if (seenCursors.has(next) || tools.length >= MAX_TOOLS) break;
+    seenCursors.add(next);
+    cursor = next;
+  }
+  return tools.slice(0, MAX_TOOLS);
+}
+function normalizeMCPTools(value) {
+  if (!Array.isArray(value)) return [];
+  const tools = [];
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object") continue;
+    const t = raw;
+    if (typeof t.name !== "string") continue;
+    const name = t.name.trim();
+    if (name.length === 0) continue;
+    const inputSchema = t.inputSchema && typeof t.inputSchema === "object" && !Array.isArray(t.inputSchema) ? t.inputSchema : { type: "object", properties: {} };
+    if (!t.inputSchema || typeof t.inputSchema !== "object" || Array.isArray(t.inputSchema)) {
+      console.warn(
+        JSON.stringify({
+          level: "warn",
+          event: "mcp.tool_schema_invalid",
+          tool: name,
+          message: "no/invalid inputSchema \u2014 defaulting to empty object",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
     }
-  } finally {
-    reader.releaseLock?.();
+    tools.push({
+      name,
+      ...typeof t.description === "string" ? { description: t.description } : {},
+      inputSchema,
+      ...isPlainObject(t.outputSchema) ? { outputSchema: t.outputSchema } : {}
+    });
   }
-  return Buffer.concat(chunks).toString("utf8");
+  return tools;
 }
 
 // src/transport-sse.ts
@@ -2069,13 +2821,27 @@ var SSETransport = class extends BaseHTTPTransport {
       });
       sseReader.onMessage((msg) => {
         this.streamSignal?.();
-        if (msg.method && !msg.id) {
-          if (msg.method === "notifications/tools/list_changed") {
+        const id = msg.id;
+        if (msg.method && (typeof id === "number" || typeof id === "string")) {
+          void this.replyToServer(
+            { id, method: msg.method, params: msg.params },
+            this.endpointUrl ?? this.url,
+            this.headers
+          );
+          return;
+        }
+        if (msg.method) {
+          if (msg.method === "notifications/cancelled") {
+            this.serverRequests.cancel(msg.params);
+          } else if (msg.method === "notifications/tools/list_changed") {
             void this.handleToolsListChanged();
           } else if (msg.method === "notifications/resources/list_changed") {
             this.notifyResourcesChanged();
           } else if (msg.method === "notifications/prompts/list_changed") {
             this.notifyPromptsChanged();
+          } else if (msg.method === "notifications/resources/updated") {
+            const uri = resourceUpdatedUri(msg.params);
+            if (uri) this.notifyResourceUpdated(uri);
           }
           return;
         }
@@ -2096,9 +2862,9 @@ var SSETransport = class extends BaseHTTPTransport {
       await this.waitForStream(streamReady, signal);
       const initRes = await this.httpPost("initialize", {
         protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-        // Client capabilities (roots/sampling/elicitation) — none are offered.
+        // Client capabilities: elicitation when the host can ask its user.
         // `tools` is a SERVER capability and never belonged here.
-        capabilities: {},
+        capabilities: this.serverRequests.capabilities(),
         clientInfo: MCP_CONSTANTS.CLIENT_INFO
       });
       if (initRes.error) {
@@ -2226,7 +2992,7 @@ var SSETransport = class extends BaseHTTPTransport {
     const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
-    const timeoutSignal = createTimeoutSignal(parent, timeoutMs);
+    const timeoutSignal = this.requestTimeoutSignal(parent, timeoutMs);
     const streamed = isNotification ? void 0 : this.awaitStreamResponse(id, timeoutSignal.signal);
     const fetchOpts = {
       method: "POST",
@@ -2315,14 +3081,7 @@ var SSETransport = class extends BaseHTTPTransport {
       });
     }
     const res = await this.httpPost("tools/call", { name, arguments: input }, opts);
-    if (res.error) {
-      return { content: res.error.message, isError: true };
-    }
-    const result = res.result;
-    return {
-      content: result?.content ?? "",
-      isError: Boolean(result?.isError)
-    };
+    return toToolCallResult(res);
   }
   /** Generic JSON-RPC request — used by MCPClient.request() for SSE transports. */
   async request(method, params, timeoutMs, opts) {
@@ -2379,23 +3138,89 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
     this._nextId = nextJsonRpcId(id);
     return id;
   }
-  consumeResponseText(text, requestId) {
-    const envelopes = extractJsonRpcEnvelopes(text);
-    for (const envelope of envelopes) {
-      if ("method" in envelope && envelope.id === void 0) {
-        this.handleNotification(envelope.method);
+  /**
+   * Read a POST's reply. A `text/event-stream` reply is consumed event by
+   * event: the server may put notifications and its OWN requests (elicitation)
+   * ahead of our response and then wait for our answer to them, so buffering
+   * the whole body first would deadlock the call.
+   */
+  async readResponse(res, requestId) {
+    const streamed = (res.headers?.get("content-type") ?? "").includes("text/event-stream");
+    const body = res.body;
+    if (!streamed || !body || typeof body.getReader !== "function") {
+      return this.takeEnvelopes(await readBodyCapped(res), requestId);
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const others = [];
+    let pending = "";
+    let total = 0;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > MAX_MCP_HTTP_BODY_BYTES) {
+          throw new Error(`MCP response stream exceeded ${MAX_MCP_HTTP_BODY_BYTES} bytes`);
+        }
+        pending += decoder.decode(value, { stream: true });
+        const cut = completeEventsEnd(pending);
+        if (cut === 0) continue;
+        const match = this.takeEnvelopes(pending.slice(0, cut), requestId, others);
+        pending = pending.slice(cut);
+        if (match) {
+          await reader.cancel().catch(() => void 0);
+          return match;
+        }
+      }
+      pending += decoder.decode();
+      return this.takeEnvelopes(pending, requestId, others) ?? others[0];
+    } finally {
+      reader.releaseLock?.();
+    }
+  }
+  /**
+   * Dispatch the notifications and server requests in `text`, and return the
+   * response to `requestId` — falling back to the first other response, which
+   * the caller's id check then rejects.
+   */
+  takeEnvelopes(text, requestId, others = []) {
+    let match;
+    for (const envelope of extractJsonRpcEnvelopes(text)) {
+      if (isJsonRpcResult(envelope)) {
+        if (envelope.id === requestId) match ??= envelope;
+        else others.push(envelope);
+      } else if (envelope.id !== void 0) {
+        void this.replyToServer(
+          { id: envelope.id, method: envelope.method, params: envelope.params },
+          this.url,
+          this.sessionHeaders()
+        );
+      } else {
+        this.handleNotification(envelope.method, envelope.params);
       }
     }
-    const responses = envelopes.filter(isJsonRpcResult);
-    return responses.find((envelope) => envelope.id === requestId) ?? responses[0];
+    return match ?? others[0];
+  }
+  sessionHeaders() {
+    return {
+      Accept: "application/json, text/event-stream",
+      ...this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {},
+      ...this.headers
+    };
   }
-  handleNotification(method) {
-    if (method === "notifications/resources/list_changed") {
+  handleNotification(method, params) {
+    if (method === "notifications/cancelled") {
+      this.serverRequests.cancel(params);
+    } else if (method === "notifications/resources/list_changed") {
       this.notifyResourcesChanged();
     } else if (method === "notifications/prompts/list_changed") {
       this.notifyPromptsChanged();
     } else if (method === "notifications/tools/list_changed") {
       void this.refreshTools();
+    } else if (method === "notifications/resources/updated") {
+      const uri = resourceUpdatedUri(params);
+      if (uri) this.notifyResourceUpdated(uri);
     }
   }
   async refreshTools() {
@@ -2434,8 +3259,9 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
           method: "initialize",
           params: {
             protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-            // Client capabilities — none offered (`tools` is a server capability).
-            capabilities: {},
+            // Client capabilities: elicitation when the host can ask its user
+            // (`tools` is a server capability and never belongs here).
+            capabilities: this.serverRequests.capabilities(),
             clientInfo: MCP_CONSTANTS.CLIENT_INFO
           }
         }),
@@ -2481,7 +3307,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
     const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
-    const timeoutSignal = createTimeoutSignal(parent, this.requestTimeout);
+    const timeoutSignal = this.requestTimeoutSignal(parent, this.requestTimeout);
     const fetchOpts = {
       method: "POST",
       headers: {
@@ -2506,7 +3332,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
         await readBodyCapped(res).catch(() => void 0);
         return { jsonrpc: "2.0", id };
       }
-      const match = this.consumeResponseText(await readBodyCapped(res), id);
+      const match = await this.readResponse(res, id);
       if (match) {
         return assertMatchingJsonRpcResult(match, id, method);
       }
@@ -2531,7 +3357,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
     const body = encodeJsonRpcMessage(id, method, params);
     const external = opts?.signal;
     const parent = external && this.abortController ? AbortSignal.any([this.abortController.signal, external]) : external ?? this.abortController?.signal;
-    const timeoutSignal = createTimeoutSignal(parent, timeoutMs ?? this.requestTimeout);
+    const timeoutSignal = this.requestTimeoutSignal(parent, timeoutMs ?? this.requestTimeout);
     const fetchOpts = {
       method: "POST",
       headers: {
@@ -2556,7 +3382,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
         await readBodyCapped(res).catch(() => void 0);
         return { jsonrpc: "2.0", id };
       }
-      const parsed = this.consumeResponseText(await readBodyCapped(res), id);
+      const parsed = await this.readResponse(res, id);
       if (parsed) {
         const matched = assertMatchingJsonRpcResult(parsed, id, method);
         return {
@@ -2586,14 +3412,7 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
       throw new Error(`streamable-http transport not connected (state=${this.state})`);
     }
     const res = await this.postRaw("tools/call", { name, arguments: input }, opts);
-    if (res.error) {
-      return { content: res.error.message, isError: true };
-    }
-    const result = res.result;
-    return {
-      content: result?.content ?? "",
-      isError: Boolean(result?.isError)
-    };
+    return toToolCallResult(res);
   }
   async close() {
     this.releasePinnedDispatcher();
@@ -2619,11 +3438,125 @@ var StreamableHTTPTransport = class _StreamableHTTPTransport extends BaseHTTPTra
     }
   }
 };
+function completeEventsEnd(text) {
+  const lf = text.lastIndexOf("\n\n");
+  const crlf = text.lastIndexOf("\r\n\r\n");
+  return Math.max(lf === -1 ? 0 : lf + 2, crlf === -1 ? 0 : crlf + 4);
+}
+
+// src/client-http-connection.ts
+async function connectSSE(host) {
+  if (!host.opts.url) {
+    host.state = "failed";
+    throw new Error('MCP SSE transport requires "url"');
+  }
+  const httpOpts = {
+    name: host.opts.name,
+    url: host.opts.url,
+    headers: resolveHttpBearerHeaders(host.opts),
+    startupTimeoutMs: host.opts.startupTimeoutMs,
+    requestTimeoutMs: host.opts.requestTimeoutMs,
+    authorizationProvider: host.opts.authorizationProvider,
+    allowPrivateNetworks: host.opts.allowPrivateNetworks,
+    serverRequests: host.serverRequests
+  };
+  host.sseTransport = new SSETransport(httpOpts);
+  host.sseTransport.onDisconnect(() => {
+    host.state = "disconnected";
+    for (const cb of host.disconnectListeners) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  });
+  host.sseTransport.onToolsChanged((tools) => {
+    host._tools = tools;
+    host._toolsCache = tools;
+    for (const cb of host.toolsChangedListeners) {
+      try {
+        cb(host.opts.name, tools);
+      } catch {
+      }
+    }
+  });
+  host.sseTransport.onResourcesChanged(() => host.emitCapabilityChanged("resources"));
+  host.sseTransport.onResourceUpdated((uri) => host.emitResourceUpdated(uri));
+  host.sseTransport.onPromptsChanged(() => host.emitCapabilityChanged("prompts"));
+  try {
+    await host.sseTransport.connect();
+  } catch (err) {
+    const t = host.sseTransport;
+    host.sseTransport = void 0;
+    await t.close().catch(() => {
+    });
+    host.state = "failed";
+    throw err;
+  }
+  host._tools = host.sseTransport.listTools();
+  host._toolsCache = host._tools;
+  host._serverMetadata = host.sseTransport.getServerMetadata();
+  host.state = "connected";
+}
+async function connectStreamableHTTP(host) {
+  if (!host.opts.url) {
+    host.state = "failed";
+    throw new Error('MCP streamable-http transport requires "url"');
+  }
+  const httpOpts = {
+    name: host.opts.name,
+    url: host.opts.url,
+    headers: resolveHttpBearerHeaders(host.opts),
+    startupTimeoutMs: host.opts.startupTimeoutMs,
+    requestTimeoutMs: host.opts.requestTimeoutMs,
+    authorizationProvider: host.opts.authorizationProvider,
+    allowPrivateNetworks: host.opts.allowPrivateNetworks,
+    serverRequests: host.serverRequests
+  };
+  host.httpTransport = new StreamableHTTPTransport(httpOpts);
+  host.httpTransport.onDisconnect(() => {
+    host.state = "disconnected";
+    for (const cb of host.disconnectListeners) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  });
+  host.httpTransport.onToolsChanged((tools) => {
+    host._tools = tools;
+    host._toolsCache = tools;
+    for (const cb of host.toolsChangedListeners) {
+      try {
+        cb(host.opts.name, tools);
+      } catch {
+      }
+    }
+  });
+  host.httpTransport.onResourcesChanged(() => host.emitCapabilityChanged("resources"));
+  host.httpTransport.onResourceUpdated((uri) => host.emitResourceUpdated(uri));
+  host.httpTransport.onPromptsChanged(() => host.emitCapabilityChanged("prompts"));
+  try {
+    await host.httpTransport.connect();
+  } catch (err) {
+    const t = host.httpTransport;
+    host.httpTransport = void 0;
+    await t.close().catch(() => {
+    });
+    host.state = "failed";
+    throw err;
+  }
+  host._tools = host.httpTransport.listTools();
+  host._toolsCache = host._tools;
+  host._serverMetadata = host.httpTransport.getServerMetadata();
+  host.state = "connected";
+}
 
 // src/client.ts
 var MCPClient = class _MCPClient {
   constructor(opts) {
     this.opts = opts;
+    this.serverRequests = new ServerRequestResponder(opts.elicitation);
   }
   opts;
   capabilityClient = new MCPCapabilityClient(
@@ -2676,8 +3609,11 @@ var MCPClient = class _MCPClient {
   toolsChangedListeners = /* @__PURE__ */ new Set();
   resourcesChangedListeners = /* @__PURE__ */ new Set();
   promptsChangedListeners = /* @__PURE__ */ new Set();
+  resourceUpdatedListeners = /* @__PURE__ */ new Set();
   /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
   disconnectListeners = /* @__PURE__ */ new Set();
+  /** Answers server→client requests (ping, elicitation) on every transport. */
+  serverRequests;
   getState() {
     return this.state;
   }
@@ -2819,9 +3755,9 @@ var MCPClient = class _MCPClient {
       "initialize",
       {
         protocolVersion: MCP_CONSTANTS.PROTOCOL_VERSION,
-        // Client capabilities (roots/sampling/elicitation) — none offered.
+        // Client capabilities: elicitation when the host can ask its user.
         // `tools` is a SERVER capability and never belonged here.
-        capabilities: {},
+        capabilities: this.serverRequests.capabilities(),
         clientInfo: MCP_CONSTANTS.CLIENT_INFO
       },
       this.opts.startupTimeoutMs ?? 1e4
@@ -2848,106 +3784,10 @@ var MCPClient = class _MCPClient {
     this.state = "connected";
   }
   async connectSSE() {
-    if (!this.opts.url) {
-      this.state = "failed";
-      throw new Error('MCP SSE transport requires "url"');
-    }
-    const httpOpts = {
-      name: this.opts.name,
-      url: this.opts.url,
-      headers: resolveHttpBearerHeaders(this.opts),
-      startupTimeoutMs: this.opts.startupTimeoutMs,
-      requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider,
-      allowPrivateNetworks: this.opts.allowPrivateNetworks
-    };
-    this.sseTransport = new SSETransport(httpOpts);
-    this.sseTransport.onDisconnect(() => {
-      this.state = "disconnected";
-      for (const cb of this.disconnectListeners) {
-        try {
-          cb();
-        } catch {
-        }
-      }
-    });
-    this.sseTransport.onToolsChanged((tools) => {
-      this._tools = tools;
-      this._toolsCache = tools;
-      for (const cb of this.toolsChangedListeners) {
-        try {
-          cb(this.opts.name, tools);
-        } catch {
-        }
-      }
-    });
-    this.sseTransport.onResourcesChanged(() => this.emitCapabilityChanged("resources"));
-    this.sseTransport.onPromptsChanged(() => this.emitCapabilityChanged("prompts"));
-    try {
-      await this.sseTransport.connect();
-    } catch (err) {
-      const t = this.sseTransport;
-      this.sseTransport = void 0;
-      await t.close().catch(() => {
-      });
-      this.state = "failed";
-      throw err;
-    }
-    this._tools = this.sseTransport.listTools();
-    this._toolsCache = this._tools;
-    this._serverMetadata = this.sseTransport.getServerMetadata();
-    this.state = "connected";
+    return connectSSE(this.clientHttpConnectionHost());
   }
   async connectStreamableHTTP() {
-    if (!this.opts.url) {
-      this.state = "failed";
-      throw new Error('MCP streamable-http transport requires "url"');
-    }
-    const httpOpts = {
-      name: this.opts.name,
-      url: this.opts.url,
-      headers: resolveHttpBearerHeaders(this.opts),
-      startupTimeoutMs: this.opts.startupTimeoutMs,
-      requestTimeoutMs: this.opts.requestTimeoutMs,
-      authorizationProvider: this.opts.authorizationProvider,
-      allowPrivateNetworks: this.opts.allowPrivateNetworks
-    };
-    this.httpTransport = new StreamableHTTPTransport(httpOpts);
-    this.httpTransport.onDisconnect(() => {
-      this.state = "disconnected";
-      for (const cb of this.disconnectListeners) {
-        try {
-          cb();
-        } catch {
-        }
-      }
-    });
-    this.httpTransport.onToolsChanged((tools) => {
-      this._tools = tools;
-      this._toolsCache = tools;
-      for (const cb of this.toolsChangedListeners) {
-        try {
-          cb(this.opts.name, tools);
-        } catch {
-        }
-      }
-    });
-    this.httpTransport.onResourcesChanged(() => this.emitCapabilityChanged("resources"));
-    this.httpTransport.onPromptsChanged(() => this.emitCapabilityChanged("prompts"));
-    try {
-      await this.httpTransport.connect();
-    } catch (err) {
-      const t = this.httpTransport;
-      this.httpTransport = void 0;
-      await t.close().catch(() => {
-      });
-      this.state = "failed";
-      throw err;
-    }
-    this._tools = this.httpTransport.listTools();
-    this._toolsCache = this._tools;
-    this._serverMetadata = this.httpTransport.getServerMetadata();
-    this.state = "connected";
+    return connectStreamableHTTP(this.clientHttpConnectionHost());
   }
   async callTool(name, input, opts) {
     if (this.state !== "connected") {
@@ -2960,14 +3800,14 @@ var MCPClient = class _MCPClient {
       return this.httpTransport.callTool(name, input, opts);
     }
     const res = await this.request("tools/call", { name, arguments: input }, void 0, opts);
-    if (res.error) {
-      return { content: res.error.message, isError: true };
-    }
-    const result = res.result;
-    return {
-      content: result?.content ?? "",
-      isError: Boolean(result?.isError)
-    };
+    return toToolCallResult(res);
+  }
+  /**
+   * Put the pages of a `-32042` tool-call error to the user (consent first,
+   * nothing opened without it), on the run whose call got the error.
+   */
+  presentUrlElicitations(elicitations, signal) {
+    return this.serverRequests.presentUrl(elicitations, signal);
   }
   async listResources(opts = {}) {
     return this.capabilityClient.listResources(opts);
@@ -3041,6 +3881,7 @@ var MCPClient = class _MCPClient {
       this.child = void 0;
     }
     this.failPending(`MCP "${this.opts.name}" closed`);
+    this.serverRequests.dispose();
     await Promise.allSettled([this.sseTransport?.close(), this.httpTransport?.close()]);
     this.state = "disconnected";
   }
@@ -3074,26 +3915,31 @@ var MCPClient = class _MCPClient {
       const detach = () => {
         if (signal && onAbort) signal.removeEventListener("abort", onAbort);
       };
-      const timer = setTimeout(() => {
+      const onTimeout = () => {
+        if (this.serverRequests.awaitingUser) {
+          entry.timer = setTimeout(onTimeout, timeoutMs);
+          return;
+        }
         this.pending.delete(id);
         detach();
         reject(
           new Error(`MCP "${this.opts.name}" request "${method}" timed out after ${timeoutMs}ms`)
         );
-      }, timeoutMs);
-      this.pending.set(id, {
+      };
+      const entry = {
         resolve: (res) => {
-          clearTimeout(timer);
+          clearTimeout(entry.timer);
           detach();
           resolve(res);
         },
         reject: (err) => {
-          clearTimeout(timer);
+          clearTimeout(entry.timer);
           detach();
           reject(err);
         },
-        timer
-      });
+        timer: setTimeout(onTimeout, timeoutMs)
+      };
+      this.pending.set(id, entry);
       const stdin = this.child?.stdin;
       if (!stdin || stdin.destroyed) {
         const pending = this.pending.get(id);
@@ -3255,7 +4101,7 @@ var MCPClient = class _MCPClient {
     if (typeof envelope["method"] === "string") {
       const id = envelope["id"];
       if (typeof id === "number" || typeof id === "string") {
-        this.handleServerRequest({
+        void this.handleServerRequest({
           jsonrpc: "2.0",
           id,
           method: envelope["method"],
@@ -3264,12 +4110,17 @@ var MCPClient = class _MCPClient {
         return;
       }
       if (Object.hasOwn(envelope, "id")) return;
-      if (envelope["method"] === "notifications/tools/list_changed") {
+      if (envelope["method"] === "notifications/cancelled") {
+        this.serverRequests.cancel(envelope["params"]);
+      } else if (envelope["method"] === "notifications/tools/list_changed") {
         void this.handleToolsListChanged();
       } else if (envelope["method"] === "notifications/resources/list_changed") {
         this.emitCapabilityChanged("resources");
       } else if (envelope["method"] === "notifications/prompts/list_changed") {
         this.emitCapabilityChanged("prompts");
+      } else if (envelope["method"] === "notifications/resources/updated") {
+        const uri = resourceUpdatedUri(envelope["params"]);
+        if (uri) this.emitResourceUpdated(uri);
       }
       return;
     }
@@ -3281,15 +4132,8 @@ var MCPClient = class _MCPClient {
       entry?.resolve(response);
     }
   }
-  handleServerRequest(request3) {
-    const response = request3.method === "ping" ? { jsonrpc: "2.0", id: request3.id, result: {} } : {
-      jsonrpc: "2.0",
-      id: request3.id,
-      error: {
-        code: -32601,
-        message: request3.method === "sampling/createMessage" ? "Client sampling is disabled by policy" : `Method not found: ${request3.method}`
-      }
-    };
+  async handleServerRequest(request3) {
+    const response = await this.serverRequests.answer(request3);
     try {
       this.child?.stdin?.write(`${JSON.stringify(response)}
 `);
@@ -3329,12 +4173,26 @@ var MCPClient = class _MCPClient {
   removeResourcesChangedListener(listener) {
     this.resourcesChangedListeners.delete(listener);
   }
+  addResourceUpdatedListener(listener) {
+    this.resourceUpdatedListeners.add(listener);
+  }
+  removeResourceUpdatedListener(listener) {
+    this.resourceUpdatedListeners.delete(listener);
+  }
   addPromptsChangedListener(listener) {
     this.promptsChangedListeners.add(listener);
   }
   removePromptsChangedListener(listener) {
     this.promptsChangedListeners.delete(listener);
   }
+  emitResourceUpdated(uri) {
+    for (const listener of this.resourceUpdatedListeners) {
+      try {
+        listener(this.opts.name, uri);
+      } catch {
+      }
+    }
+  }
   emitCapabilityChanged(capability) {
     const listeners = capability === "resources" ? this.resourcesChangedListeners : this.promptsChangedListeners;
     for (const listener of listeners) {
@@ -3344,8 +4202,99 @@ var MCPClient = class _MCPClient {
       }
     }
   }
+  clientHttpConnectionHost() {
+    const self = this;
+    return {
+      get opts() {
+        return self.opts;
+      },
+      get state() {
+        return self.state;
+      },
+      set state(value) {
+        self.state = value;
+      },
+      get sseTransport() {
+        return self.sseTransport;
+      },
+      set sseTransport(value) {
+        self.sseTransport = value;
+      },
+      disconnectListeners: this.disconnectListeners,
+      get _tools() {
+        return self._tools;
+      },
+      set _tools(value) {
+        self._tools = value;
+      },
+      get _toolsCache() {
+        return self._toolsCache;
+      },
+      set _toolsCache(value) {
+        self._toolsCache = value;
+      },
+      toolsChangedListeners: this.toolsChangedListeners,
+      emitCapabilityChanged: (...args) => this.emitCapabilityChanged(...args),
+      emitResourceUpdated: (uri) => this.emitResourceUpdated(uri),
+      get _serverMetadata() {
+        return self._serverMetadata;
+      },
+      set _serverMetadata(value) {
+        self._serverMetadata = value;
+      },
+      get httpTransport() {
+        return self.httpTransport;
+      },
+      set httpTransport(value) {
+        self.httpTransport = value;
+      },
+      serverRequests: this.serverRequests
+    };
+  }
 };
 
+// src/config-env.ts
+var PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+function mcpEnvPlaceholders(cfg) {
+  const names = /* @__PURE__ */ new Set();
+  const scan = (value) => {
+    if (!value) return;
+    for (const match of value.matchAll(PLACEHOLDER)) if (match[1]) names.add(match[1]);
+  };
+  scan(cfg.command);
+  scan(cfg.url);
+  for (const arg of cfg.args ?? []) scan(arg);
+  for (const value of Object.values(cfg.env ?? {})) scan(value);
+  for (const value of Object.values(cfg.headers ?? {})) scan(value);
+  return [...names].sort();
+}
+function expandMcpEnvPlaceholders(cfg, env = process.env) {
+  const missing = /* @__PURE__ */ new Set();
+  const expand = (value) => value.replace(PLACEHOLDER, (_match, name, fallback) => {
+    const resolved = env[name];
+    if (resolved !== void 0 && resolved !== "") return resolved;
+    if (fallback !== void 0) return fallback;
+    missing.add(name);
+    return "";
+  });
+  const mapValues = (record3) => record3 ? Object.fromEntries(Object.entries(record3).map(([key, value]) => [key, expand(value)])) : void 0;
+  const expanded = {
+    command: cfg.command === void 0 ? void 0 : expand(cfg.command),
+    args: cfg.args?.map(expand),
+    env: mapValues(cfg.env),
+    url: cfg.url === void 0 ? void 0 : expand(cfg.url),
+    headers: mapValues(cfg.headers)
+  };
+  if (missing.size > 0) {
+    throw new Error(
+      `MCP server "${cfg.name}" needs environment variable${missing.size === 1 ? "" : "s"} ${[
+        ...missing
+      ].join(", ")} (referenced as \${\u2026} in its config)`
+    );
+  }
+  return expanded;
+}
+
 // src/content-selection.ts
 var DEFAULT_MCP_INSERTION_MAX_BYTES = 256 * 1024;
 var DEFAULT_MCP_RESOURCE_SCHEMES = [
@@ -3466,11 +4415,223 @@ function base64DecodedBytes(blob) {
 function utf8Bytes(value) {
   return new TextEncoder().encode(value).byteLength;
 }
-function requireIdentity(value, label) {
+function requireIdentity(value, label2) {
   if (value.length === 0 || value.length > 256) {
-    throw new Error(`MCP insertion ${label} must contain 1\u2013256 characters`);
+    throw new Error(`MCP insertion ${label2} must contain 1\u2013256 characters`);
+  }
+}
+
+// src/elicitation-form.ts
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+var MAX_ATTEMPTS = 3;
+var CONFIRM_QUESTION = "confirm";
+var URL_QUESTION = "url";
+function questionId(index) {
+  return `f${index}`;
+}
+function optionId(index) {
+  return `o${index}`;
+}
+function bounds(min, max, unit = "") {
+  if (min !== void 0 && max !== void 0) return `Between ${min} and ${max}${unit}.`;
+  if (min !== void 0) return `At least ${min}${unit}.`;
+  if (max !== void 0) return `At most ${max}${unit}.`;
+  return void 0;
+}
+function describe(field) {
+  const notes = [field.description];
+  if (field.kind === "string") {
+    notes.push(field.format ? `Format: ${field.format}.` : void 0);
+    notes.push(bounds(field.minLength, field.maxLength, " characters"));
+  } else if (field.kind === "number" || field.kind === "integer") {
+    notes.push(field.kind === "integer" ? "A whole number." : "A number.");
+    notes.push(bounds(field.minimum, field.maximum));
+  } else if (field.kind === "multi-enum") {
+    notes.push(bounds(field.minItems, field.maxItems, " choices"));
+  }
+  const text = notes.filter(Boolean).join(" ");
+  return text || void 0;
+}
+function toQuestion(field, index) {
+  const base = {
+    id: questionId(index),
+    prompt: field.title ?? field.name,
+    description: describe(field),
+    required: field.required
+  };
+  switch (field.kind) {
+    case "string":
+      return { ...base, kind: "text", recommendedText: field.default, placeholder: field.format };
+    case "number":
+    case "integer":
+      return {
+        ...base,
+        kind: "text",
+        recommendedText: field.default === void 0 ? void 0 : String(field.default)
+      };
+    case "boolean":
+      return {
+        ...base,
+        kind: "single_select",
+        options: [
+          { id: "yes", label: "Yes" },
+          { id: "no", label: "No" }
+        ],
+        recommendedOptionIds: field.default === void 0 ? void 0 : [field.default ? "yes" : "no"]
+      };
+    case "enum":
+    case "multi-enum": {
+      const defaults = field.kind === "enum" ? [field.default] : field.default ?? [];
+      const recommended = field.options.map((option, i) => defaults.includes(option.value) ? optionId(i) : void 0).filter((id) => id !== void 0);
+      return {
+        ...base,
+        kind: field.kind === "enum" ? "single_select" : "multi_select",
+        options: field.options.map((option, i) => ({ id: optionId(i), label: option.label })),
+        recommendedOptionIds: recommended.length > 0 ? recommended : void 0
+      };
+    }
   }
 }
+function pageWarnings(url) {
+  const warnings = [];
+  if (url.hostname.split(".").some((label2) => label2.startsWith("xn--"))) {
+    warnings.push(
+      "The address uses international characters (punycode); it may imitate another site."
+    );
+  }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol === "http:" && !local) {
+    warnings.push("The page is not served over HTTPS.");
+  }
+  if (url.username || url.password) warnings.push("The address carries a user name or password.");
+  return warnings;
+}
+function toPageRequest(request3, canOpen) {
+  const url = new URL(request3.url);
+  const description = [
+    request3.message,
+    `Page: ${request3.url}`,
+    `Site: ${url.host}`,
+    ...pageWarnings(url).map((warning) => `Warning: ${warning}`),
+    "What you do on that page goes to the server directly, not through WrongStack."
+  ].join("\n\n");
+  return {
+    id: `mcp-elicitation-${randomUUID()}`,
+    title: `MCP server "${request3.server}" asks you to open ${url.host}`,
+    description,
+    submitLabel: "Continue",
+    tabs: [
+      {
+        id: "page",
+        label: request3.server,
+        questions: [
+          {
+            id: URL_QUESTION,
+            prompt: `Open ${url.host}?`,
+            kind: "single_select",
+            required: true,
+            options: [
+              // Named: with `wstack remote` this process runs on another machine.
+              ...canOpen ? [{ id: "open", label: `Open it in the browser on ${hostname()}` }] : [],
+              { id: "self", label: "I will open it myself" },
+              { id: "decline", label: "Decline" }
+            ]
+          }
+        ]
+      }
+    ]
+  };
+}
+function toUserInputRequest(request3, problem) {
+  const questions = request3.fields.length > 0 ? request3.fields.map(toQuestion) : [
+    {
+      id: CONFIRM_QUESTION,
+      prompt: "Go ahead?",
+      kind: "single_select",
+      required: true,
+      options: [
+        { id: "yes", label: "Yes" },
+        { id: "no", label: "No" }
+      ]
+    }
+  ];
+  const description = [
+    request3.message,
+    `Only share what you are comfortable sending to "${request3.server}".`,
+    problem ? `The last answer was not accepted: ${problem}.` : void 0
+  ].filter(Boolean).join("\n\n");
+  return {
+    id: `mcp-elicitation-${randomUUID()}`,
+    title: `MCP server "${request3.server}" is asking for input`,
+    description,
+    submitLabel: `Send to ${request3.server}`,
+    tabs: [{ id: "form", label: request3.server, questions }]
+  };
+}
+function answerValue(field, answer) {
+  if (!answer || answer.delegated) return void 0;
+  switch (field.kind) {
+    case "string":
+      return answer.text?.trim() ? answer.text : void 0;
+    case "number":
+    case "integer":
+      return answer.text?.trim() || void 0;
+    case "boolean": {
+      const picked = answer.selectedOptionIds[0];
+      return picked === "yes" ? true : picked === "no" ? false : void 0;
+    }
+    case "enum":
+    case "multi-enum": {
+      const values = answer.selectedOptionIds.map((id) => field.options[Number(id.slice(1))]?.value).filter((v) => v !== void 0);
+      if (field.kind === "enum") return values[0];
+      return values;
+    }
+  }
+}
+async function elicitViaUserInput(request3, fallback, options = {}) {
+  const target = request3.requester ?? fallback;
+  if (!target) return { action: "cancel" };
+  if (request3.mode === "url") {
+    if (request3.signal.aborted) return { action: "cancel" };
+    const response = await target.requestUserInput(
+      toPageRequest(request3, options.openUrl !== void 0),
+      request3.signal
+    );
+    if (!response || request3.signal.aborted) return { action: "cancel" };
+    if (response.status !== "submitted") return { action: "decline" };
+    const choice = response.answers.find((a) => a.questionId === URL_QUESTION)?.selectedOptionIds[0];
+    if (choice === "open" && options.openUrl) {
+      options.openUrl(request3.url);
+      return { action: "accept", content: {} };
+    }
+    if (choice === "self") return { action: "accept", content: {} };
+    return { action: "decline" };
+  }
+  const form = request3;
+  let problem;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    if (request3.signal.aborted) return { action: "cancel" };
+    const response = await target.requestUserInput(
+      toUserInputRequest(form, problem),
+      request3.signal
+    );
+    if (!response || request3.signal.aborted) return { action: "cancel" };
+    if (response.status !== "submitted") return { action: "decline" };
+    const byId = new Map(response.answers.map((answer) => [answer.questionId, answer]));
+    if (form.fields.length === 0) {
+      return byId.get(CONFIRM_QUESTION)?.selectedOptionIds[0] === "yes" ? { action: "accept", content: {} } : { action: "decline" };
+    }
+    const content = {};
+    form.fields.forEach((field, i) => {
+      content[field.name] = answerValue(field, byId.get(questionId(i)));
+    });
+    const checked = validateElicitationContent(form.fields, content);
+    if (checked.ok) return { action: "accept", content: checked.value };
+    problem = checked.error;
+  }
+  return { action: "cancel" };
+}
 
 // src/manage.ts
 import { randomBytes as randomBytes3 } from "node:crypto";
@@ -3708,11 +4869,11 @@ async function disableMcp(name, deps) {
   }
   const cfg = servers[name];
   if (!cfg) return { ok: false, message: `Server "${name}" is not in config.` };
-  await safeStop(name, deps);
   cfg.enabled = false;
-  trackDisabled(deps.registry, { ...cfg, name });
   servers[name] = cfg;
   await persist(deps.configPath, full, servers);
+  trackDisabled(deps.registry, { ...cfg, name });
+  await safeStop(name, deps);
   return {
     ok: true,
     message: `Server "${name}" disabled`,
@@ -4023,6 +5184,13 @@ function requireHttpServerConfig(servers, disabledServers, name) {
   }
   return cfg;
 }
+async function loginRegistryAuthorization(manager, cfg, name, input) {
+  return requireAuthorizationManager(manager).beginLogin({
+    serverName: name,
+    resource: cfg.url,
+    ...input
+  });
+}
 async function beginRegistryAuthorization(manager, cfg, name, input) {
   return requireAuthorizationManager(manager).begin({
     serverName: name,
@@ -4080,6 +5248,56 @@ import { expectDefined } from "@wrongstack/core/utils";
 // src/wrap-tool.ts
 import { ToolCapabilities } from "@wrongstack/core/security";
 import { mcpQualifiedToolName } from "@wrongstack/core/utils";
+
+// src/structured-result.ts
+import { validateAgainstSchema } from "@wrongstack/core/utils";
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+function textBlocks(content) {
+  if (typeof content === "string") return [content];
+  if (!Array.isArray(content)) return [];
+  return content.flatMap(
+    (block) => block && typeof block === "object" && block.type === "text" ? [String(block.text ?? "")] : []
+  );
+}
+function alreadyInText(content, structured) {
+  const wanted = canonical(structured);
+  return textBlocks(content).some((text) => {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{")) return false;
+    try {
+      return canonical(JSON.parse(trimmed)) === wanted;
+    } catch {
+      return false;
+    }
+  });
+}
+function renderStructuredResult(rendered, content, structured, outputSchema) {
+  if (!structured) return rendered;
+  const parts = [rendered];
+  if (!alreadyInText(content, structured)) {
+    parts.push(`Structured result:
+${JSON.stringify(structured, null, 2)}`);
+  }
+  if (outputSchema) {
+    const check = validateAgainstSchema(structured, outputSchema);
+    if (!check.ok) {
+      const problems = check.errors.slice(0, 3).map((e) => `${e.path || "(root)"}: ${e.message}`).join("; ");
+      parts.push(
+        `[The structured result does not match the tool's declared output schema \u2014 ${problems}]`
+      );
+    }
+  }
+  return parts.filter((part) => part.length > 0).join("\n\n");
+}
+
+// src/wrap-tool.ts
 var MUTATING_RE = /create|update|delete|write|send|set|put|post|patch|remove|rename|move/i;
 function isMutatingTool(mcpTool) {
   if (MUTATING_RE.test(mcpTool.name)) return true;
@@ -4106,24 +5324,49 @@ function wrapMCPTool(serverName, mcpTool, client, permission = "confirm", observ
     inputSchema: mcpTool.inputSchema ?? { type: "object", properties: {} },
     async execute(input, ctx, opts) {
       const startedAt = Date.now();
-      observer?.onStart();
+      observer?.onStart(ctx);
       let ok = false;
       try {
         const live = typeof client === "function" ? await client() : client;
         const signal = opts?.signal ?? ctx?.signal;
         const res = await live.callTool(mcpTool.name, input, signal ? { signal } : void 0);
+        if (res.urlElicitations && res.urlElicitations.length > 0) {
+          const outcomes = await live.presentUrlElicitations(
+            res.urlElicitations,
+            signal ?? new AbortController().signal
+          );
+          throw new Error(describeUrlOutcomes(serverName, qualifiedName, outcomes));
+        }
         if (res.isError) {
           const errText = stringify(res.content);
           throw new Error(errText || `MCP tool "${qualifiedName}" failed`);
         }
         ok = true;
-        return stringify(res.content);
+        return renderStructuredResult(
+          stringify(res.content),
+          res.content,
+          res.structuredContent,
+          mcpTool.outputSchema
+        );
       } finally {
-        observer?.onFinish({ durationMs: Date.now() - startedAt, ok });
+        observer?.onFinish({ durationMs: Date.now() - startedAt, ok }, ctx);
       }
     }
   };
 }
+function describeUrlOutcomes(serverName, toolName, outcomes) {
+  const lines = outcomes.map(({ elicitation, action }) => {
+    const site = new URL(elicitation.url).host;
+    const choice = action === "accept" ? "the user agreed to open it" : action === "decline" ? "the user declined" : "no answer";
+    return `- ${site}: ${elicitation.message} (${choice})`;
+  });
+  const agreed = outcomes.length > 0 && outcomes.every((o) => o.action === "accept");
+  return [
+    `MCP server "${serverName}" needs the user to finish a step in the browser before "${toolName}" can run:`,
+    ...lines,
+    agreed ? "Ask the user to tell you when they have finished, then call the tool again." : "The user did not agree to every page, so do not call the tool again unless they ask."
+  ].join("\n");
+}
 function renderContentBlock(item) {
   const type = item["type"];
   if (type === "text") return typeof item["text"] === "string" ? item["text"] : "";
@@ -4181,7 +5424,8 @@ function applySlotTools(ctx, slot, tools, client) {
   const clientArg = slot.lazy ? () => ctx.ensureConnected(slot.cfg.name) : expectDefined(client);
   const wrapped = filtered.map(
     (t) => wrapMCPTool(slot.cfg.name, t, clientArg, slot.cfg.permission ?? "confirm", {
-      onStart: () => {
+      onStart: (caller) => {
+        if (caller) slot.activeCallers = [...slot.activeCallers ?? [], caller];
         slot.operations.inFlightCalls++;
         slot.operations.peakInFlightCalls = Math.max(
           slot.operations.peakInFlightCalls,
@@ -4189,7 +5433,9 @@ function applySlotTools(ctx, slot, tools, client) {
         );
         ctx.recordOperation(slot, "call", "started", void 0, void 0, false);
       },
-      onFinish: ({ durationMs, ok }) => {
+      onFinish: ({ durationMs, ok }, caller) => {
+        const at = caller ? slot.activeCallers?.lastIndexOf(caller) ?? -1 : -1;
+        if (at >= 0) slot.activeCallers?.splice(at, 1);
         slot.operations.inFlightCalls = Math.max(0, slot.operations.inFlightCalls - 1);
         slot.lastUsed = Date.now();
         pushBounded(slot.operations.callSamples, durationMs, MCP_OPERATION_LIMITS.LATENCY_SAMPLES);
@@ -4289,9 +5535,9 @@ async function persistSlotCapabilityManifest(cacheDir, slot) {
   if (slot.manifestWrite === pending) slot.manifestWrite = void 0;
 }
 async function attemptConnectSlot(ctx, slot) {
-  const MAX_ATTEMPTS = MCP_CONSTANTS.RECONNECT.MAX_ATTEMPTS;
+  const MAX_ATTEMPTS2 = MCP_CONSTANTS.RECONNECT.MAX_ATTEMPTS;
   let attempt = 0;
-  while (attempt < MAX_ATTEMPTS) {
+  while (attempt < MAX_ATTEMPTS2) {
     if (ctx.servers.get(slot.cfg.name) !== slot) {
       return;
     }
@@ -4305,18 +5551,17 @@ async function attemptConnectSlot(ctx, slot) {
       client = new MCPClient({
         name: slot.cfg.name,
         transport: slot.cfg.transport,
-        command: slot.cfg.command,
-        args: slot.cfg.args,
-        env: slot.cfg.env,
-        url: slot.cfg.url,
-        headers: slot.cfg.headers,
+        // `${VAR}` placeholders resolve here, per connect — never into the
+        // stored config (see config-env.ts).
+        ...expandMcpEnvPlaceholders(slot.cfg),
         bearerTokenEnv: slot.cfg.bearerTokenEnv,
         startupTimeoutMs: slot.cfg.startupTimeoutMs,
         requestTimeoutMs: slot.cfg.requestTimeoutMs,
         cwd: ctx.cwd,
         allowPrivateNetworks: slot.cfg.allowPrivateNetworks,
         passthroughEnv: slot.cfg.passthroughEnv,
-        authorizationProvider: ctx.authorizationProviderFactory?.(slot.cfg)
+        authorizationProvider: ctx.authorizationProviderFactory?.(slot.cfg),
+        elicitation: slotElicitation(ctx, slot)
       });
       if (slot.cfg.transport === "stdio") {
         client.addExitListener(ctx.onChildExit);
@@ -4389,9 +5634,9 @@ async function attemptConnectSlot(ctx, slot) {
         await client.close().catch(() => {
         });
       }
-      if (attempt >= MAX_ATTEMPTS) {
+      if (attempt >= MAX_ATTEMPTS2) {
         ctx.log.error(
-          `MCP server "${slot.cfg.name}" connect exhausted after ${MAX_ATTEMPTS} attempts`,
+          `MCP server "${slot.cfg.name}" connect exhausted after ${MAX_ATTEMPTS2} attempts`,
           err
         );
         slot.state = "failed";
@@ -4415,6 +5660,11 @@ async function attemptConnectSlot(ctx, slot) {
     }
   }
 }
+function slotElicitation(ctx, slot) {
+  const handler = ctx.elicitationHandler;
+  if (!handler) return void 0;
+  return (form) => handler({ ...form, server: slot.cfg.name, requester: slot.activeCallers?.at(-1) });
+}
 
 // src/registry-disconnect.ts
 function resetDisconnectedSlotTools(slot, toolRegistry) {
@@ -4536,6 +5786,7 @@ async function sleepIdleSlot(ctx, slot) {
       ctx.log.warn(`MCP server "${slot.cfg.name}" error during idle sleep close`, err);
     }
   }
+  if (slot.client || slot.state !== "dormant") return;
   slot.onDisconnect = void 0;
   slot.operations.sleepCount++;
   ctx.recordOperation(slot, "sleep", "idle-timeout");
@@ -4651,7 +5902,10 @@ var MCPRegistry = class _MCPRegistry {
   idleTimeoutMs;
   authorizationProviderFactory;
   authorizationManager;
+  elicitationHandler;
   operationListeners = /* @__PURE__ */ new Set();
+  /** Starts still in flight, for {@link whenStarted}. */
+  startups = /* @__PURE__ */ new Set();
   /** Single shared idle sweep timer (started lazily; unref'd; cleared on stopAll). */
   idleTimer;
   constructor(opts) {
@@ -4664,12 +5918,17 @@ var MCPRegistry = class _MCPRegistry {
     this.idleTimeoutMs = opts.idleTimeoutMs ?? MCP_CONSTANTS.IDLE.DEFAULT_TIMEOUT_MS;
     this.authorizationProviderFactory = opts.authorizationProviderFactory;
     this.authorizationManager = opts.authorizationManager;
+    this.elicitationHandler = opts.elicitationHandler;
   }
   requireSlot(name) {
     const slot = this.servers.get(name);
     if (!slot) throw new Error(`MCP server "${name}" not registered`);
     return slot;
   }
+  async loginAuthorization(name, input) {
+    const cfg = this.requireHttpServerConfig(name);
+    return loginRegistryAuthorization(this.authorizationManager, cfg, name, input);
+  }
   async beginAuthorization(name, input) {
     const cfg = this.requireHttpServerConfig(name);
     return beginRegistryAuthorization(this.authorizationManager, cfg, name, input);
@@ -4720,11 +5979,24 @@ var MCPRegistry = class _MCPRegistry {
       operations: createMCPServerOperationState()
     };
     this.servers.set(cfg.name, slot);
-    if (lazy) {
-      await this.startLazy(slot);
-    } else {
-      await this.singleFlightConnect(slot);
-    }
+    const startup = lazy ? this.startLazy(slot) : this.singleFlightConnect(slot);
+    const settled = startup.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    this.startups.add(settled);
+    void settled.finally(() => this.startups.delete(settled));
+    await startup;
+  }
+  /**
+   * Resolves once every start already in flight has connected or failed. A
+   * host that starts its servers in the background and then runs a single
+   * turn waits here, so the turn's tool list includes theirs.
+   */
+  async whenStarted() {
+    while (this.startups.size > 0) await Promise.all([...this.startups]);
   }
   /** Record an intentionally disabled configuration without opening a transport. */
   markDisabled(cfg) {
@@ -4876,10 +6148,13 @@ var MCPRegistry = class _MCPRegistry {
       slot.reconnectTimer = void 0;
     }
     slot.state = "disconnected";
-    if (slot.client) {
+    while (slot.client) {
       const client = slot.client;
+      slot.client = void 0;
+      const handler = slot.onDisconnect;
+      slot.onDisconnect = void 0;
       client.removeExitListener?.(this.onChildExit);
-      if (slot.onDisconnect) client.removeDisconnectListener?.(slot.onDisconnect);
+      if (handler) client.removeDisconnectListener?.(handler);
       client.removeToolsChangedListener?.(this.onToolsChanged);
       this.removeCatalogListeners(client);
       try {
@@ -4887,9 +6162,8 @@ var MCPRegistry = class _MCPRegistry {
       } catch (err) {
         this.log.warn(`MCP server "${name}" error during stop close`, err);
       }
-      slot.client = void 0;
+      slot.state = "disconnected";
     }
-    slot.onDisconnect = void 0;
     slot.connecting = void 0;
     resetDisconnectedSlotTools(slot, this.toolRegistry);
     slot.registeredLazy = false;
@@ -5065,6 +6339,7 @@ var MCPRegistry = class _MCPRegistry {
       cacheDir: this.cacheDir,
       cwd: this.cwd,
       authorizationProviderFactory: this.authorizationProviderFactory,
+      elicitationHandler: this.elicitationHandler,
       operationListeners: this.operationListeners,
       ensureConnected: (name) => this.ensureConnected(name),
       recordOperation: (slot, kind, reason, failureKind, durationMs, retain) => this.recordOperation(slot, kind, reason, failureKind, durationMs, retain),
@@ -5190,6 +6465,10 @@ var MCPRegistry = class _MCPRegistry {
     void this.persistCapabilityManifest(slot);
     this.log.info(`MCP server "${name}" resource catalog invalidated`);
   };
+  onResourceUpdated = (name, uri) => {
+    if (!this.servers.has(name)) return;
+    this.events.emit("mcp.resource.updated", { name, uri });
+  };
   onPromptsChanged = (name) => {
     const slot = this.servers.get(name);
     if (!slot) return;
@@ -5200,10 +6479,12 @@ var MCPRegistry = class _MCPRegistry {
   addCatalogListeners(client) {
     client.addResourcesChangedListener(this.onResourcesChanged);
     client.addPromptsChangedListener(this.onPromptsChanged);
+    client.addResourceUpdatedListener?.(this.onResourceUpdated);
   }
   removeCatalogListeners(client) {
     client.removeResourcesChangedListener?.(this.onResourcesChanged);
     client.removePromptsChangedListener?.(this.onPromptsChanged);
+    client.removeResourceUpdatedListener?.(this.onResourceUpdated);
   }
   onChildExit = (name, code, _signal) => {
     const slot = this.servers.get(name);
@@ -5288,8 +6569,8 @@ var MCPRegistry = class _MCPRegistry {
 
 // src/server.ts
 import { timingSafeEqual as timingSafeEqual2 } from "node:crypto";
-import { createServer } from "node:http";
-import { expectDefined as expectDefined3, toErrorMessage as toErrorMessage2, validateAgainstSchema } from "@wrongstack/core/utils";
+import { createServer as createServer2 } from "node:http";
+import { expectDefined as expectDefined3, toErrorMessage as toErrorMessage2, validateAgainstSchema as validateAgainstSchema2 } from "@wrongstack/core/utils";
 var PARSE_ERROR = -32700;
 var INVALID_REQUEST = -32600;
 var METHOD_NOT_FOUND = -32601;
@@ -5482,7 +6763,7 @@ var MCPServer = class {
     }
     const schema = tools.find((tool) => tool.name === name)?.inputSchema;
     if (!schema || typeof schema !== "object") return;
-    const result = validateAgainstSchema(
+    const result = validateAgainstSchema2(
       args,
       schema
     );
@@ -5527,14 +6808,14 @@ function requiredParamString(params, field, method) {
   }
   return value;
 }
-function stringRecord(value, label) {
+function stringRecord(value, label2) {
   if (value === void 0) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${label} must be an object`);
+    throw new Error(`${label2} must be an object`);
   }
   const result = {};
   for (const [key, item] of Object.entries(value)) {
-    if (typeof item !== "string") throw new Error(`${label}.${key} must be a string`);
+    if (typeof item !== "string") throw new Error(`${label2}.${key} must be a string`);
     result[key] = item;
   }
   return result;
@@ -5716,7 +6997,7 @@ function serveHttp(server, opts = {}) {
       )
     );
   }
-  const httpServer = createServer((req, res) => {
+  const httpServer = createServer2((req, res) => {
     void handleHttpRequest(server, req, res, token, log, host);
   });
   return new Promise((resolve, reject) => {
@@ -5792,8 +7073,8 @@ async function handleHttpRequest(server, req, res, token, log, boundHost) {
     });
   });
 }
-function isLoopbackHostname(hostname) {
-  const bare = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+function isLoopbackHostname(hostname2) {
+  const bare = hostname2.toLowerCase().replace(/^\[(.*)\]$/, "$1");
   return bare === "localhost" || bare === "::1" || bare === "127.0.0.1" || bare.startsWith("127.");
 }
 function originIsAcceptable(req, boundHost) {
@@ -5920,13 +7201,15 @@ var MCPVaultTokenStore = class {
   encryptEntry(value) {
     const accessToken = this.vault.encrypt(value.tokenSet.accessToken);
     const refreshToken = value.tokenSet.refreshToken ? this.vault.encrypt(value.tokenSet.refreshToken) : void 0;
-    if (!this.vault.isEncrypted(accessToken) || refreshToken && !this.vault.isEncrypted(refreshToken)) {
+    const clientSecret = value.clientSecret ? this.vault.encrypt(value.clientSecret) : void 0;
+    if (!this.vault.isEncrypted(accessToken) || refreshToken && !this.vault.isEncrypted(refreshToken) || clientSecret && !this.vault.isEncrypted(clientSecret)) {
       throw new Error("MCP token store requires an encrypting SecretVault");
     }
     return {
       serverName: value.serverName,
       resource: value.resource,
       clientId: value.clientId,
+      clientSecret,
       authorizationServer: value.authorizationServer,
       accessToken,
       refreshToken,
@@ -5937,13 +7220,14 @@ var MCPVaultTokenStore = class {
     };
   }
   decryptEntry(entry) {
-    if (!this.vault.isEncrypted(entry.accessToken) || entry.refreshToken !== void 0 && !this.vault.isEncrypted(entry.refreshToken)) {
+    if (!this.vault.isEncrypted(entry.accessToken) || entry.refreshToken !== void 0 && !this.vault.isEncrypted(entry.refreshToken) || entry.clientSecret !== void 0 && !this.vault.isEncrypted(entry.clientSecret)) {
       throw new Error("MCP token store contains an unencrypted token");
     }
     const value = {
       serverName: entry.serverName,
       resource: entry.resource,
       clientId: entry.clientId,
+      ...entry.clientSecret !== void 0 ? { clientSecret: this.vault.decrypt(entry.clientSecret) } : {},
       authorizationServer: entry.authorizationServer,
       tokenSet: {
         accessToken: this.vault.decrypt(entry.accessToken),
@@ -6014,6 +7298,7 @@ var MCPRefreshingAuthorizationProvider = class {
       tokenSet = await refreshMcpAccessToken({
         authorizationServer: state.authorizationServer,
         clientId: state.clientId,
+        clientSecret: state.clientSecret,
         resource: state.resource,
         refreshToken
       });
@@ -6087,7 +7372,7 @@ function emptyFile() {
   return { version: TOKEN_STORE_VERSION, updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(), entries: [] };
 }
 function validateStoreFile(value) {
-  if (!isRecord(value) || value["version"] !== TOKEN_STORE_VERSION || !Array.isArray(value["entries"])) {
+  if (!isRecord2(value) || value["version"] !== TOKEN_STORE_VERSION || !Array.isArray(value["entries"])) {
     throw new Error("MCP token store has an unsupported or malformed structure");
   }
   if (value["entries"].length > MAX_ENTRIES)
@@ -6099,7 +7384,7 @@ function validateStoreFile(value) {
   };
 }
 function validateEncryptedEntry(value) {
-  if (!isRecord(value)) throw new Error("MCP token store entry must be an object");
+  if (!isRecord2(value)) throw new Error("MCP token store entry must be an object");
   const resource = canonicalMcpResource(boundedString(value["resource"], "resource", 4096));
   const authorizationServer = validateMcpAuthorizationServerMetadata(value["authorizationServer"]);
   const scopes = stringArray(value["scopes"], "scopes", 128);
@@ -6111,6 +7396,7 @@ function validateEncryptedEntry(value) {
     serverName: boundedString(value["serverName"], "serverName", 256),
     resource,
     clientId: boundedString(value["clientId"], "clientId", 4096),
+    clientSecret: value["clientSecret"] === void 0 ? void 0 : boundedString(value["clientSecret"], "clientSecret", 32768),
     authorizationServer,
     accessToken: boundedString(value["accessToken"], "accessToken", 32768),
     refreshToken: value["refreshToken"] === void 0 ? void 0 : boundedString(value["refreshToken"], "refreshToken", 32768),
@@ -6137,12 +7423,13 @@ function normalizeStoredAuthorization(value) {
     serverName,
     resource,
     clientId: boundedString(value.clientId, "clientId", 4096),
+    ...value.clientSecret ? { clientSecret: boundedString(value.clientSecret, "clientSecret", 4096) } : {},
     authorizationServer,
     tokenSet,
     updatedAt: boundedString(value.updatedAt, "updatedAt", 128)
   };
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function boundedString(value, field, maxLength) {
@@ -6182,10 +7469,12 @@ export {
   disableMcp,
   discoverMcp,
   discoverMcpAuthorization,
+  elicitViaUserInput,
   enableMcp,
   exchangeMcpAuthorizationCode,
   listMcp,
   manifestConfigHash,
+  mcpEnvPlaceholders,
   negotiateProtocolVersion,
   parseAuthorizationServerMetadata,
   parseGetPromptResult,
@@ -6203,10 +7492,12 @@ export {
   readCapabilityManifest,
   readManifest,
   refreshMcpAccessToken,
+  registerMcpOAuthClient,
   removeMcp,
   restartMcp,
   serveHttp,
   serveStdio,
+  startMcpOAuthCallbackServer,
   toContentBlocks,
   updateMcp,
   validateMcpAuthorizationServerMetadata,