# exa-labs/exa-mcp-server architecture

> Architecture diagram of the GitHub repository exa-labs/exa-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exa-labs/exa-mcp-server
- Repository: https://github.com/exa-labs/exa-mcp-server

## Overview

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: [`src/mcp-handler.ts`](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts) (MCP handler), [`src/utils/exaResponseSanitizer.ts`](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/exaResponseSanitizer.ts) (Sanitizer), [`src/tools/webSearch.ts`](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts) (Web search), [`src/tools/companyResearch.ts`](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/companyResearch.ts) (Company research)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol layer"]
  node_api_mcp["MCP endpoint<br/>http endpoint<br/>[mcp.ts]"]
  node_api_oauth["OAuth endpoint<br/>[mcp-oauth.ts]"]
  node_api_config["Discovery config<br/>well-known metadata"]
  node_api_resource["Resource metadata<br/>well-known metadata"]
end

subgraph group_app["Application layer"]
  node_src_index(("Server entry<br/>node runtime<br/>[index.ts]"))
  node_mcp_handler["MCP handler<br/>request dispatcher<br/>[mcp-handler.ts]"]
end

subgraph group_tools["Tool layer"]
  node_web_search{{"Web search<br/>search tool<br/>[webSearch.ts]"}}
  node_web_search_adv{{"Advanced search<br/>search tool"}}
  node_code_search{{"Code search<br/>search tool<br/>[exaCode.ts]"}}
  node_company_research{{"Company research<br/>research tool<br/>[companyResearch.ts]"}}
  node_people_search{{"People search<br/>search tool<br/>[peopleSearch.ts]"}}
  node_linkedin_search{{"LinkedIn search<br/>search tool<br/>[linkedInSearch.ts]"}}
  node_crawling{{"Crawling<br/>crawl tool<br/>[crawling.ts]"}}
  node_deep_start{{"Deep start<br/>workflow step"}}
  node_deep_check{{"Deep check<br/>workflow step"}}
  node_deep_search{{"Deep search<br/>workflow step<br/>[deepSearch.ts]"}}
end

subgraph group_utils["Shared utils"]
  node_auth_utils["Auth<br/>security helper<br/>[auth.ts]"]
  node_sanitizer["Sanitizer<br/>response helper"]
  node_logger["Logger<br/>observability helper<br/>[logger.ts]"]
  node_errors["Error handler<br/>failure helper<br/>[errorHandler.ts]"]
  node_tool_config["Tool config<br/>shared config<br/>[config.ts]"]
  node_types["Types<br/>[types.ts]"]
end

subgraph group_ops["Packaging"]
  node_package_json["Package<br/>build config<br/>[package.json]"]
  node_vercel_json["Vercel config<br/>deploy config<br/>[vercel.json]"]
  node_dockerfile["Dockerfile<br/>deploy config"]
  node_smithery["Smithery<br/>distribution config<br/>[smithery.yaml]"]
end

node_api_mcp -->|"dispatches"| node_mcp_handler
node_api_oauth -->|"auth"| node_auth_utils
node_api_config -.->|"discovers"| node_mcp_handler
node_api_resource -.->|"protects"| node_auth_utils
node_src_index -->|"boots"| node_mcp_handler
node_mcp_handler -->|"checks"| node_auth_utils
node_mcp_handler -->|"handles"| node_errors
node_mcp_handler -.->|"logs"| node_logger
node_mcp_handler -->|"routes"| node_tool_config
node_mcp_handler -->|"invokes"| node_web_search
node_mcp_handler -->|"invokes"| node_web_search_adv
node_mcp_handler -->|"invokes"| node_code_search
node_mcp_handler -->|"invokes"| node_company_research
node_mcp_handler -->|"invokes"| node_people_search
node_mcp_handler -->|"invokes"| node_linkedin_search
node_mcp_handler -->|"invokes"| node_crawling
node_mcp_handler -->|"invokes"| node_deep_start
node_deep_start -->|"polls"| node_deep_check
node_deep_check -->|"completes"| node_deep_search
node_web_search -->|"normalizes"| node_sanitizer
node_web_search_adv -->|"normalizes"| node_sanitizer
node_code_search -->|"normalizes"| node_sanitizer
node_company_research -->|"normalizes"| node_sanitizer
node_people_search -->|"normalizes"| node_sanitizer
node_linkedin_search -->|"normalizes"| node_sanitizer
node_crawling -->|"normalizes"| node_sanitizer
node_deep_search -->|"normalizes"| node_sanitizer
node_web_search -.->|"uses"| node_types
node_company_research -.->|"uses"| node_types
node_package_json -.->|"runs"| node_src_index
node_vercel_json -.->|"deploys"| node_api_mcp
node_dockerfile -.->|"packages"| node_src_index
node_smithery -.->|"publishes"| node_api_config

