@databricks/appkit 0.31.0 → 0.33.0

package/dist/connectors/mcp/client.js

@@ -0,0 +1,296 @@
+import { createLogger } from "../../logging/logger.js";
+import { assertResolvedHostSafe, checkMcpUrl } from "./host-policy.js";
+
+//#region src/connectors/mcp/client.ts
+const logger = createLogger("connector:mcp");
+/**
+* Hard cap on the size of a single MCP response body, including SSE
+* frames bundled into one HTTP response. MCP `initialize` / `tools/list`
+* / `tools/call` responses are JSON-RPC payloads — single-digit kilobytes
+* in normal use. A response anywhere near this size signals either a
+* misbehaving server or an attempt to exhaust client memory; we'd rather
+* fail loudly than allocate unbounded buffers from a remote.
+*/
+const MCP_RESPONSE_BODY_LIMIT_BYTES = 1024 * 1024;
+/**
+* Read a fetch Response body into a string with a hard size cap. Aborts
+* and throws if the cumulative bytes read cross {@link
+* MCP_RESPONSE_BODY_LIMIT_BYTES}, so a remote server cannot keep
+* streaming data past the limit. Returns the empty string when the
+* response has no readable body.
+*/
+/**
+* Empty-object fallback used when an MCP server ships a missing or
+* malformed `inputSchema`. Matches the shape downstream adapters expect
+* for a function tool that takes no arguments.
+*/
+const EMPTY_TOOL_PARAMETERS = {
+	type: "object",
+	properties: {}
+};
+/**
+* Coerce a remote MCP server's reported `inputSchema` into the
+* JSONSchema7 shape AppKit's adapters expect for a function tool's
+* `parameters`. The MCP wire type is `Record<string, unknown>`, so a
+* misbehaving (or malicious) server could ship arbitrary JSON. We accept
+* only the standard `{ type: "object", properties: {...} }` shape and
+* fall back to an empty-parameters schema otherwise — the tool still
+* registers, it just can't accept arguments.
+*/
+function coerceToolParameters(inputSchema) {
+	if (!inputSchema || typeof inputSchema !== "object") return EMPTY_TOOL_PARAMETERS;
+	const { type, properties } = inputSchema;
+	if (type !== "object") return EMPTY_TOOL_PARAMETERS;
+	if (properties !== void 0 && (typeof properties !== "object" || properties === null || Array.isArray(properties))) return EMPTY_TOOL_PARAMETERS;
+	return inputSchema;
+}
+async function readResponseTextCapped(response, maxBytes, contextLabel) {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder("utf-8");
+	let total = 0;
+	let out = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) throw new Error(`MCP ${contextLabel}: response body exceeded ${maxBytes} bytes — refusing to allocate unbounded buffer from a remote server.`);
+			out += decoder.decode(value, { stream: true });
+		}
+		out += decoder.decode();
+	} finally {
+		reader.releaseLock();
+	}
+	return out;
+}
+/**
+* Lightweight MCP client for Databricks-hosted MCP servers.
+*
+* Uses raw fetch() with JSON-RPC 2.0 over HTTP — no @modelcontextprotocol/sdk
+* or LangChain dependency. Supports the Streamable HTTP transport only
+* (POST with JSON-RPC request, single JSON-RPC response). Implements exactly
+* four methods: `initialize`, `notifications/initialized`, `tools/list`,
+* `tools/call`. No prompts/resources/completion/sampling.
+*
+* All outbound URLs are gated by an {@link McpHostPolicy}: unallowlisted hosts
+* are rejected before the first byte is sent, and workspace credentials are
+* only forwarded to the same-origin workspace. See `mcp-host-policy.ts`.
+*
+* Rationale for hand-rolling JSON-RPC instead of `@modelcontextprotocol/sdk`:
+* see the file-level comment at the top of this module.
+*/
+var AppKitMcpClient = class {
+	connections = /* @__PURE__ */ new Map();
+	sessionIds = /* @__PURE__ */ new Map();
+	requestId = 0;
+	closed = false;
+	constructor(workspaceHost, authenticate, policy, options = {}) {
+		this.workspaceHost = workspaceHost;
+		this.authenticate = authenticate;
+		this.policy = policy;
+		this.options = options;
+	}
+	/**
+	* Connects every endpoint in parallel and returns a structured summary so
+	* callers can distinguish "all connected" from "some failed".
+	*
+	* Returning the result instead of throwing is deliberate: one
+	* misconfigured MCP server should not take down the entire agents plugin
+	* at boot, and the agents plugin uses the summary to warn at startup with
+	* the failed-endpoint names. Errors are also logged here so a caller
+	* that ignores the return still gets per-endpoint diagnostics.
+	*
+	* @returns `connected` lists the endpoint names that initialised
+	*   successfully; `failed` carries `{ name, error }` for the rest.
+	*/
+	async connectAll(endpoints) {
+		const results = await Promise.allSettled(endpoints.map((ep) => this.connect(ep)));
+		const out = {
+			connected: [],
+			failed: []
+		};
+		for (let i = 0; i < results.length; i++) {
+			const r = results[i];
+			const name = endpoints[i].name;
+			if (r.status === "fulfilled") out.connected.push(name);
+			else {
+				const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
+				logger.error("Failed to connect MCP server %s: %O", name, error);
+				out.failed.push({
+					name,
+					error
+				});
+			}
+		}
+		return out;
+	}
+	resolveUrl(endpoint) {
+		if (endpoint.url.startsWith("http://") || endpoint.url.startsWith("https://")) return endpoint.url;
+		return `${this.workspaceHost}${endpoint.url}`;
+	}
+	async connect(endpoint) {
+		const resolvedUrl = this.resolveUrl(endpoint);
+		const check = checkMcpUrl(resolvedUrl, this.policy);
+		if (!check.ok) throw new Error(`MCP endpoint '${endpoint.name}' refused at connect: ${check.reason}`);
+		await assertResolvedHostSafe(check.url.hostname, this.policy, this.options.dnsLookup);
+		logger.info("Connecting to MCP server: %s at %s (forwardWorkspaceAuth=%s)", endpoint.name, resolvedUrl, check.forwardWorkspaceAuth);
+		const initResponse = await this.sendRpc(resolvedUrl, "initialize", {
+			protocolVersion: "2025-03-26",
+			capabilities: {},
+			clientInfo: {
+				name: "appkit-agent",
+				version: "0.1.0"
+			}
+		}, { forwardWorkspaceAuth: check.forwardWorkspaceAuth });
+		if (initResponse.sessionId) this.sessionIds.set(endpoint.name, initResponse.sessionId);
+		const sessionId = this.sessionIds.get(endpoint.name);
+		await this.sendNotification(resolvedUrl, "notifications/initialized", {
+			sessionId,
+			forwardWorkspaceAuth: check.forwardWorkspaceAuth
+		});
+		const toolList = (await this.sendRpc(resolvedUrl, "tools/list", {}, {
+			sessionId,
+			forwardWorkspaceAuth: check.forwardWorkspaceAuth
+		})).result?.tools ?? [];
+		const tools = /* @__PURE__ */ new Map();
+		for (const tool of toolList) tools.set(tool.name, tool);
+		this.connections.set(endpoint.name, {
+			config: endpoint,
+			resolvedUrl,
+			forwardWorkspaceAuth: check.forwardWorkspaceAuth,
+			tools
+		});
+		logger.info("Connected to MCP server %s: %d tools available", endpoint.name, tools.size);
+	}
+	getAllToolDefinitions() {
+		const defs = [];
+		for (const [serverName, conn] of this.connections) for (const [toolName, schema] of conn.tools) defs.push({
+			name: `mcp.${serverName}.${toolName}`,
+			description: schema.description ?? toolName,
+			parameters: coerceToolParameters(schema.inputSchema)
+		});
+		return defs;
+	}
+	/**
+	* Whether the named MCP server may receive workspace-scoped auth headers
+	* (e.g., an OBO bearer token from an end-user request). Callers should gate
+	* auth-forwarding decisions on this to prevent credential exfiltration to
+	* non-workspace hosts.
+	*/
+	canForwardWorkspaceAuth(serverName) {
+		return this.connections.get(serverName)?.forwardWorkspaceAuth ?? false;
+	}
+	async callTool(qualifiedName, args, authHeaders, callerSignal) {
+		const parts = qualifiedName.split(".");
+		if (parts.length < 3 || parts[0] !== "mcp") throw new Error(`Invalid MCP tool name: ${qualifiedName}`);
+		const serverName = parts[1];
+		const toolName = parts.slice(2).join(".");
+		const conn = this.connections.get(serverName);
+		if (!conn) throw new Error(`MCP server not connected: ${serverName}`);
+		const sessionId = this.sessionIds.get(serverName);
+		const scopedAuthOverride = conn.forwardWorkspaceAuth ? authHeaders : void 0;
+		const result = (await this.sendRpc(conn.resolvedUrl, "tools/call", {
+			name: toolName,
+			arguments: args
+		}, {
+			authOverride: scopedAuthOverride,
+			sessionId,
+			forwardWorkspaceAuth: conn.forwardWorkspaceAuth,
+			callerSignal
+		})).result;
+		const textContent = (result.content ?? []).filter((c) => c.type === "text" && typeof c.text === "string");
+		if (result.isError) {
+			const errText = textContent.map((c) => c.text).join("\n");
+			throw new Error(errText || "MCP tool call failed");
+		}
+		return textContent.map((c) => c.text).join("\n");
+	}
+	async close() {
+		this.closed = true;
+		this.connections.clear();
+		this.sessionIds.clear();
+	}
+	async sendRpc(url, method, params, options) {
+		if (this.closed) throw new Error("MCP client is closed");
+		const request = {
+			jsonrpc: "2.0",
+			id: ++this.requestId,
+			method,
+			...params && { params }
+		};
+		const authHeaders = await this.resolveAuthHeaders(options);
+		const headers = {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+			...authHeaders
+		};
+		if (options?.sessionId) headers["Mcp-Session-Id"] = options.sessionId;
+		const fetchImpl = this.options.fetchImpl ?? fetch;
+		const signals = [AbortSignal.timeout(3e4)];
+		if (options?.callerSignal) signals.push(options.callerSignal);
+		const response = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(request),
+			signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0]
+		});
+		if (!response.ok) throw new Error(`MCP request to ${method} failed: ${response.status} ${response.statusText}`);
+		const contentType = response.headers.get("content-type") ?? "";
+		const bodyText = await readResponseTextCapped(response, MCP_RESPONSE_BODY_LIMIT_BYTES, method);
+		let json;
+		if (contentType.includes("text/event-stream")) {
+			const lastData = bodyText.split("\n").filter((line) => line.startsWith("data: ")).map((line) => line.slice(6)).pop();
+			if (!lastData) throw new Error(`MCP SSE response for ${method} contained no data`);
+			json = JSON.parse(lastData);
+		} else {
+			if (bodyText.length === 0) throw new Error(`MCP response for ${method} had an empty body`);
+			json = JSON.parse(bodyText);
+		}
+		if (json.error) throw new Error(`MCP error (${json.error.code}): ${json.error.message}`);
+		const sid = response.headers.get("mcp-session-id") ?? void 0;
+		return {
+			result: json.result,
+			sessionId: sid
+		};
+	}
+	async sendNotification(url, method, options) {
+		if (this.closed) return;
+		const authHeaders = await this.resolveAuthHeaders(options);
+		const headers = {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+			...authHeaders
+		};
+		if (options?.sessionId) headers["Mcp-Session-Id"] = options.sessionId;
+		const fetchImpl = this.options.fetchImpl ?? fetch;
+		try {
+			const response = await fetchImpl(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					method
+				}),
+				signal: AbortSignal.timeout(3e4)
+			});
+			if (!response.ok) logger.warn("MCP notification %s to %s returned %d %s — the server may have rejected the request, but per MCP spec notifications are fire-and-forget and the connection is considered established.", method, url, response.status, response.statusText);
+		} catch (err) {
+			logger.warn("MCP notification %s to %s failed before a response was received: %O", method, url, err);
+		}
+	}
+	/**
+	* Return the auth headers to send on an outbound request. Workspace auth
+	* (SP or OBO) is only resolved when `forwardWorkspaceAuth` is true; for
+	* non-workspace hosts no bearer token is attached.
+	*/
+	async resolveAuthHeaders(options) {
+		if (!options?.forwardWorkspaceAuth) return {};
+		if (options.authOverride) return options.authOverride;
+		return this.authenticate();
+	}
+};
+
+//#endregion
+export { AppKitMcpClient };
+//# sourceMappingURL=client.js.map

