Exa MCP Server

Executes semantic web searches using Exa's neural search index, which ranks results by semantic relevance rather than keyword matching. The server translates natural language queries into vector embeddings via the Exa API, retrieves ranked results with metadata (URL, title, snippet, publication date), and returns structured JSON with configurable result limits. This differs from traditional keyword-based search by understanding query intent and returning contextually relevant pages even without exact keyword matches.

Fetches complete page content from a given URL and automatically converts HTML to clean, readable text suitable for LLM consumption. The server handles DOM parsing, removes boilerplate (navigation, ads, scripts), extracts main content, and returns structured text with preserved formatting. This replaces traditional web crawling by providing AI-ready content without manual parsing or regex-based extraction.

Manages the complete lifecycle of Exa API requests, including timeout handling, rate limit detection, and quota enforcement. The server monitors request duration, detects Exa API rate limit responses (429 status), and returns meaningful error messages to clients. This enables graceful degradation under load and prevents clients from overwhelming the Exa API with requests.

Provides fine-grained control over search parameters including domain whitelisting/blacklisting, date range filtering, content category filtering, and result type specification (news, research papers, etc.). The server accepts structured filter objects and translates them into Exa API query parameters, enabling researchers to narrow results to specific sources, time periods, or content types. This is an opt-in tool for use cases requiring precision over breadth.

Implements the Model Context Protocol (MCP) specification to expose Exa tools as callable functions within MCP-compatible clients (Claude, VS Code, Cursor, etc.). The server supports multiple transport mechanisms: stdio for local deployment, HTTP/SSE for hosted endpoints, and serverless functions (Vercel). A single codebase (src/mcp-handler.ts) defines tool schemas and logic; deployment-specific entry points (src/index.ts for Smithery, api/mcp.ts for Vercel) adapt the core to different transports without code duplication.

Allows runtime configuration of which tools are exposed and how they behave through a configSchema defined in src/index.ts. The initializeMcpServer function in src/mcp-handler.ts reads configuration and conditionally registers tools (web_search_exa, web_fetch_exa, web_search_advanced_exa) with their respective input schemas. This enables deployment-time tool selection without code changes, supporting different use cases (e.g., disabling advanced search for free tier users).

Defines strict TypeScript interfaces in src/types.ts for all Exa API requests and responses, ensuring compile-time type safety and runtime validation. The server validates incoming MCP tool parameters against these types before forwarding to Exa API, and validates Exa responses before returning to clients. This prevents type mismatches, malformed requests, and unexpected response structures from propagating to downstream consumers.

Implements comprehensive error handling across the request lifecycle: validates input parameters, catches Exa API errors, handles network timeouts, and returns structured error responses to MCP clients. The server logs errors with context (request ID, tool name, parameters) to aid debugging. Error responses follow MCP error format, allowing clients to distinguish between invalid input, API failures, and transient errors.

Provides a research orchestrator pattern (documented in SKILL.md) that chains multiple search and fetch operations to answer complex research questions. The orchestrator can execute semantic searches, fetch full content from top results, filter by domain/date, and synthesize findings into coherent answers. This enables AI agents to conduct multi-step research without explicit step-by-step prompting, automating common research patterns.

Abstracts the transport layer from tool logic, enabling deployment across stdio (local), HTTP/SSE (hosted), and serverless (Vercel) without code duplication. The core tool logic in src/mcp-handler.ts is transport-agnostic; deployment-specific entry points (src/index.ts for Smithery, api/mcp.ts for Vercel) handle transport details. This allows a single codebase to serve local development, cloud-hosted instances, and serverless functions.

Manages Exa API authentication through environment variables (EXA_API_KEY), supporting both local development and cloud deployments. The server reads the API key at startup and includes it in all Exa API requests. This approach avoids hardcoding credentials and supports standard deployment patterns (environment variable injection in Docker, Vercel, etc.).