How exa-labs/exa-mcp-server works
1. What this repo is
- This is an MCP (Model Context Protocol) server for Exa’s search API.
- Its job is to expose Exa capabilities to AI clients as MCP tools over HTTP, with support for both hosted remote access and npm/self-hosted usage.
2. Primary runtime boundary
- The runtime entrypoints live in src/index.ts and src/mcp-handler.ts.
- The server is packaged as a TypeScript Node service and deployed in serverless-style environments, especially Vercel.
- The api/ directory contains HTTP endpoints used by the hosted deployment.
3. HTTP/API surface
- api/mcp.ts is the main MCP transport endpoint.
- api/mcp-oauth.ts and the well-known-* files provide the OAuth and discovery metadata endpoints needed for authenticated MCP clients.
- api/well-known-mcp-config.ts and api/well-known-oauth-protected-resource.ts support client discovery and protected-resource metadata.
4. MCP request handling
- src/mcp-handler.ts appears to be the central dispatcher that translates MCP requests into internal tool calls.
- This is the main control boundary between the MCP protocol layer and Exa-specific search logic.
5. Tooling subsystem
- The actual capabilities are implemented under src/tools/.
- Each file represents a distinct search feature: web search, advanced web search, code search, company research, people search, LinkedIn search, crawling, and deep research flows.
- This is where the repo’s functional architecture lives: MCP tool names map to these modules.
6. Search/data flow
- Client request enters via MCP HTTP endpoint.
- The handler authenticates/validates the request, selects the tool, and calls the relevant module in src/tools/.
- Tool modules call Exa’s search/crawl APIs, normalize the results, and return MCP-friendly output back to the client.
7. Deep research workflow
- deepResearchStart.ts, deepResearchCheck.ts, and deepSearch.ts indicate a multi-step research path rather than one-shot search only.
- This suggests asynchronous or staged workflows for broader research tasks, with polling/checking for completion and then returning consolidated results.
8. External integration points
- The core external dependency is Exa’s API.
- OAuth support implies the server can operate in authenticated contexts, not only via static API keys.
- The README also shows the server is meant to be consumed by AI clients like Cursor, VS Code, Claude Code/Desktop, and others via remote MCP.
9. Shared utility layer
- src/utils/ contains cross-cutting concerns:
- auth.ts for auth and access checks
- errorHandler.ts for consistent failure shaping
- logger.ts for observability
- exaResponseSanitizer.ts for cleaning/normalizing upstream Exa responses
- src/types.ts and src/tools/config.ts provide shared schemas/configuration used by multiple tools.
10. Packaging and deployment
- package.json, tsconfig.json, Dockerfile, and vercel.json show the project is built for both local Node execution and deployment on Vercel.
- server.json, VERCEL_DEPLOYMENT_GUIDE.md, and env.example support operational setup.
- package-lock.json indicates npm-based dependency management.
11. Client-facing configuration assets
- Files like smithery.yaml, smithery-example.json, gemini-extension.json, and .claude-plugin/marketplace.json are distribution/configuration artifacts for MCP marketplaces and client integrations.
- These are not core runtime logic, but they matter for how the server is discovered and installed.
12. Claude Skills are documentation/UX, not runtime code
- The skills/ directory contains reusable “Claude Skills” for specific research workflows: company search, people search, code search, financial reports, papers, and personal sites.
- These are guidance assets that tell an agent how to use the MCP tools effectively; they do not appear to be server execution code.
13. Important architectural boundary
- There is a clean split between:
- Protocol layer: HTTP/MCP/OAuth endpoints in api/
- Application layer: MCP orchestration in src/mcp-handler.ts
- Domain/tool layer: search/research implementations in src/tools/
- Cross-cutting layer: auth, logging, sanitization, and error handling in src/utils/
- That separation is the main thing to capture in an architecture diagram.
14. Repository intent
- The repository is optimized for being a remote, client-agnostic search service rather than a standalone UI.
- Most of the surface area is about exposing Exa’s retrieval capabilities cleanly and safely to LLM clients through MCP, with deployment and client-setup artifacts included alongside the code.
Main entry points: mcp-handler.ts MCP handler · exaResponseSanitizer.ts Sanitizer · webSearch.ts Web search · companyResearch.ts Company research
Components 26
Protocol layer
HTTP endpoints and MCP/OAuth discovery surface
- MCP endpoint · Main MCP transport for hosted access
api/mcp.ts - OAuth endpoint · OAuth flow for authenticated MCP clients
api/mcp-oauth.ts - Discovery config · Client discovery and MCP configuration
api/well-known-mcp-config.ts - Resource metadata · Protected resource metadata for OAuth-aware clients
api/well-known-oauth-protected-resource.ts
Application layer
Runtime entrypoints and MCP request orchestration
- Server entry · Top-level service bootstrap and wiring
src/index.ts - MCP handler · Central protocol-to-tool request router
src/mcp-handler.ts
Tool layer
Exa-backed search and research capabilities
- Web search · Core web retrieval tool
src/tools/webSearch.ts - Advanced search · Richer web search variant
src/tools/webSearchAdvanced.ts - Code search · Code-oriented Exa search capability
src/tools/exaCode.ts - Company research · Company-level synthesis workflow
src/tools/companyResearch.ts - People search · Person discovery and lookup
src/tools/peopleSearch.ts - LinkedIn search · LinkedIn-oriented people/company search
src/tools/linkedInSearch.ts - Crawling · Fetches and normalizes page content
src/tools/crawling.ts - Deep start · Begins staged deep research
src/tools/deepResearchStart.ts - Deep check · Polls staged research status
src/tools/deepResearchCheck.ts - Deep search · Consolidated deep research output
src/tools/deepSearch.ts
Shared utils
Cross-cutting auth, logging, and response shaping
- Auth · Access checks and request authorization
src/utils/auth.ts - Sanitizer · Normalizes upstream Exa responses
src/utils/exaResponseSanitizer.ts - Logger · Structured logging for runtime events
src/utils/logger.ts - Error handler · Consistent error shaping and handling
src/utils/errorHandler.ts - Tool config · Shared tool schemas and constants
src/tools/config.ts - Types · Common TypeScript types and interfaces
src/types.ts
Packaging
Deployment and client distribution assets
- Package · Node package metadata and scripts
package.json - Vercel config · Serverless deployment configuration
vercel.json - Dockerfile · Container packaging for local or hosted runs
Dockerfile - Smithery · Marketplace/install metadata
smithery.yaml
Connections 33
- MCP endpoint → MCP handler: dispatches · HTTP MCP requests enter the dispatcher
- OAuth endpoint → Auth: auth · OAuth flow relies on shared authorization checks
- Discovery config → MCP handler: discovers · Client metadata points to the MCP runtime
- Resource metadata → Auth: protects · Protected-resource metadata supports authenticated access
- Server entry → MCP handler: boots · Server entry initializes the MCP request layer
- MCP handler → Auth: checks · Requests are validated before tool execution
- MCP handler → Error handler: handles · Failures are converted into consistent MCP errors
- MCP handler → Logger: logs · Dispatcher emits runtime observability events
- MCP handler → Tool config: routes · Tool selection and shared tool definitions
- MCP handler → Web search: invokes · Maps MCP tool calls to web search
- MCP handler → Advanced search: invokes · Maps MCP tool calls to advanced search
- MCP handler → Code search: invokes · Maps MCP tool calls to code search
- MCP handler → Company research: invokes · Maps MCP tool calls to company research
- MCP handler → People search: invokes · Maps MCP tool calls to people search
- MCP handler → LinkedIn search: invokes · Maps MCP tool calls to LinkedIn search
- MCP handler → Crawling: invokes · Maps MCP tool calls to crawling
- MCP handler → Deep start: invokes · Starts staged deep research jobs
- Deep start → Deep check: polls · Deep research is checked asynchronously
- Deep check → Deep search: completes · Completed research resolves to final synthesis
- Web search → Sanitizer: normalizes · Search results are cleaned before returning
- Advanced search → Sanitizer: normalizes · Advanced search results are cleaned before returning
- Code search → Sanitizer: normalizes · Code search results are cleaned before returning
- Company research → Sanitizer: normalizes · Research output is cleaned before returning
- People search → Sanitizer: normalizes · People results are cleaned before returning
- LinkedIn search → Sanitizer: normalizes · LinkedIn results are cleaned before returning
- Crawling → Sanitizer: normalizes · Crawl output is cleaned before returning
- Deep search → Sanitizer: normalizes · Deep research output is cleaned before returning
- Web search → Types: uses · Shared result types
- Company research → Types: uses · Shared research types
- Package → Server entry: runs · Package scripts target the Node entrypoint
- Vercel config → MCP endpoint: deploys · Vercel hosts the HTTP MCP surface
- Dockerfile → Server entry: packages · Container build targets the service runtime
- Smithery → Discovery config: publishes · Distribution metadata helps clients discover the server