package/dist/connectors/mcp/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/mcp/client.ts"],"sourcesContent":["/**\n * Custom MCP over HTTP (Streamable) — not `@modelcontextprotocol/sdk`\n *\n * This module implements a tiny JSON-RPC 2.0 client on `fetch` for the subset\n * of MCP we need: `initialize`, `notifications/initialized`, `tools/list`,\n * `tools/call` over a single JSON request/response. We do not use the official\n * SDK because:\n *\n * - **Policy and auth are the product** — every outbound URL is checked with\n *   {@link McpHostPolicy} (allowlist, DNS, private/blocked IP ranges) before\n *   the first byte is sent, and workspace tokens are only forwarded when\n *   `forwardWorkspaceAuth` is true for that destination. A generic transport\n *   from the SDK would still need the same hooks; re-wrapping it would be\n *   about as much code, with a larger third-party surface to audit.\n * - **Narrow scope** — we only target Databricks-hosted MCP over Streamable\n *   HTTP, not stdio, full SSE sessions, or the rest of the protocol. A\n *   hand-rolled path keeps the call graph obvious in code review.\n * - **Zero extra runtime dependency** for this path, consistent with other\n *   small, security-sensitive AppKit pieces.\n *\n * Revisit if we add more transports, or if the SDK ships a first-class way to\n * inject our host policy and per-URL auth without fighting the default\n * transport.\n */\nimport type { AgentToolDefinition } from \"shared\";\nimport { createLogger } from \"../../logging/logger\";\nimport {\n  assertResolvedHostSafe,\n  checkMcpUrl,\n  type DnsLookup,\n  type McpHostPolicy,\n} from \"./host-policy\";\nimport type { McpEndpointConfig } from \"./types\";\n\nconst logger = createLogger(\"connector:mcp\");\n\n/**\n * Hard cap on the size of a single MCP response body, including SSE\n * frames bundled into one HTTP response. MCP `initialize` / `tools/list`\n * / `tools/call` responses are JSON-RPC payloads — single-digit kilobytes\n * in normal use. A response anywhere near this size signals either a\n * misbehaving server or an attempt to exhaust client memory; we'd rather\n * fail loudly than allocate unbounded buffers from a remote.\n */\nconst MCP_RESPONSE_BODY_LIMIT_BYTES = 1024 * 1024;\n\n/**\n * Read a fetch Response body into a string with a hard size cap. Aborts\n * and throws if the cumulative bytes read cross {@link\n * MCP_RESPONSE_BODY_LIMIT_BYTES}, so a remote server cannot keep\n * streaming data past the limit. Returns the empty string when the\n * response has no readable body.\n */\n/**\n * Empty-object fallback used when an MCP server ships a missing or\n * malformed `inputSchema`. Matches the shape downstream adapters expect\n * for a function tool that takes no arguments.\n */\nconst EMPTY_TOOL_PARAMETERS: AgentToolDefinition[\"parameters\"] = {\n  type: \"object\",\n  properties: {},\n};\n\n/**\n * Coerce a remote MCP server's reported `inputSchema` into the\n * JSONSchema7 shape AppKit's adapters expect for a function tool's\n * `parameters`. The MCP wire type is `Record<string, unknown>`, so a\n * misbehaving (or malicious) server could ship arbitrary JSON. We accept\n * only the standard `{ type: \"object\", properties: {...} }` shape and\n * fall back to an empty-parameters schema otherwise — the tool still\n * registers, it just can't accept arguments.\n */\nfunction coerceToolParameters(\n  inputSchema: Record<string, unknown> | undefined,\n): AgentToolDefinition[\"parameters\"] {\n  if (!inputSchema || typeof inputSchema !== \"object\") {\n    return EMPTY_TOOL_PARAMETERS;\n  }\n  const { type, properties } = inputSchema;\n  if (type !== \"object\") return EMPTY_TOOL_PARAMETERS;\n  if (\n    properties !== undefined &&\n    (typeof properties !== \"object\" ||\n      properties === null ||\n      Array.isArray(properties))\n  ) {\n    return EMPTY_TOOL_PARAMETERS;\n  }\n  return inputSchema as AgentToolDefinition[\"parameters\"];\n}\n\nasync function readResponseTextCapped(\n  response: Response,\n  maxBytes: number,\n  contextLabel: string,\n): Promise<string> {\n  if (!response.body) return \"\";\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder(\"utf-8\");\n  let total = 0;\n  let out = \"\";\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      total += value.byteLength;\n      if (total > maxBytes) {\n        throw new Error(\n          `MCP ${contextLabel}: response body exceeded ${maxBytes} bytes — refusing to allocate unbounded buffer from a remote server.`,\n        );\n      }\n      out += decoder.decode(value, { stream: true });\n    }\n    out += decoder.decode();\n  } finally {\n    reader.releaseLock();\n  }\n  return out;\n}\n\ninterface JsonRpcRequest {\n  jsonrpc: \"2.0\";\n  id: number;\n  method: string;\n  params?: Record<string, unknown>;\n}\n\ninterface JsonRpcResponse {\n  jsonrpc: \"2.0\";\n  id: number;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\ninterface McpToolSchema {\n  name: string;\n  description?: string;\n  inputSchema?: Record<string, unknown>;\n}\n\ninterface McpToolCallResult {\n  content: Array<{ type: string; text?: string }>;\n  isError?: boolean;\n}\n\n/**\n * Per-endpoint outcome of {@link AppKitMcpClient.connectAll}. Callers (the\n * agents plugin in particular) use the split to warn at startup when some\n * MCP servers are unreachable without aborting boot for the rest.\n */\nexport interface McpConnectAllResult {\n  connected: string[];\n  failed: Array<{ name: string; error: Error }>;\n}\n\ninterface McpServerConnection {\n  config: McpEndpointConfig;\n  resolvedUrl: string;\n  /**\n   * Whether workspace auth (SP / OBO) may be forwarded to this endpoint's URL.\n   * Decided at `connect()` time via {@link McpHostPolicy} and cached for the\n   * lifetime of the connection.\n   */\n  forwardWorkspaceAuth: boolean;\n  tools: Map<string, McpToolSchema>;\n}\n\n/**\n * Lightweight MCP client for Databricks-hosted MCP servers.\n *\n * Uses raw fetch() with JSON-RPC 2.0 over HTTP — no @modelcontextprotocol/sdk\n * or LangChain dependency. Supports the Streamable HTTP transport only\n * (POST with JSON-RPC request, single JSON-RPC response). Implements exactly\n * four methods: `initialize`, `notifications/initialized`, `tools/list`,\n * `tools/call`. No prompts/resources/completion/sampling.\n *\n * All outbound URLs are gated by an {@link McpHostPolicy}: unallowlisted hosts\n * are rejected before the first byte is sent, and workspace credentials are\n * only forwarded to the same-origin workspace. See `mcp-host-policy.ts`.\n *\n * Rationale for hand-rolling JSON-RPC instead of `@modelcontextprotocol/sdk`:\n * see the file-level comment at the top of this module.\n */\nexport class AppKitMcpClient {\n  private connections = new Map<string, McpServerConnection>();\n  private sessionIds = new Map<string, string>();\n  private requestId = 0;\n  private closed = false;\n\n  constructor(\n    private workspaceHost: string,\n    private authenticate: () => Promise<Record<string, string>>,\n    private policy: McpHostPolicy,\n    private options: { dnsLookup?: DnsLookup; fetchImpl?: typeof fetch } = {},\n  ) {}\n\n  /**\n   * Connects every endpoint in parallel and returns a structured summary so\n   * callers can distinguish \"all connected\" from \"some failed\".\n   *\n   * Returning the result instead of throwing is deliberate: one\n   * misconfigured MCP server should not take down the entire agents plugin\n   * at boot, and the agents plugin uses the summary to warn at startup with\n   * the failed-endpoint names. Errors are also logged here so a caller\n   * that ignores the return still gets per-endpoint diagnostics.\n   *\n   * @returns `connected` lists the endpoint names that initialised\n   *   successfully; `failed` carries `{ name, error }` for the rest.\n   */\n  async connectAll(\n    endpoints: McpEndpointConfig[],\n  ): Promise<McpConnectAllResult> {\n    const results = await Promise.allSettled(\n      endpoints.map((ep) => this.connect(ep)),\n    );\n    const out: McpConnectAllResult = { connected: [], failed: [] };\n    for (let i = 0; i < results.length; i++) {\n      const r = results[i];\n      const name = endpoints[i].name;\n      if (r.status === \"fulfilled\") {\n        out.connected.push(name);\n      } else {\n        const error =\n          r.reason instanceof Error ? r.reason : new Error(String(r.reason));\n        logger.error(\"Failed to connect MCP server %s: %O\", name, error);\n        out.failed.push({ name, error });\n      }\n    }\n    return out;\n  }\n\n  private resolveUrl(endpoint: McpEndpointConfig): string {\n    if (\n      endpoint.url.startsWith(\"http://\") ||\n      endpoint.url.startsWith(\"https://\")\n    ) {\n      return endpoint.url;\n    }\n    return `${this.workspaceHost}${endpoint.url}`;\n  }\n\n  async connect(endpoint: McpEndpointConfig): Promise<void> {\n    const resolvedUrl = this.resolveUrl(endpoint);\n    const check = checkMcpUrl(resolvedUrl, this.policy);\n    if (!check.ok) {\n      throw new Error(\n        `MCP endpoint '${endpoint.name}' refused at connect: ${check.reason}`,\n      );\n    }\n    await assertResolvedHostSafe(\n      check.url.hostname,\n      this.policy,\n      this.options.dnsLookup,\n    );\n\n    logger.info(\n      \"Connecting to MCP server: %s at %s (forwardWorkspaceAuth=%s)\",\n      endpoint.name,\n      resolvedUrl,\n      check.forwardWorkspaceAuth,\n    );\n\n    const initResponse = await this.sendRpc(\n      resolvedUrl,\n      \"initialize\",\n      {\n        protocolVersion: \"2025-03-26\",\n        capabilities: {},\n        clientInfo: { name: \"appkit-agent\", version: \"0.1.0\" },\n      },\n      { forwardWorkspaceAuth: check.forwardWorkspaceAuth },\n    );\n\n    if (initResponse.sessionId) {\n      this.sessionIds.set(endpoint.name, initResponse.sessionId);\n    }\n    const sessionId = this.sessionIds.get(endpoint.name);\n\n    await this.sendNotification(resolvedUrl, \"notifications/initialized\", {\n      sessionId,\n      forwardWorkspaceAuth: check.forwardWorkspaceAuth,\n    });\n\n    const listResponse = await this.sendRpc(\n      resolvedUrl,\n      \"tools/list\",\n      {},\n      { sessionId, forwardWorkspaceAuth: check.forwardWorkspaceAuth },\n    );\n    const toolList =\n      (listResponse.result as { tools?: McpToolSchema[] })?.tools ?? [];\n\n    const tools = new Map<string, McpToolSchema>();\n    for (const tool of toolList) {\n      tools.set(tool.name, tool);\n    }\n\n    this.connections.set(endpoint.name, {\n      config: endpoint,\n      resolvedUrl,\n      forwardWorkspaceAuth: check.forwardWorkspaceAuth,\n      tools,\n    });\n    logger.info(\n      \"Connected to MCP server %s: %d tools available\",\n      endpoint.name,\n      tools.size,\n    );\n  }\n\n  getAllToolDefinitions(): AgentToolDefinition[] {\n    const defs: AgentToolDefinition[] = [];\n    for (const [serverName, conn] of this.connections) {\n      for (const [toolName, schema] of conn.tools) {\n        defs.push({\n          name: `mcp.${serverName}.${toolName}`,\n          description: schema.description ?? toolName,\n          parameters: coerceToolParameters(schema.inputSchema),\n        });\n      }\n    }\n    return defs;\n  }\n\n  /**\n   * Whether the named MCP server may receive workspace-scoped auth headers\n   * (e.g., an OBO bearer token from an end-user request). Callers should gate\n   * auth-forwarding decisions on this to prevent credential exfiltration to\n   * non-workspace hosts.\n   */\n  canForwardWorkspaceAuth(serverName: string): boolean {\n    return this.connections.get(serverName)?.forwardWorkspaceAuth ?? false;\n  }\n\n  async callTool(\n    qualifiedName: string,\n    args: unknown,\n    authHeaders?: Record<string, string>,\n    callerSignal?: AbortSignal,\n  ): Promise<string> {\n    const parts = qualifiedName.split(\".\");\n    if (parts.length < 3 || parts[0] !== \"mcp\") {\n      throw new Error(`Invalid MCP tool name: ${qualifiedName}`);\n    }\n    const serverName = parts[1];\n    const toolName = parts.slice(2).join(\".\");\n\n    const conn = this.connections.get(serverName);\n    if (!conn) {\n      throw new Error(`MCP server not connected: ${serverName}`);\n    }\n\n    const sessionId = this.sessionIds.get(serverName);\n    // authHeaders are caller-supplied credentials (typically the OBO token).\n    // Only honor them if the destination URL was admitted with\n    // forwardWorkspaceAuth=true at connect time.\n    const scopedAuthOverride = conn.forwardWorkspaceAuth\n      ? authHeaders\n      : undefined;\n\n    const rpcResult = await this.sendRpc(\n      conn.resolvedUrl,\n      \"tools/call\",\n      { name: toolName, arguments: args },\n      {\n        authOverride: scopedAuthOverride,\n        sessionId,\n        forwardWorkspaceAuth: conn.forwardWorkspaceAuth,\n        callerSignal,\n      },\n    );\n    const result = rpcResult.result as McpToolCallResult;\n\n    // `text` is optional on `McpToolCallResult.content[]` per the MCP\n    // spec; filtering only on `type === \"text\"` lets `c.text` be\n    // `undefined`, which `Array.join` would render as the literal\n    // string `\"undefined\"` and ship to the agent. Narrow on both\n    // fields so the joined string only contains real text.\n    const textContent = (result.content ?? []).filter(\n      (c): c is { type: \"text\"; text: string } =>\n        c.type === \"text\" && typeof c.text === \"string\",\n    );\n\n    if (result.isError) {\n      const errText = textContent.map((c) => c.text).join(\"\\n\");\n      throw new Error(errText || \"MCP tool call failed\");\n    }\n\n    return textContent.map((c) => c.text).join(\"\\n\");\n  }\n\n  async close(): Promise<void> {\n    this.closed = true;\n    this.connections.clear();\n    this.sessionIds.clear();\n  }\n\n  private async sendRpc(\n    url: string,\n    method: string,\n    params?: Record<string, unknown>,\n    options?: {\n      authOverride?: Record<string, string>;\n      sessionId?: string;\n      forwardWorkspaceAuth?: boolean;\n      /**\n       * Optional external abort signal (typically the agent's stream signal).\n       * Composed with the built-in 30 s timeout so `/cancel` or agent-run\n       * shutdown immediately propagates to the MCP fetch rather than waiting\n       * for the remote server to respond.\n       */\n      callerSignal?: AbortSignal;\n    },\n  ): Promise<{ result: unknown; sessionId?: string }> {\n    if (this.closed) throw new Error(\"MCP client is closed\");\n\n    const request: JsonRpcRequest = {\n      jsonrpc: \"2.0\",\n      id: ++this.requestId,\n      method,\n      ...(params && { params }),\n    };\n\n    const authHeaders = await this.resolveAuthHeaders(options);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      Accept: \"application/json, text/event-stream\",\n      ...authHeaders,\n    };\n    if (options?.sessionId) {\n      headers[\"Mcp-Session-Id\"] = options.sessionId;\n    }\n\n    const fetchImpl = this.options.fetchImpl ?? fetch;\n    const signals: AbortSignal[] = [AbortSignal.timeout(30_000)];\n    if (options?.callerSignal) signals.push(options.callerSignal);\n    const response = await fetchImpl(url, {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify(request),\n      signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `MCP request to ${method} failed: ${response.status} ${response.statusText}`,\n      );\n    }\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n    // Always read the body via the capped helper so a misconfigured or\n    // malicious server can't exhaust client memory by streaming an\n    // unbounded payload. Applies to both SSE (`response.text()` would\n    // have buffered the whole stream) and plain JSON (`response.json()`\n    // does the same internally).\n    const bodyText = await readResponseTextCapped(\n      response,\n      MCP_RESPONSE_BODY_LIMIT_BYTES,\n      method,\n    );\n    let json: JsonRpcResponse;\n\n    if (contentType.includes(\"text/event-stream\")) {\n      const lastData = bodyText\n        .split(\"\\n\")\n        .filter((line) => line.startsWith(\"data: \"))\n        .map((line) => line.slice(6))\n        .pop();\n      if (!lastData) {\n        throw new Error(`MCP SSE response for ${method} contained no data`);\n      }\n      json = JSON.parse(lastData) as JsonRpcResponse;\n    } else {\n      if (bodyText.length === 0) {\n        throw new Error(`MCP response for ${method} had an empty body`);\n      }\n      json = JSON.parse(bodyText) as JsonRpcResponse;\n    }\n\n    if (json.error) {\n      throw new Error(`MCP error (${json.error.code}): ${json.error.message}`);\n    }\n\n    const sid = response.headers.get(\"mcp-session-id\") ?? undefined;\n    return { result: json.result, sessionId: sid };\n  }\n\n  private async sendNotification(\n    url: string,\n    method: string,\n    options?: {\n      sessionId?: string;\n      forwardWorkspaceAuth?: boolean;\n    },\n  ): Promise<void> {\n    if (this.closed) return;\n\n    const authHeaders = await this.resolveAuthHeaders(options);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      Accept: \"application/json, text/event-stream\",\n      ...authHeaders,\n    };\n    if (options?.sessionId) {\n      headers[\"Mcp-Session-Id\"] = options.sessionId;\n    }\n\n    const fetchImpl = this.options.fetchImpl ?? fetch;\n    // MCP notifications are fire-and-forget per spec — we don't throw on\n    // failure. But silently swallowing 4xx/5xx hides server-side\n    // rejections that would otherwise look like a successful connect()\n    // followed by mysterious tool-call failures. Surface the bad status\n    // via the logger so the dev sees it without breaking the protocol\n    // contract.\n    try {\n      const response = await fetchImpl(url, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ jsonrpc: \"2.0\", method }),\n        signal: AbortSignal.timeout(30_000),\n      });\n      if (!response.ok) {\n        logger.warn(\n          \"MCP notification %s to %s returned %d %s — the server may have rejected the request, but per MCP spec notifications are fire-and-forget and the connection is considered established.\",\n          method,\n          url,\n          response.status,\n          response.statusText,\n        );\n      }\n    } catch (err) {\n      logger.warn(\n        \"MCP notification %s to %s failed before a response was received: %O\",\n        method,\n        url,\n        err,\n      );\n    }\n  }\n\n  /**\n   * Return the auth headers to send on an outbound request. Workspace auth\n   * (SP or OBO) is only resolved when `forwardWorkspaceAuth` is true; for\n   * non-workspace hosts no bearer token is attached.\n   */\n  private async resolveAuthHeaders(options?: {\n    authOverride?: Record<string, string>;\n    forwardWorkspaceAuth?: boolean;\n  }): Promise<Record<string, string>> {\n    if (!options?.forwardWorkspaceAuth) return {};\n    if (options.authOverride) return options.authOverride;\n    return this.authenticate();\n  }\n}\n"],"mappings":"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"}