click node_api_mcp "https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts"
click node_api_oauth "https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp-oauth.ts"
click node_api_config "https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts"
click node_api_resource "https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-oauth-protected-resource.ts"
click node_src_index "https://github.com/exa-labs/exa-mcp-server/blob/main/src/index.ts"
click node_mcp_handler "https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts"
click node_web_search "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts"
click node_web_search_adv "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts"
click node_code_search "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/exaCode.ts"
click node_company_research "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/companyResearch.ts"
click node_people_search "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/peopleSearch.ts"
click node_linkedin_search "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/linkedInSearch.ts"
click node_crawling "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/crawling.ts"
click node_deep_start "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepResearchStart.ts"
click node_deep_check "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepResearchCheck.ts"
click node_deep_search "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts"
click node_auth_utils "https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/auth.ts"
click node_sanitizer "https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/exaResponseSanitizer.ts"
click node_logger "https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/logger.ts"
click node_errors "https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/errorHandler.ts"
click node_tool_config "https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/config.ts"
click node_types "https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts"
click node_package_json "https://github.com/exa-labs/exa-mcp-server/blob/main/package.json"
click node_vercel_json "https://github.com/exa-labs/exa-mcp-server/blob/main/vercel.json"
click node_dockerfile "https://github.com/exa-labs/exa-mcp-server/tree/main/Dockerfile"
click node_smithery "https://github.com/exa-labs/exa-mcp-server/blob/main/smithery.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_mcp,node_api_oauth,node_api_config,node_api_resource toneBlue
class node_src_index,node_mcp_handler toneAmber
class node_web_search,node_web_search_adv,node_code_search,node_company_research,node_people_search,node_linkedin_search,node_crawling,node_deep_start,node_deep_check,node_deep_search toneMint
class node_auth_utils,node_sanitizer,node_logger,node_errors,node_tool_config,node_types toneRose
class node_package_json,node_vercel_json,node_dockerfile,node_smithery toneIndigo
```

## Components

### Protocol layer

HTTP endpoints and MCP/OAuth discovery surface

- [MCP endpoint](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts): http endpoint · Main MCP transport for hosted access · `api/mcp.ts`
- [OAuth endpoint](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp-oauth.ts): auth endpoint · OAuth flow for authenticated MCP clients · `api/mcp-oauth.ts`
- [Discovery config](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts): well-known metadata · Client discovery and MCP configuration · `api/well-known-mcp-config.ts`
- [Resource metadata](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-oauth-protected-resource.ts): well-known 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](https://github.com/exa-labs/exa-mcp-server/blob/main/src/index.ts): node runtime · Top-level service bootstrap and wiring · `src/index.ts`
- [MCP handler](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts): request dispatcher · Central protocol-to-tool request router · `src/mcp-handler.ts`

### Tool layer

Exa-backed search and research capabilities

- [Web search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts): search tool · Core web retrieval tool · `src/tools/webSearch.ts`
- [Advanced search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts): search tool · Richer web search variant · `src/tools/webSearchAdvanced.ts`
- [Code search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/exaCode.ts): search tool · Code-oriented Exa search capability · `src/tools/exaCode.ts`
- [Company research](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/companyResearch.ts): research tool · Company-level synthesis workflow · `src/tools/companyResearch.ts`
- [People search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/peopleSearch.ts): search tool · Person discovery and lookup · `src/tools/peopleSearch.ts`
- [LinkedIn search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/linkedInSearch.ts): search tool · LinkedIn-oriented people/company search · `src/tools/linkedInSearch.ts`
- [Crawling](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/crawling.ts): crawl tool · Fetches and normalizes page content · `src/tools/crawling.ts`
- [Deep start](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepResearchStart.ts): workflow step · Begins staged deep research · `src/tools/deepResearchStart.ts`
- [Deep check](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepResearchCheck.ts): workflow step · Polls staged research status · `src/tools/deepResearchCheck.ts`
- [Deep search](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts): workflow step · Consolidated deep research output · `src/tools/deepSearch.ts`

### Shared utils

Cross-cutting auth, logging, and response shaping

- [Auth](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/auth.ts): security helper · Access checks and request authorization · `src/utils/auth.ts`
- [Sanitizer](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/exaResponseSanitizer.ts): response helper · Normalizes upstream Exa responses · `src/utils/exaResponseSanitizer.ts`
- [Logger](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/logger.ts): observability helper · Structured logging for runtime events · `src/utils/logger.ts`
- [Error handler](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/errorHandler.ts): failure helper · Consistent error shaping and handling · `src/utils/errorHandler.ts`
- [Tool config](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/config.ts): shared config · Shared tool schemas and constants · `src/tools/config.ts`
- [Types](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts): shared types · Common TypeScript types and interfaces · `src/types.ts`

### Packaging

Deployment and client distribution assets

- [Package](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json): build config · Node package metadata and scripts · `package.json`
- [Vercel config](https://github.com/exa-labs/exa-mcp-server/blob/main/vercel.json): deploy config · Serverless deployment configuration · `vercel.json`
- [Dockerfile](https://github.com/exa-labs/exa-mcp-server/tree/main/Dockerfile): deploy config · Container packaging for local or hosted runs · `Dockerfile`
- [Smithery](https://github.com/exa-labs/exa-mcp-server/blob/main/smithery.yaml): distribution config · Marketplace/install metadata · `smithery.yaml`

## Connections

- 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
