feat(mcp): add direct Exa API integration to bypass slow mcp.exa.ai (#2021)

* feat(mcp): add direct Exa API integration to bypass slow mcp.exa.ai

Intercepts calls to mcp.exa.ai and routes them directly to api.exa.ai,
eliminating the slow hosted MCP server (~3-12s latency) while keeping
the same user configuration.

- Add exaDirect.ts module with direct API client
- Intercept tool listing in tools.ts to return hardcoded definitions
- Intercept tool calls in httpClient.ts to use direct API
- Add EXA_API_KEY config for authentication

No user config changes needed - existing MCP_SERVERS with mcp.exa.ai
continue to work transparently.

* Add scroll to metadata output in ToolUpdate

Wrapped the metadata <pre> block with custom scrollbar, max height, and vertical overflow for better readability when displaying large metadata content.

* fix(mcp): bypass mcp.exa.ai in health check, security/leak fixes

- Add Exa bypass to /api/mcp/health endpoint for instant response
- Support x-api-key header for API key (preferred over URL param)
- Fix event listener leak by adding { once: true }
- Remove query logging to avoid PII leakage

.env

@@ -132,6 +132,8 @@ ALLOW_IFRAME=true # Allow the app to be embedded in an iframe
 MCP_SERVERS=
 # When true, forward the logged-in user's Hugging Face access token
 MCP_FORWARD_HF_USER_TOKEN=
+# Exa API key for direct API calls (bypasses slow mcp.exa.ai endpoint)
+EXA_API_KEY=
 ENABLE_DATA_EXPORT=true
 
 ### Rate limits ### 

src/lib/components/chat/ToolUpdate.svelte

@@ -230,7 +230,8 @@
 										{/if}
 
 										{#if parsedOutput.metadata.length > 0}
-											<pre class="whitespace-pre-wrap break-all font-mono text-xs">{formatValue(
+											<pre
+												class="scrollbar-custom max-h-60 overflow-y-auto whitespace-pre-wrap break-all font-mono text-xs">{formatValue(
 													Object.fromEntries(parsedOutput.metadata)
 												)}</pre>
 										{/if}

src/lib/server/config.ts

@@ -158,7 +158,8 @@ type ExtraConfigKeys =
 	| "METRICS_ENABLED"
 	| "METRICS_PORT"
 	| "MCP_SERVERS"
-	| "MCP_FORWARD_HF_USER_TOKEN";
+	| "MCP_FORWARD_HF_USER_TOKEN"
+	| "EXA_API_KEY";
 
 type ConfigProxy = ConfigManager & { [K in ConfigKey | ExtraConfigKeys]: string };
 

src/lib/server/mcp/exaDirect.ts

@@ -0,0 +1,255 @@
+/**
+ * Direct Exa API integration - bypasses mcp.exa.ai for faster responses
+ *
+ * Instead of: MCP protocol → mcp.exa.ai (slow) → Exa API
+ * We do:      Direct call → api.exa.ai (fast)
+ */
+
+import { config } from "$lib/server/config";
+import type { McpServerConfig, McpToolTextResponse } from "./httpClient";
+
+const EXA_API_BASE = "https://api.exa.ai";
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// Tool definitions matching what Exa MCP server exposes
+type ListedTool = {
+	name: string;
+	inputSchema?: Record<string, unknown>;
+	description?: string;
+};
+
+/**
+ * Detect if a server is the Exa MCP server
+ */
+export function isExaServer(server: McpServerConfig): boolean {
+	try {
+		const url = new URL(server.url);
+		return url.hostname.toLowerCase() === "mcp.exa.ai";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Extract Exa API key from server headers, URL, or config
+ * Priority: headers["x-api-key"] > URL param > EXA_API_KEY env var
+ */
+export function getExaApiKey(server: McpServerConfig): string | undefined {
+	// First check headers (preferred - avoids key in URL logs)
+	const headerKey = server.headers?.["x-api-key"];
+	if (headerKey && headerKey.trim().length > 0) {
+		return headerKey;
+	}
+
+	// Check URL params (e.g., ?exaApiKey=xxx) - discouraged but supported
+	try {
+		const url = new URL(server.url);
+		const urlKey = url.searchParams.get("exaApiKey");
+		if (urlKey) return urlKey;
+	} catch {}
+
+	// Fall back to config
+	const configKey = config.EXA_API_KEY;
+	if (configKey && configKey.trim().length > 0) {
+		return configKey;
+	}
+
+	return undefined;
+}
+
+/**
+ * Hardcoded tool definitions for Exa (matches what mcp.exa.ai returns)
+ */
+export function getExaToolDefinitions(): ListedTool[] {
+	return [
+		{
+			name: "web_search_exa",
+			description:
+				"Search the web using Exa AI. Returns relevant web pages with titles, URLs, and content snippets.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "The search query",
+					},
+					numResults: {
+						type: "number",
+						description: "Number of results to return (default: 10, max: 100)",
+					},
+					type: {
+						type: "string",
+						enum: ["auto", "neural", "keyword"],
+						description: "Search type (default: auto)",
+					},
+					includeDomains: {
+						type: "array",
+						items: { type: "string" },
+						description: "Only include results from these domains",
+					},
+					excludeDomains: {
+						type: "array",
+						items: { type: "string" },
+						description: "Exclude results from these domains",
+					},
+				},
+				required: ["query"],
+			},
+		},
+		{
+			name: "get_code_context_exa",
+			description:
+				"Search for code snippets, documentation, and programming resources. Optimized for finding code examples and technical documentation.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "The code or programming-related search query",
+					},
+					numResults: {
+						type: "number",
+						description: "Number of results to return (default: 10)",
+					},
+				},
+				required: ["query"],
+			},
+		},
+	];
+}
+
+interface ExaSearchResult {
+	title: string;
+	url: string;
+	id: string;
+	score?: number;
+	publishedDate?: string;
+	author?: string;
+	text?: string;
+	highlights?: string[];
+	highlightScores?: number[];
+	summary?: string;
+}
+
+interface ExaSearchResponse {
+	requestId: string;
+	resolvedSearchType: string;
+	results: ExaSearchResult[];
+	costDollars?: Record<string, number>;
+}
+
+/**
+ * Format Exa search results as human-readable text
+ */
+function formatSearchResultsAsText(results: ExaSearchResult[]): string {
+	if (results.length === 0) {
+		return "No results found.";
+	}
+
+	return results
+		.map((result, index) => {
+			const parts = [`${index + 1}. ${result.title}`, `   URL: ${result.url}`];
+
+			if (result.publishedDate) {
+				parts.push(`   Published: ${result.publishedDate}`);
+			}
+
+			if (result.text) {
+				parts.push(`   ${result.text}`);
+			} else if (result.highlights && result.highlights.length > 0) {
+				parts.push(`   ${result.highlights.join(" ... ")}`);
+			}
+
+			return parts.join("\n");
+		})
+		.join("\n\n");
+}
+
+/**
+ * Call Exa API directly (bypasses MCP protocol)
+ */
+export async function callExaDirectApi(
+	tool: string,
+	args: Record<string, unknown>,
+	apiKey: string,
+	options?: { signal?: AbortSignal; timeoutMs?: number }
+): Promise<McpToolTextResponse> {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+	// Both tools use the /search endpoint
+	if (tool !== "web_search_exa" && tool !== "get_code_context_exa") {
+		throw new Error(`Unsupported Exa tool: ${tool}`);
+	}
+
+	const query = args.query as string;
+	if (!query || typeof query !== "string") {
+		throw new Error("Missing required parameter: query");
+	}
+
+	// Build request body - pass through all args, ensure query exists and request text content
+	const requestBody: Record<string, unknown> = {
+		...args,
+		query,
+		// Required to get page text content, not just metadata
+		contents: {
+			text: true,
+		},
+	};
+
+	// Create abort controller for timeout
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+	// Combine with external signal if provided
+	if (options?.signal) {
+		options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+	}
+
+	const startTime = Date.now();
+
+	try {
+		const response = await fetch(`${EXA_API_BASE}/search`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"x-api-key": apiKey,
+			},
+			body: JSON.stringify(requestBody),
+			signal: controller.signal,
+		});
+
+		clearTimeout(timeoutId);
+
+		if (!response.ok) {
+			const errorText = await response.text();
+			console.log(`[EXA DIRECT] API error: ${response.status} - ${errorText}`);
+			throw new Error(`Exa API error: ${response.status} ${response.statusText} - ${errorText}`);
+		}
+
+		const data = (await response.json()) as ExaSearchResponse;
+		const duration = Date.now() - startTime;
+		console.log(
+			`[EXA DIRECT] Success in ${duration}ms - ${data.results.length} results (type: ${data.resolvedSearchType})`
+		);
+
+		// Format response to match MCP tool response format
+		const text = formatSearchResultsAsText(data.results);
+
+		return {
+			text,
+			structured: data.results,
+			content: [{ type: "text", text }],
+		};
+	} catch (err) {
+		clearTimeout(timeoutId);
+		const duration = Date.now() - startTime;
+
+		if (err instanceof Error && err.name === "AbortError") {
+			console.log(`[EXA DIRECT] Timeout after ${duration}ms`);
+			throw new Error(`Exa API request timed out after ${timeoutMs}ms`);
+		}
+
+		console.log(`[EXA DIRECT] Failed after ${duration}ms: ${err}`);
+		throw err;
+	}
+}