package/dist/connectors/mcp/host-policy.d.ts

@@ -0,0 +1,51 @@
+//#region src/connectors/mcp/host-policy.d.ts
+/**
+ * DNS lookup function compatible with `dns/promises.lookup(host, { all: true })`.
+ * Exposed as an injection point so callers (tests, custom DNS resolvers) can
+ * override the default resolver.
+ */
+type DnsLookup = (hostname: string, options: {
+  all: true;
+}) => Promise<Array<{
+  address: string;
+  family: number;
+}>>;
+/**
+ * Policy that decides whether a given MCP endpoint URL is allowed and whether
+ * Databricks workspace credentials (SP or OBO) may be forwarded to it.
+ *
+ * The default posture is zero-trust: only same-origin workspace URLs receive
+ * workspace credentials, and all other destinations must be explicitly
+ * allowlisted by the application developer. Private / link-local IP ranges
+ * are blocked outright to prevent SSRF into cloud metadata services.
+ */
+interface McpHostPolicy {
+  /** Lowercased hostname of the Databricks workspace (same-origin target). */
+  readonly workspaceHostname: string;
+  /** Additional allowlisted hostnames (lowercased). Workspace auth is NEVER forwarded to these. */
+  readonly trustedHosts: ReadonlySet<string>;
+  /** Permit `http://localhost`, `127.0.0.1`, `::1` URLs. Typically true only in development. */
+  readonly allowLocalhost: boolean;
+}
+/**
+ * Config shape accepted by {@link buildMcpHostPolicy}, matching the
+ * `mcp` field on `AgentsPluginConfig`.
+ */
+interface McpHostPolicyConfig {
+  /**
+   * Additional hostnames that may host custom MCP servers beyond the same-origin
+   * workspace. Compared case-insensitively; bare hostnames only (no scheme or
+   * path). Workspace credentials (SP / OBO) are never forwarded to these hosts —
+   * they must handle authentication themselves.
+   */
+  trustedHosts?: string[];
+  /**
+   * Allow `http://localhost`, `127.0.0.1`, and `::1` MCP URLs for local
+   * development. Defaults to `true` when `NODE_ENV !== "production"`,
+   * otherwise `false`. Workspace credentials are never forwarded to localhost.
+   */
+  allowLocalhost?: boolean;
+}
+//#endregion
+export { DnsLookup, McpHostPolicy, McpHostPolicyConfig };
+//# sourceMappingURL=host-policy.d.ts.map

