semantic web search with neural ranking
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.
Unique: Uses Exa's proprietary neural search index with semantic embeddings for ranking instead of BM25 keyword matching; integrates via MCP protocol allowing direct tool invocation from Claude, VS Code, and other MCP-compatible clients without custom API wrappers
vs alternatives: Provides semantic relevance ranking superior to Google Search API's keyword-based results, and integrates natively into AI workflows via MCP without requiring custom HTTP client code
full-page content retrieval with html-to-text conversion
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.
Unique: Implements intelligent boilerplate removal and DOM-aware content extraction (not regex-based) to produce LLM-optimized text; handles encoding detection and preserves semantic structure while removing noise, integrated as a single MCP tool callable from AI assistants
vs alternatives: More reliable than Puppeteer-based crawling for static content (no browser overhead), and produces cleaner output than raw HTML parsing; faster than Readability.js implementations due to server-side optimization
request lifecycle management with timeout and quota handling
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.
Unique: Implements request lifecycle management at the MCP server level, detecting and handling Exa API rate limits and timeouts before returning responses to clients. This enables the server to provide meaningful error messages and prevent cascading failures when the API quota is exhausted.
vs alternatives: More resilient than client-side timeout handling because the server can enforce timeouts uniformly across all clients; better error messages than raw API errors because the server translates Exa API responses into MCP-compatible error formats; enables quota management at the server level rather than requiring each client to implement its own rate limiting.
advanced search with granular filtering and domain constraints
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.
Unique: Exposes Exa's full filter API through MCP tool parameters, allowing declarative specification of domain whitelists/blacklists, date ranges, and content categories without requiring direct API calls; filters are applied server-side before ranking
vs alternatives: More flexible than Google Search API's site: operator; supports simultaneous multi-domain filtering, date ranges, and category constraints in a single query rather than requiring multiple searches
mcp protocol bridging with multi-transport deployment
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.
Unique: Abstracts transport layer from tool logic via separate entry points (stdio vs HTTP/SSE vs serverless); uses Smithery framework for configuration schema and dynamic tool registration, enabling single-codebase deployment across stdio, hosted HTTP, and Vercel serverless without conditional logic
vs alternatives: Eliminates need for custom HTTP wrappers or plugin development; MCP standardization allows same tool to work across Claude, VS Code, Cursor, and future MCP clients without modification
dynamic tool registration with configuration schema
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).
Unique: Uses Smithery's configSchema pattern to define tool availability at deployment time; initializeMcpServer conditionally registers tools based on config, avoiding hardcoded tool lists and enabling tiered feature access without code branching
vs alternatives: More flexible than static tool registration; supports multi-tenant scenarios where different customers see different tool sets, and enables A/B testing of tool availability without code changes
type-safe api request/response handling with validation
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.
Unique: Implements bidirectional validation: validates MCP input parameters against Exa request types before API call, and validates Exa responses against response types before returning to client; uses TypeScript interfaces as single source of truth for API contracts
vs alternatives: Stricter than runtime-only validation (e.g., Zod); catches type errors at compile time and provides IDE autocomplete, reducing debugging time and preventing invalid requests from reaching Exa API
error handling and logging with structured output
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.
Unique: Implements error handling at multiple layers: input validation, API call execution, response parsing; returns structured MCP error responses that distinguish between client errors (invalid input), server errors (API failures), and transient errors (timeouts)
vs alternatives: More granular than generic HTTP error handling; MCP error format allows clients to implement intelligent retry logic based on error type, and structured logging enables faster root cause analysis
+3 more capabilities