Exa MCP Server

Executes semantic web searches via the Exa AI API using neural embeddings to rank results by relevance rather than keyword matching. The server translates MCP tool calls into Exa API requests, handles authentication via API keys, and returns ranked search results with titles, URLs, and optional content snippets. Results are optimized for AI consumption with relevance scores computed server-side.

Fetches complete HTML content from a given URL and automatically cleans it into readable text by removing boilerplate (navigation, ads, scripts), extracting main content, and preserving semantic structure. The web_fetch_exa tool sends the URL to Exa's backend, which applies content extraction heuristics and returns cleaned markdown or plain text optimized for LLM consumption. This replaces the deprecated crawling_exa tool with improved extraction logic.

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 web search via the web_search_advanced_exa tool, allowing filtering by domain whitelist/blacklist, publication date ranges, content categories, and result type (news, research papers, etc.). The tool accepts structured filter parameters and passes them to Exa's API, which applies these constraints before neural ranking. This enables precision research workflows where broad semantic search needs to be narrowed by metadata.

Implements the Model Context Protocol (MCP) specification to expose Exa search tools as standardized resources that any MCP-compatible client can invoke. The server (src/mcp-handler.ts) registers tools with the McpServer instance, defines JSON schemas for tool inputs/outputs, and handles tool execution lifecycle. Supports both stdio (local) and HTTP/SSE (hosted) transports, enabling deployment flexibility. Clients like Claude Desktop, VS Code, and Cursor automatically discover and call these tools without custom integration code.

Allows dynamic selection of which tools to expose via environment variables or configuration schema, enabling different deployments to activate different tool sets. The initializeMcpServer function (src/mcp-handler.ts) conditionally registers tools based on configuration, and the configSchema (src/index.ts) defines which tools are available. This enables a single codebase to support multiple deployment profiles: basic search-only, search+fetch, or advanced search with all filters.

Defines strict TypeScript types and JSON schemas for all Exa API requests and responses (src/types.ts), ensuring type safety across the server and validating client inputs against expected schemas. Tool inputs are validated against MCP schemas before being sent to Exa's API, and responses are typed to prevent runtime errors. This enables early error detection and provides IDE autocomplete for developers extending the server.

Supports deployment across multiple transport and hosting options from a single codebase: stdio for local Claude Desktop/VS Code integration, HTTP/SSE for hosted endpoints, Docker for containerized deployments, and Vercel serverless for scalable cloud hosting. Different entry points (src/index.ts for stdio, api/mcp.ts for Vercel) adapt the core MCP logic to each transport without code duplication. This enables flexible deployment strategies based on infrastructure and scale requirements.

Implements structured error handling and logging throughout the server, capturing errors from Exa API calls, MCP protocol violations, and tool execution failures. Errors are logged with context (tool name, request parameters, error code) and returned to clients with meaningful messages. This enables debugging of integration issues and monitoring of server health in production deployments.

Provides a modular architecture for adding new tools to the MCP server without modifying core protocol logic. The initializeMcpServer function (src/mcp-handler.ts) registers tools by mapping tool names to handler functions and defining input/output schemas. Developers can add new tools by implementing a handler function, defining its schema, and registering it with the McpServer instance. This enables teams to extend the server with custom search capabilities or domain-specific tools.

Manages Exa API authentication via environment variables (EXA_API_KEY), ensuring credentials are not hardcoded or exposed in logs. The server reads the API key at startup, validates it, and uses it for all Exa API requests. Error messages and logs are sanitized to avoid leaking credentials. This enables secure deployment across different environments (local, staging, production) without credential exposure.