package/dist/connectors/mcp/host-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-policy.d.ts","names":[],"sources":["../../../src/connectors/mcp/host-policy.ts"],"mappings":";;AAQA;;;;KAAY,SAAA,IACV,QAAA,UACA,OAAA;EAAW,GAAA;AAAA,MACR,OAAA,CAAQ,KAAA;EAAQ,OAAA;EAAiB,MAAA;AAAA;;;;AAWtC;;;;;;UAAiB,aAAA;EAMN;EAAA,SAJA,iBAAA;EAIc;EAAA,SAFd,YAAA,EAAc,WAAA;EASW;EAAA,SAPzB,cAAA;AAAA;;;;;UAOM,mBAAA;;;;;;;EAOf,YAAA;;;;;;EAMA,cAAA;AAAA"}

package/dist/connectors/mcp/host-policy.js

@@ -0,0 +1,168 @@
+import { lookup } from "node:dns/promises";
+import { isIP, isIPv4 } from "node:net";
+
+//#region src/connectors/mcp/host-policy.ts
+/** Build an {@link McpHostPolicy} from user config + the resolved workspace URL. */
+function buildMcpHostPolicy(config, workspaceHost) {
+	const workspaceHostname = safeHostname(workspaceHost);
+	if (!workspaceHostname) throw new Error(`Invalid workspace host for MCP policy: ${JSON.stringify(workspaceHost)}`);
+	return {
+		workspaceHostname,
+		trustedHosts: new Set((config?.trustedHosts ?? []).map((h) => h.trim().toLowerCase())),
+		allowLocalhost: config?.allowLocalhost ?? process.env.NODE_ENV !== "production"
+	};
+}
+/**
+* Synchronously decide whether an MCP URL is allowed under the given policy
+* and whether workspace credentials may be forwarded to it.
+*
+* Hard rejections:
+* - Non-`http(s)` schemes.
+* - `http://` unless the host is localhost AND `allowLocalhost` is true.
+* - Hosts that are neither same-origin workspace, localhost (if allowed),
+*   nor in `trustedHosts`.
+*/
+function checkMcpUrl(rawUrl, policy) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		return {
+			ok: false,
+			reason: `MCP URL is not a valid absolute URL: ${rawUrl}`
+		};
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return {
+		ok: false,
+		reason: `MCP URL scheme '${url.protocol}' is not allowed (http(s) only): ${rawUrl}`
+	};
+	const host = url.hostname.toLowerCase();
+	const isLoopback = isLoopbackHost(host);
+	if (url.protocol === "http:" && !(isLoopback && policy.allowLocalhost)) return {
+		ok: false,
+		reason: `MCP URL uses plaintext http:// which forwards bearer tokens in cleartext: ${rawUrl}. Use https:// or enable allowLocalhost for a localhost dev server.`
+	};
+	if (host === policy.workspaceHostname) return {
+		ok: true,
+		forwardWorkspaceAuth: true,
+		url
+	};
+	if (isLoopback) {
+		if (!policy.allowLocalhost) return {
+			ok: false,
+			reason: `MCP URL points to localhost but allowLocalhost is disabled: ${rawUrl}`
+		};
+		return {
+			ok: true,
+			forwardWorkspaceAuth: false,
+			url
+		};
+	}
+	if (policy.trustedHosts.has(host)) return {
+		ok: true,
+		forwardWorkspaceAuth: false,
+		url
+	};
+	return {
+		ok: false,
+		reason: `MCP host '${host}' is not allowed. Either use a same-origin workspace URL (${policy.workspaceHostname}) or add it to agents({ mcp: { trustedHosts: ['${host}'] } }).`
+	};
+}
+/**
+* Resolve `hostname` via DNS and assert that none of its addresses fall in a
+* blocked IP range (loopback, RFC1918, link-local, CGNAT, cloud metadata).
+*
+* Throws with a descriptive error if any resolved address is blocked. Pass
+* `allowLocalhost: true` to permit `127.0.0.1` / `::1` specifically.
+*
+* Note: this only guards against hosts that statically resolve to private
+* ranges. Full SSRF protection requires socket-level IP pinning after
+* resolution (DNS rebinding defense), which is out of scope here.
+*/
+async function assertResolvedHostSafe(hostname, policy, lookup$1 = lookup) {
+	const lowered = hostname.toLowerCase();
+	if (isIP(lowered)) {
+		if (isBlockedIp(lowered, policy.allowLocalhost)) throw new Error(`MCP host ${lowered} is in a blocked IP range`);
+		return;
+	}
+	if (lowered === "localhost") {
+		if (!policy.allowLocalhost) throw new Error(`MCP host localhost is not allowed under the current policy`);
+		return;
+	}
+	let resolved;
+	try {
+		resolved = await lookup$1(hostname, { all: true });
+	} catch (cause) {
+		throw new Error(`MCP host ${hostname} could not be resolved via DNS: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	if (resolved.length === 0) throw new Error(`MCP host ${hostname} returned no DNS addresses`);
+	for (const { address } of resolved) if (isBlockedIp(address, policy.allowLocalhost)) throw new Error(`MCP host ${hostname} resolved to blocked address ${address} (private / link-local ranges are not allowed)`);
+}
+/** Whether a raw hostname literal is one of the recognised loopback aliases. */
+function isLoopbackHost(host) {
+	const lowered = host.toLowerCase();
+	return lowered === "localhost" || lowered === "127.0.0.1" || lowered === "::1" || lowered === "[::1]" || lowered === "0:0:0:0:0:0:0:1";
+}
+/**
+* Check whether a resolved IP address is in a range that should never receive
+* workspace credentials. `allowLocalhost` carves out 127.0.0.0/8 and ::1.
+*/
+function isBlockedIp(address, allowLocalhost) {
+	if (isIPv4(address)) return isBlockedIpv4(address, allowLocalhost);
+	if (isIP(address) === 6) return isBlockedIpv6(address, allowLocalhost);
+	return true;
+}
+function isBlockedIpv4(addr, allowLocalhost) {
+	const parts = addr.split(".").map((p) => Number.parseInt(p, 10));
+	if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) return true;
+	const [a, b] = parts;
+	if (a === 0) return true;
+	if (a === 127) return !allowLocalhost;
+	if (a === 10) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 168) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 100 && b >= 64 && b <= 127) return true;
+	if (a >= 224) return true;
+	return false;
+}
+function isBlockedIpv6(addr, allowLocalhost) {
+	const lowered = addr.toLowerCase().replace(/^\[|\]$/g, "");
+	if (lowered === "::") return true;
+	if (lowered === "::1" || lowered === "0:0:0:0:0:0:0:1") return !allowLocalhost;
+	if (lowered.startsWith("::ffff:")) {
+		const tail = lowered.slice(7);
+		if (isIPv4(tail)) return isBlockedIpv4(tail, allowLocalhost);
+		const hexV4 = hexPairToDottedIpv4(tail);
+		if (hexV4) return isBlockedIpv4(hexV4, allowLocalhost);
+	}
+	if (/^f[cd][0-9a-f]{2}:/.test(lowered)) return true;
+	if (/^fe[89ab][0-9a-f]:/.test(lowered)) return true;
+	if (lowered.startsWith("ff")) return true;
+	return false;
+}
+/**
+* Parse the trailing two hex groups of an IPv4-mapped IPv6 address written
+* in colon-hex form (e.g. `a9fe:a9fe`) into the equivalent dotted-quad IPv4
+* representation (`169.254.169.254`). Returns null for anything else.
+*/
+function hexPairToDottedIpv4(tail) {
+	const match = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (!match) return null;
+	const hi = Number.parseInt(match[1], 16);
+	const lo = Number.parseInt(match[2], 16);
+	if (!Number.isFinite(hi) || !Number.isFinite(lo)) return null;
+	if (hi < 0 || hi > 65535 || lo < 0 || lo > 65535) return null;
+	return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+}
+function safeHostname(rawUrl) {
+	try {
+		return new URL(rawUrl).hostname.toLowerCase();
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { assertResolvedHostSafe, buildMcpHostPolicy, checkMcpUrl };
+//# sourceMappingURL=host-policy.js.map

package/dist/connectors/mcp/host-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-policy.js","names":["defaultLookup","lookup"],"sources":["../../../src/connectors/mcp/host-policy.ts"],"sourcesContent":["import { lookup as defaultLookup } from \"node:dns/promises\";\nimport { isIP, isIPv4 } from \"node:net\";\n\n/**\n * DNS lookup function compatible with `dns/promises.lookup(host, { all: true })`.\n * Exposed as an injection point so callers (tests, custom DNS resolvers) can\n * override the default resolver.\n */\nexport type DnsLookup = (\n  hostname: string,\n  options: { all: true },\n) => Promise<Array<{ address: string; family: number }>>;\n\n/**\n * Policy that decides whether a given MCP endpoint URL is allowed and whether\n * Databricks workspace credentials (SP or OBO) may be forwarded to it.\n *\n * The default posture is zero-trust: only same-origin workspace URLs receive\n * workspace credentials, and all other destinations must be explicitly\n * allowlisted by the application developer. Private / link-local IP ranges\n * are blocked outright to prevent SSRF into cloud metadata services.\n */\nexport interface McpHostPolicy {\n  /** Lowercased hostname of the Databricks workspace (same-origin target). */\n  readonly workspaceHostname: string;\n  /** Additional allowlisted hostnames (lowercased). Workspace auth is NEVER forwarded to these. */\n  readonly trustedHosts: ReadonlySet<string>;\n  /** Permit `http://localhost`, `127.0.0.1`, `::1` URLs. Typically true only in development. */\n  readonly allowLocalhost: boolean;\n}\n\n/**\n * Config shape accepted by {@link buildMcpHostPolicy}, matching the\n * `mcp` field on `AgentsPluginConfig`.\n */\nexport interface McpHostPolicyConfig {\n  /**\n   * Additional hostnames that may host custom MCP servers beyond the same-origin\n   * workspace. Compared case-insensitively; bare hostnames only (no scheme or\n   * path). Workspace credentials (SP / OBO) are never forwarded to these hosts —\n   * they must handle authentication themselves.\n   */\n  trustedHosts?: string[];\n  /**\n   * Allow `http://localhost`, `127.0.0.1`, and `::1` MCP URLs for local\n   * development. Defaults to `true` when `NODE_ENV !== \"production\"`,\n   * otherwise `false`. Workspace credentials are never forwarded to localhost.\n   */\n  allowLocalhost?: boolean;\n}\n\n/** Build an {@link McpHostPolicy} from user config + the resolved workspace URL. */\nexport function buildMcpHostPolicy(\n  config: McpHostPolicyConfig | undefined,\n  workspaceHost: string,\n): McpHostPolicy {\n  const workspaceHostname = safeHostname(workspaceHost);\n  if (!workspaceHostname) {\n    throw new Error(\n      `Invalid workspace host for MCP policy: ${JSON.stringify(workspaceHost)}`,\n    );\n  }\n  const trustedHosts = new Set(\n    (config?.trustedHosts ?? []).map((h) => h.trim().toLowerCase()),\n  );\n  const allowLocalhost =\n    config?.allowLocalhost ?? process.env.NODE_ENV !== \"production\";\n  return { workspaceHostname, trustedHosts, allowLocalhost };\n}\n\ntype McpUrlCheck =\n  | {\n      readonly ok: true;\n      /** Whether it is safe to forward workspace-scoped credentials (SP/OBO) to this URL. */\n      readonly forwardWorkspaceAuth: boolean;\n      /** Parsed URL for reuse by the caller. */\n      readonly url: URL;\n    }\n  | { readonly ok: false; readonly reason: string };\n\n/**\n * Synchronously decide whether an MCP URL is allowed under the given policy\n * and whether workspace credentials may be forwarded to it.\n *\n * Hard rejections:\n * - Non-`http(s)` schemes.\n * - `http://` unless the host is localhost AND `allowLocalhost` is true.\n * - Hosts that are neither same-origin workspace, localhost (if allowed),\n *   nor in `trustedHosts`.\n */\nexport function checkMcpUrl(\n  rawUrl: string,\n  policy: McpHostPolicy,\n): McpUrlCheck {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    return {\n      ok: false,\n      reason: `MCP URL is not a valid absolute URL: ${rawUrl}`,\n    };\n  }\n\n  if (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n    return {\n      ok: false,\n      reason: `MCP URL scheme '${url.protocol}' is not allowed (http(s) only): ${rawUrl}`,\n    };\n  }\n\n  const host = url.hostname.toLowerCase();\n  const isLoopback = isLoopbackHost(host);\n\n  if (url.protocol === \"http:\" && !(isLoopback && policy.allowLocalhost)) {\n    return {\n      ok: false,\n      reason: `MCP URL uses plaintext http:// which forwards bearer tokens in cleartext: ${rawUrl}. Use https:// or enable allowLocalhost for a localhost dev server.`,\n    };\n  }\n\n  if (host === policy.workspaceHostname) {\n    return { ok: true, forwardWorkspaceAuth: true, url };\n  }\n\n  if (isLoopback) {\n    if (!policy.allowLocalhost) {\n      return {\n        ok: false,\n        reason: `MCP URL points to localhost but allowLocalhost is disabled: ${rawUrl}`,\n      };\n    }\n    return { ok: true, forwardWorkspaceAuth: false, url };\n  }\n\n  if (policy.trustedHosts.has(host)) {\n    return { ok: true, forwardWorkspaceAuth: false, url };\n  }\n\n  return {\n    ok: false,\n    reason: `MCP host '${host}' is not allowed. Either use a same-origin workspace URL (${policy.workspaceHostname}) or add it to agents({ mcp: { trustedHosts: ['${host}'] } }).`,\n  };\n}\n\n/**\n * Resolve `hostname` via DNS and assert that none of its addresses fall in a\n * blocked IP range (loopback, RFC1918, link-local, CGNAT, cloud metadata).\n *\n * Throws with a descriptive error if any resolved address is blocked. Pass\n * `allowLocalhost: true` to permit `127.0.0.1` / `::1` specifically.\n *\n * Note: this only guards against hosts that statically resolve to private\n * ranges. Full SSRF protection requires socket-level IP pinning after\n * resolution (DNS rebinding defense), which is out of scope here.\n */\nexport async function assertResolvedHostSafe(\n  hostname: string,\n  policy: McpHostPolicy,\n  lookup: DnsLookup = defaultLookup,\n): Promise<void> {\n  const lowered = hostname.toLowerCase();\n\n  if (isIP(lowered)) {\n    if (isBlockedIp(lowered, policy.allowLocalhost)) {\n      throw new Error(`MCP host ${lowered} is in a blocked IP range`);\n    }\n    return;\n  }\n\n  if (lowered === \"localhost\") {\n    if (!policy.allowLocalhost) {\n      throw new Error(\n        `MCP host localhost is not allowed under the current policy`,\n      );\n    }\n    return;\n  }\n\n  let resolved: Array<{ address: string }>;\n  try {\n    resolved = await lookup(hostname, { all: true });\n  } catch (cause) {\n    throw new Error(\n      `MCP host ${hostname} could not be resolved via DNS: ${cause instanceof Error ? cause.message : String(cause)}`,\n    );\n  }\n\n  if (resolved.length === 0) {\n    throw new Error(`MCP host ${hostname} returned no DNS addresses`);\n  }\n\n  for (const { address } of resolved) {\n    if (isBlockedIp(address, policy.allowLocalhost)) {\n      throw new Error(\n        `MCP host ${hostname} resolved to blocked address ${address} (private / link-local ranges are not allowed)`,\n      );\n    }\n  }\n}\n\n/** Whether a raw hostname literal is one of the recognised loopback aliases. */\nexport function isLoopbackHost(host: string): boolean {\n  const lowered = host.toLowerCase();\n  return (\n    lowered === \"localhost\" ||\n    lowered === \"127.0.0.1\" ||\n    lowered === \"::1\" ||\n    lowered === \"[::1]\" ||\n    lowered === \"0:0:0:0:0:0:0:1\"\n  );\n}\n\n/**\n * Check whether a resolved IP address is in a range that should never receive\n * workspace credentials. `allowLocalhost` carves out 127.0.0.0/8 and ::1.\n */\nexport function isBlockedIp(address: string, allowLocalhost: boolean): boolean {\n  if (isIPv4(address)) {\n    return isBlockedIpv4(address, allowLocalhost);\n  }\n  if (isIP(address) === 6) {\n    return isBlockedIpv6(address, allowLocalhost);\n  }\n  // Not a recognisable IP literal — fail-closed.\n  return true;\n}\n\nfunction isBlockedIpv4(addr: string, allowLocalhost: boolean): boolean {\n  const parts = addr.split(\".\").map((p) => Number.parseInt(p, 10));\n  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {\n    return true;\n  }\n  const [a, b] = parts;\n  if (a === 0) return true;\n  if (a === 127) return !allowLocalhost;\n  if (a === 10) return true;\n  if (a === 172 && b >= 16 && b <= 31) return true;\n  if (a === 192 && b === 168) return true;\n  if (a === 169 && b === 254) return true;\n  if (a === 100 && b >= 64 && b <= 127) return true;\n  if (a >= 224) return true;\n  return false;\n}\n\nfunction isBlockedIpv6(addr: string, allowLocalhost: boolean): boolean {\n  const lowered = addr.toLowerCase().replace(/^\\[|\\]$/g, \"\");\n\n  if (lowered === \"::\") return true;\n  if (lowered === \"::1\" || lowered === \"0:0:0:0:0:0:0:1\")\n    return !allowLocalhost;\n\n  // IPv4-mapped IPv6: `::ffff:<v4>` may be written in dotted form\n  // (`::ffff:169.254.169.254`) or colon-hex form (`::ffff:a9fe:a9fe`). Both\n  // route to the same destination, so we must normalise before delegating\n  // to the IPv4 blocklist.\n  if (lowered.startsWith(\"::ffff:\")) {\n    const tail = lowered.slice(\"::ffff:\".length);\n    if (isIPv4(tail)) return isBlockedIpv4(tail, allowLocalhost);\n    const hexV4 = hexPairToDottedIpv4(tail);\n    if (hexV4) return isBlockedIpv4(hexV4, allowLocalhost);\n  }\n\n  // Unique Local Addresses (fc00::/7) — `fc` and `fd` only.\n  if (/^f[cd][0-9a-f]{2}:/.test(lowered)) return true;\n  // Link-local fe80::/10 — the first 10 bits are 1111111010, i.e. the\n  // second hex nibble must be 8-b. Matches fe80:..–febf:..\n  if (/^fe[89ab][0-9a-f]:/.test(lowered)) return true;\n  // Multicast ff00::/8.\n  if (lowered.startsWith(\"ff\")) return true;\n  return false;\n}\n\n/**\n * Parse the trailing two hex groups of an IPv4-mapped IPv6 address written\n * in colon-hex form (e.g. `a9fe:a9fe`) into the equivalent dotted-quad IPv4\n * representation (`169.254.169.254`). Returns null for anything else.\n */\nfunction hexPairToDottedIpv4(tail: string): string | null {\n  const match = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);\n  if (!match) return null;\n  const hi = Number.parseInt(match[1], 16);\n  const lo = Number.parseInt(match[2], 16);\n  if (!Number.isFinite(hi) || !Number.isFinite(lo)) return null;\n  if (hi < 0 || hi > 0xffff || lo < 0 || lo > 0xffff) return null;\n  const a = (hi >> 8) & 0xff;\n  const b = hi & 0xff;\n  const c = (lo >> 8) & 0xff;\n  const d = lo & 0xff;\n  return `${a}.${b}.${c}.${d}`;\n}\n\nfunction safeHostname(rawUrl: string): string | null {\n  try {\n    return new URL(rawUrl).hostname.toLowerCase();\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;AAoDA,SAAgB,mBACd,QACA,eACe;CACf,MAAM,oBAAoB,aAAa,cAAc;AACrD,KAAI,CAAC,kBACH,OAAM,IAAI,MACR,0CAA0C,KAAK,UAAU,cAAc,GACxE;AAOH,QAAO;EAAE;EAAmB,cALP,IAAI,KACtB,QAAQ,gBAAgB,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAChE;EAGyC,gBADxC,QAAQ,kBAAkB,QAAQ,IAAI,aAAa;EACK;;;;;;;;;;;;AAuB5D,SAAgB,YACd,QACA,QACa;CACb,IAAI;AACJ,KAAI;AACF,QAAM,IAAI,IAAI,OAAO;SACf;AACN,SAAO;GACL,IAAI;GACJ,QAAQ,wCAAwC;GACjD;;AAGH,KAAI,IAAI,aAAa,WAAW,IAAI,aAAa,SAC/C,QAAO;EACL,IAAI;EACJ,QAAQ,mBAAmB,IAAI,SAAS,mCAAmC;EAC5E;CAGH,MAAM,OAAO,IAAI,SAAS,aAAa;CACvC,MAAM,aAAa,eAAe,KAAK;AAEvC,KAAI,IAAI,aAAa,WAAW,EAAE,cAAc,OAAO,gBACrD,QAAO;EACL,IAAI;EACJ,QAAQ,6EAA6E,OAAO;EAC7F;AAGH,KAAI,SAAS,OAAO,kBAClB,QAAO;EAAE,IAAI;EAAM,sBAAsB;EAAM;EAAK;AAGtD,KAAI,YAAY;AACd,MAAI,CAAC,OAAO,eACV,QAAO;GACL,IAAI;GACJ,QAAQ,+DAA+D;GACxE;AAEH,SAAO;GAAE,IAAI;GAAM,sBAAsB;GAAO;GAAK;;AAGvD,KAAI,OAAO,aAAa,IAAI,KAAK,CAC/B,QAAO;EAAE,IAAI;EAAM,sBAAsB;EAAO;EAAK;AAGvD,QAAO;EACL,IAAI;EACJ,QAAQ,aAAa,KAAK,4DAA4D,OAAO,kBAAkB,iDAAiD,KAAK;EACtK;;;;;;;;;;;;;AAcH,eAAsB,uBACpB,UACA,QACA,WAAoBA,QACL;CACf,MAAM,UAAU,SAAS,aAAa;AAEtC,KAAI,KAAK,QAAQ,EAAE;AACjB,MAAI,YAAY,SAAS,OAAO,eAAe,CAC7C,OAAM,IAAI,MAAM,YAAY,QAAQ,2BAA2B;AAEjE;;AAGF,KAAI,YAAY,aAAa;AAC3B,MAAI,CAAC,OAAO,eACV,OAAM,IAAI,MACR,6DACD;AAEH;;CAGF,IAAI;AACJ,KAAI;AACF,aAAW,MAAMC,SAAO,UAAU,EAAE,KAAK,MAAM,CAAC;UACzC,OAAO;AACd,QAAM,IAAI,MACR,YAAY,SAAS,kCAAkC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GAC9G;;AAGH,KAAI,SAAS,WAAW,EACtB,OAAM,IAAI,MAAM,YAAY,SAAS,4BAA4B;AAGnE,MAAK,MAAM,EAAE,aAAa,SACxB,KAAI,YAAY,SAAS,OAAO,eAAe,CAC7C,OAAM,IAAI,MACR,YAAY,SAAS,+BAA+B,QAAQ,gDAC7D;;;AAMP,SAAgB,eAAe,MAAuB;CACpD,MAAM,UAAU,KAAK,aAAa;AAClC,QACE,YAAY,eACZ,YAAY,eACZ,YAAY,SACZ,YAAY,WACZ,YAAY;;;;;;AAQhB,SAAgB,YAAY,SAAiB,gBAAkC;AAC7E,KAAI,OAAO,QAAQ,CACjB,QAAO,cAAc,SAAS,eAAe;AAE/C,KAAI,KAAK,QAAQ,KAAK,EACpB,QAAO,cAAc,SAAS,eAAe;AAG/C,QAAO;;AAGT,SAAS,cAAc,MAAc,gBAAkC;CACrE,MAAM,QAAQ,KAAK,MAAM,IAAI,CAAC,KAAK,MAAM,OAAO,SAAS,GAAG,GAAG,CAAC;AAChE,KAAI,MAAM,WAAW,KAAK,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,EAAE,CAAC,CAC9D,QAAO;CAET,MAAM,CAAC,GAAG,KAAK;AACf,KAAI,MAAM,EAAG,QAAO;AACpB,KAAI,MAAM,IAAK,QAAO,CAAC;AACvB,KAAI,MAAM,GAAI,QAAO;AACrB,KAAI,MAAM,OAAO,KAAK,MAAM,KAAK,GAAI,QAAO;AAC5C,KAAI,MAAM,OAAO,MAAM,IAAK,QAAO;AACnC,KAAI,MAAM,OAAO,MAAM,IAAK,QAAO;AACnC,KAAI,MAAM,OAAO,KAAK,MAAM,KAAK,IAAK,QAAO;AAC7C,KAAI,KAAK,IAAK,QAAO;AACrB,QAAO;;AAGT,SAAS,cAAc,MAAc,gBAAkC;CACrE,MAAM,UAAU,KAAK,aAAa,CAAC,QAAQ,YAAY,GAAG;AAE1D,KAAI,YAAY,KAAM,QAAO;AAC7B,KAAI,YAAY,SAAS,YAAY,kBACnC,QAAO,CAAC;AAMV,KAAI,QAAQ,WAAW,UAAU,EAAE;EACjC,MAAM,OAAO,QAAQ,MAAM,EAAiB;AAC5C,MAAI,OAAO,KAAK,CAAE,QAAO,cAAc,MAAM,eAAe;EAC5D,MAAM,QAAQ,oBAAoB,KAAK;AACvC,MAAI,MAAO,QAAO,cAAc,OAAO,eAAe;;AAIxD,KAAI,qBAAqB,KAAK,QAAQ,CAAE,QAAO;AAG/C,KAAI,qBAAqB,KAAK,QAAQ,CAAE,QAAO;AAE/C,KAAI,QAAQ,WAAW,KAAK,CAAE,QAAO;AACrC,QAAO;;;;;;;AAQT,SAAS,oBAAoB,MAA6B;CACxD,MAAM,QAAQ,KAAK,MAAM,oCAAoC;AAC7D,KAAI,CAAC,MAAO,QAAO;CACnB,MAAM,KAAK,OAAO,SAAS,MAAM,IAAI,GAAG;CACxC,MAAM,KAAK,OAAO,SAAS,MAAM,IAAI,GAAG;AACxC,KAAI,CAAC,OAAO,SAAS,GAAG,IAAI,CAAC,OAAO,SAAS,GAAG,CAAE,QAAO;AACzD,KAAI,KAAK,KAAK,KAAK,SAAU,KAAK,KAAK,KAAK,MAAQ,QAAO;AAK3D,QAAO,GAJI,MAAM,IAAK,IAIV,GAHF,KAAK,IAGE,GAFN,MAAM,IAAK,IAEA,GADZ,KAAK;;AAIjB,SAAS,aAAa,QAA+B;AACnD,KAAI;AACF,SAAO,IAAI,IAAI,OAAO,CAAC,SAAS,aAAa;SACvC;AACN,SAAO"}

package/dist/connectors/mcp/index.d.ts

@@ -0,0 +1,3 @@
+import { McpHostPolicyConfig } from "./host-policy.js";
+import { McpEndpointConfig } from "./types.js";
+import { AppKitMcpClient, McpConnectAllResult } from "./client.js";

package/dist/connectors/mcp/index.js

@@ -0,0 +1,4 @@
+import { buildMcpHostPolicy } from "./host-policy.js";
+import { AppKitMcpClient } from "./client.js";
+
+export {  };

package/dist/connectors/mcp/types.d.ts

@@ -0,0 +1,16 @@
+//#region src/connectors/mcp/types.d.ts
+/**
+ * Input shape consumed by {@link AppKitMcpClient.connect}. Produced by the
+ * agents plugin from user-facing `HostedTool` declarations (see
+ * `core/agent/tools/hosted-tools.ts`) and accepted directly by the
+ * connector to keep its surface free of agent-layer concepts.
+ */
+interface McpEndpointConfig {
+  /** Stable logical name used as the `mcp.<name>.*` tool prefix and in logs. */
+  name: string;
+  /** Absolute URL (`https://…`) or workspace-relative path (`/api/2.0/mcp/…`). */
+  url: string;
+}
+//#endregion
+export { McpEndpointConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/connectors/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/connectors/mcp/types.ts"],"mappings":";;AAMA;;;;;UAAiB,iBAAA;;EAEf,IAAA;;EAEA,GAAA;AAAA"}

package/dist/context/index.js

@@ -10,5 +10,5 @@ var init_context = __esmMin((() => {
 
 //#endregion
 init_context();
-export { init_context };
+export { getWorkspaceClient, init_context };
 //# sourceMappingURL=index.js.map

package/dist/core/agent/build-toolkit.d.ts

@@ -0,0 +1,2 @@
+import "./types.js";
+import "./tools/define-tool.js";