exa-mcp-server

Executes semantic web searches through the Model Context Protocol by translating natural language queries into Exa API requests, returning ranked results with relevance scoring. The server implements the MCP tool registry pattern where web_search_exa is registered as a callable tool with standardized input/output schemas, allowing Claude, VS Code, Cursor, and other MCP-compatible clients to invoke searches without direct API knowledge. Results include title, URL, snippet, and relevance metadata optimized for LLM context windows.

Retrieves full HTML content from specified URLs and returns cleaned, structured text optimized for LLM consumption. The web_fetch_exa tool uses Exa's content extraction pipeline to strip boilerplate (navigation, ads, scripts), extract main content, and format it as readable text with preserved structure. This replaces the deprecated crawling_exa tool and integrates with the MCP tool registry to allow AI clients to fetch and analyze specific web pages without managing HTML parsing or cleaning logic.

Manages Exa API authentication by accepting an API key through environment variables (EXA_API_KEY) and including it in all requests to the Exa API. The server validates that the API key is present at startup and includes it in request headers or query parameters as required by the Exa API. Credentials are never logged or exposed in error messages, protecting sensitive data. The authentication mechanism is transparent to MCP clients, which do not need to provide credentials directly.

Provides a research orchestration framework (documented in SKILL.md) that enables AI agents to compose multiple search and fetch operations into complex research workflows. The framework allows agents to chain searches (e.g., search for topic, fetch top results, search for related topics) and coordinate results across multiple tool calls. This is implemented through the standard MCP tool interface, allowing agents to call tools sequentially and use results from one call as input to the next. The framework is agent-agnostic, working with any MCP-compatible agent that supports tool calling.

Supports Docker-based deployment through a Dockerfile that packages the MCP server with all dependencies, enabling consistent deployment across environments. The Docker image includes Node.js runtime, server code, and dependencies, and can be deployed to any Docker-compatible platform (Kubernetes, Docker Compose, cloud container services). The image exposes the MCP server via HTTP/SSE transport, making it accessible to remote clients. Environment variables (including EXA_API_KEY) are passed at container runtime, enabling credential management without rebuilding images.

Enables serverless deployment on Vercel through an HTTP/SSE transport adapter (api/mcp.ts) that translates HTTP requests into MCP protocol messages. The adapter handles incoming HTTP requests, parses them as MCP tool calls, executes the tools, and returns results as HTTP responses. This allows the MCP server to run as a Vercel serverless function, scaling automatically based on demand without managing infrastructure. The same core tool logic (src/mcp-handler.ts) is reused across stdio and serverless deployments.

Executes semantic web searches with fine-grained control over result filtering through the web_search_advanced_exa tool, supporting domain whitelisting/blacklisting, date range filtering, content category filtering, and result ranking customization. The tool accepts structured filter parameters that are translated into Exa API query constraints, enabling researchers and agents to narrow search scope to specific sources, time periods, or content types. Results are returned with full metadata including publication date, domain, and category tags.

Implements the Model Context Protocol's tool registry pattern through the initializeMcpServer function in src/mcp-handler.ts, which dynamically registers web_search_exa, web_fetch_exa, and web_search_advanced_exa as callable tools with standardized JSON schemas. Each tool is registered with input parameter definitions, descriptions, and execution handlers that translate MCP tool calls into Exa API requests. The registry supports configuration-driven tool selection, allowing deployments to enable/disable tools based on environment variables or deployment context.

Supports deployment across multiple transport mechanisms (stdio for local development, HTTP/SSE for hosted endpoints, serverless for Vercel) from a single codebase through modular architecture. The entry point src/index.ts handles Smithery-based deployments with stdio transport, while api/mcp.ts provides HTTP/SSE transport for serverless environments. The core MCP handler logic in src/mcp-handler.ts is transport-agnostic, allowing the same tool implementations to work across deployment targets. Configuration is managed through environment variables and deployment-specific entry points.

Implements strict TypeScript type definitions in src/types.ts for all Exa API requests and responses, ensuring compile-time type safety and runtime validation. The type system defines contracts for search queries, fetch requests, filter parameters, and result objects, preventing type mismatches between MCP tool invocations and Exa API calls. Type definitions are used for both client-side validation (before sending to Exa) and server-side response parsing, reducing runtime errors and improving IDE autocomplete for developers extending the server.

Implements structured error handling and logging throughout the server to capture API failures, validation errors, and request/response issues. The error handling strategy includes try-catch blocks around Exa API calls, validation of MCP tool parameters, and structured logging of request/response data for debugging. Errors are propagated to MCP clients with descriptive messages, enabling clients to handle failures gracefully. Logging infrastructure supports different verbosity levels and can be configured via environment variables for development vs. production deployments.

Allows deployment-time configuration of which tools are enabled and how they behave through environment variables and configuration schemas. The configSchema in src/index.ts defines available configuration options, and the initializeMcpServer function uses these settings to selectively register tools and customize their behavior. This enables different deployments (e.g., research-focused vs. general-purpose) to expose different tool sets without code changes. Configuration is validated at server startup, ensuring invalid configurations are caught early.

Implements the Model Context Protocol specification to ensure compatibility with MCP-capable clients including Claude Desktop, VS Code with MCP extension, Cursor, and custom MCP clients. The server exposes tools through the MCP tool discovery mechanism, allowing clients to query available tools and their schemas at connection time. Tool schemas include parameter definitions, descriptions, and examples, enabling clients to provide autocomplete and validation. The server handles MCP protocol messages (tool calls, results, errors) according to the specification.

Manages the complete request lifecycle from MCP tool invocation through Exa API call to result formatting and return to the client. The data flow begins with the client sending an MCP tool call message, which the server parses and validates against the tool schema. The server then constructs an Exa API request with the validated parameters, handles authentication, sends the request, parses the response, formats results for the MCP client, and returns the result message. Error handling is integrated throughout the lifecycle, with failures at any stage being caught and returned as MCP error messages.