src/lib/server/mcp/httpClient.ts

@@ -1,5 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client";
 import { getClient, evictFromPool } from "./clientPool";
+import { isExaServer, getExaApiKey, callExaDirectApi } from "./exaDirect";
 
 function isConnectionClosedError(err: unknown): boolean {
 	const message = err instanceof Error ? err.message : String(err);
@@ -32,6 +33,21 @@ export async function callMcpTool(
 		client,
 	}: { timeoutMs?: number; signal?: AbortSignal; client?: Client } = {}
 ): Promise<McpToolTextResponse> {
+	// Bypass MCP protocol for Exa - call direct API
+	if (isExaServer(server)) {
+		const apiKey = getExaApiKey(server);
+		if (!apiKey) {
+			throw new Error(
+				"Exa API key not found. Set EXA_API_KEY environment variable or add ?exaApiKey= to the server URL."
+			);
+		}
+		const normalizedArgs =
+			typeof args === "object" && args !== null && !Array.isArray(args)
+				? (args as Record<string, unknown>)
+				: {};
+		return callExaDirectApi(tool, normalizedArgs, apiKey, { signal, timeoutMs });
+	}
+
 	const normalizedArgs =
 		typeof args === "object" && args !== null && !Array.isArray(args)
 			? (args as Record<string, unknown>)

src/lib/server/mcp/tools.ts

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import type { McpServerConfig } from "./httpClient";
 import { logger } from "$lib/server/logger";
+import { isExaServer, getExaToolDefinitions } from "./exaDirect";
 // use console.* for lightweight diagnostics in production logs
 
 export type OpenAiTool = {
@@ -65,6 +66,16 @@ async function listServerTools(
 	server: McpServerConfig,
 	opts: { signal?: AbortSignal } = {}
 ): Promise<ListedTool[]> {
+	// Bypass MCP protocol for Exa - return hardcoded tool definitions
+	if (isExaServer(server)) {
+		const tools = getExaToolDefinitions();
+		logger.debug(
+			{ server: server.name, count: tools.length, toolNames: tools.map((t) => t.name) },
+			"[mcp] using direct Exa tool definitions (bypassing MCP)"
+		);
+		return tools;
+	}
+
 	const url = new URL(server.url);
 	const client = new Client({ name: "chat-ui-mcp", version: "0.1.0" });
 	try {

src/routes/api/mcp/health/+server.ts

@@ -7,6 +7,7 @@ import { logger } from "$lib/server/logger";
 import type { RequestHandler } from "./$types";
 import { isValidUrl } from "$lib/server/urlSafety";
 import { isStrictHfMcpLogin, hasNonEmptyToken } from "$lib/server/mcp/hf";
+import { isExaServer, getExaToolDefinitions } from "$lib/server/mcp/exaDirect";
 
 interface HealthCheckRequest {
 	url: string;
@@ -50,6 +51,24 @@ export const POST: RequestHandler = async ({ request, locals }) => {
 			);
 		}
 
+		// Bypass MCP protocol for Exa - return hardcoded tool definitions immediately
+		if (isExaServer({ name: "", url, headers: {} })) {
+			const tools = getExaToolDefinitions();
+			const response: HealthCheckResponse = {
+				ready: true,
+				tools: tools.map((tool) => ({
+					name: tool.name,
+					description: tool.description,
+					inputSchema: tool.inputSchema,
+				})),
+				authRequired: false,
+			};
+			return new Response(JSON.stringify(response), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}
+
 		const baseUrl = new URL(url);
 
 		// Minimal header handling