exa-mcp-server

Executes semantic web searches through the Model Context Protocol by translating natural language queries into Exa API calls, returning ranked results with relevance scoring. The server implements MCP's tool-calling interface, allowing AI clients (Claude, VS Code, Cursor) to invoke web_search_exa as a native tool with schema-based parameter validation. Results include URLs, titles, snippets, and metadata without requiring the client to manage API authentication directly.

Fetches complete HTML content from a given URL and returns cleaned, structured text via the web_fetch_exa tool. The server handles HTML parsing, boilerplate removal (navigation, ads, footers), and text extraction, returning only the main content body. This replaces the deprecated crawling_exa tool and integrates with Exa's content cleaning pipeline, allowing AI clients to retrieve article text, documentation, or page content without managing web scraping complexity.

Implements consistent error handling across stdio, HTTP/SSE, and serverless transports, translating internal errors into MCP-compliant error responses that clients can understand. The server catches API errors, network failures, and validation errors, and returns structured error messages with context. This enables clients to handle failures gracefully without crashing, and provides visibility into what went wrong (e.g., API rate limit, invalid query, network timeout).

Leverages Exa's semantic search engine to rank results by relevance to the query, returning results ordered by a relevance score. The server does not implement its own ranking; it delegates to Exa's neural search model, which understands semantic meaning and returns results in order of relevance. Clients receive results pre-ranked and can use the score to filter or prioritize results in their workflows.

Distributes the exa-mcp-server as an npm package, allowing developers to install it locally via npm install exa-mcp-server and run it as a local MCP server. The package includes pre-built binaries and configuration, enabling quick setup without cloning the repository or building from source. This is the simplest deployment method for local development and testing.

Provides a Dockerfile and Docker configuration enabling the exa-mcp-server to be containerized and deployed in Docker environments, Kubernetes clusters, or any container orchestration platform. The container includes all dependencies and can be deployed with a single docker run command, making it portable across different infrastructure environments. This is ideal for teams deploying MCP servers in containerized environments.

Provides fine-grained control over web search parameters through the web_search_advanced_exa tool, allowing clients to filter by domain whitelist/blacklist, publication date ranges, content categories, and other metadata. The server translates these filter parameters into Exa API query options, enabling researchers and agents to narrow search scope without post-processing results. This is an opt-in tool for power users who need more control than the basic semantic search.

Implements the Model Context Protocol (MCP) as a standardized server that can be deployed across multiple transport layers (stdio for local, HTTP/SSE for hosted, serverless for Vercel) from a single codebase. The server uses the McpServer class to register tools, handle tool invocation requests, and manage the MCP lifecycle. This architecture allows the same tool definitions and logic to work across Claude Desktop, VS Code, Cursor, and custom MCP clients without modification.

Defines and validates tool parameters using JSON Schema, ensuring type safety and preventing invalid requests from reaching the Exa API. The server uses src/types.ts to define data contracts for API requests and responses, and the MCP protocol enforces schema validation at the client level before tool invocation. This prevents malformed queries and provides clear error messages to clients when parameters don't match the schema.

Allows runtime selection of which tools to expose through the initializeMcpServer function, which reads configuration and registers only the specified tools with the McpServer instance. The server supports enabling/disabling tools via environment variables or configuration files, enabling different deployments to expose different tool sets without code changes. This is particularly useful for managing deprecated tools (crawling_exa) alongside newer ones (web_fetch_exa).

Abstracts MCP protocol details to provide a unified interface that works across Claude, VS Code, Cursor, and custom MCP clients. The server implements the MCP specification, handling client-specific quirks and protocol variations transparently. Clients connect via stdio (local), HTTP/SSE (hosted), or other transports, and the server normalizes requests and responses to ensure consistent behavior across all clients.

Supports deployment as a Vercel serverless function (api/mcp.ts) or Docker container with HTTP/SSE transport, enabling hosted MCP server deployments without managing long-running processes. The server exposes an HTTP endpoint that clients can connect to via SSE (Server-Sent Events), allowing remote access to tools. This complements the stdio transport for local deployments, providing a unified codebase that works across local and hosted scenarios.

Provides a research orchestrator pattern (documented in SKILL.md) that allows agents to compose multiple search and fetch operations into multi-step research workflows. The server enables agents to chain web_search_exa → web_fetch_exa operations, using search results to inform subsequent fetches, and supports more complex research patterns like comparing multiple sources or synthesizing information across pages. This is implemented through the MCP tool interface, allowing any MCP client to orchestrate research workflows.

Abstracts Exa API authentication by accepting an API key at server initialization and managing all downstream API calls transparently. Clients do not need to provide or manage API keys; they simply invoke tools through MCP, and the server handles authentication with the Exa API. This pattern supports multiple authentication methods (environment variables, configuration files, Smithery config) depending on deployment method, centralizing credential management.