# https://github.com/exa-labs/exa-mcp-server Project Manual
Generated at: 2026-05-30 21:18:55 UTC
## Table of Contents
- [Introduction to Exa MCP Server](#introduction)
- [Quick Start Guide](#quick-start)
- [MCP Protocol Implementation](#mcp-protocol-implementation)
- [Transport Layer (HTTP/SSE and STDIO)](#transport-layer)
- [Search Tools Reference](#search-tools)
- [Tool Selection and Configuration](#tool-configuration)
- [IDE Integration Guide](#ide-integration)
- [Environment Variables and API Configuration](#environment-setup)
- [Common Issues and Troubleshooting](#common-issues)
- [Smithery Integration](#smithery-integration)
## Introduction to Exa MCP Server
### Related Pages
Related topics: [Quick Start Guide](#quick-start), [MCP Protocol Implementation](#mcp-protocol-implementation)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/webSearchAdvanced.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts)
- [src/utils/errorHandler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/errorHandler.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# Introduction to Exa MCP Server
Exa MCP Server is a Model Context Protocol (MCP) server that connects AI assistants to Exa's search infrastructure. It enables AI applications to perform web searches, content retrieval, and advanced search operations directly from their conversational interface.
**Version:** 3.2.1
**Package Name:** `exa-mcp-server`
**MCP Name:** `io.github.exa-labs/exa-mcp-server`
**Repository:** [exa-labs/exa-mcp-server](https://github.com/exa-labs/exa-mcp-server)
## Overview
The Exa MCP Server acts as a bridge between AI assistants (such as Claude Code, Cursor, or VS Code) and Exa's search API. It exposes search capabilities as MCP tools that can be invoked programmatically by AI assistants.
```mermaid
graph LR
AI[AI Assistant] <--> MCP[MCP Protocol]
MCP <--> Server[Exa MCP Server]
Server <--> ExaAPI[Exa Search API]
ExaAPI <--> Web[Web Content]
style AI fill:#e1f5fe
style Server fill:#fff3e0
style ExaAPI fill:#f3e5f5
```
### Key Features
| Feature | Description |
|---------|-------------|
| Web Search | Basic search for any topic with clean, ready-to-use content |
| Advanced Search | Full control over filters, domains, dates, highlights, and subpage crawling |
| Web Fetching | Extract content from specific URLs |
| Tool Selection | Enable/disable specific tools via URL parameters |
| Rate Limit Handling | Automatic retry with exponential backoff and user-friendly error messages |
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## Architecture
The server is built on the Model Context Protocol SDK and provides multiple transport mechanisms for different use cases.
### Transport Options
```mermaid
graph TD
subgraph "Transport Types"
HTTP[HTTP/SSE
Remote MCP]
STDIO[STDIO
Local npm package]
end
HTTP --> Preferred[Preferred for most users]
STDIO --> Local[Local development & self-hosting]
style HTTP fill:#c8e6c9
style STDIO fill:#ffe0b2
```
| Transport | Use Case | Setup Complexity |
|-----------|----------|------------------|
| HTTP/SSE | Remote hosted server at `https://mcp.exa.ai/mcp` | Low - no installation required |
| STDIO | Local npm package installation | Medium - requires npm setup |
Source: [package.json:7](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json#L7)
### Server Configuration
The server reads configuration from:
1. **URL Query Parameters** (for HTTP transport)
2. **Environment Variables** (for STDIO transport)
3. **Server-side Fallback** (default API key when none provided)
Configuration parameters are exposed via a JSON Schema at `/.well-known/mcp-config` for client discovery.
Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Available Tools
The server provides the following tools, with varying default states:
### Default Enabled Tools
| Tool | Description | Use Case |
|------|-------------|----------|
| `web_search_exa` | Search the web for any topic and get clean, ready-to-use content | Finding current information, news, facts |
| `web_fetch_exa` | Get the full content of a specific webpage from a known URL | Extracting detailed content from specific pages |
### Off by Default
| Tool | Description | Use Case |
|------|-------------|----------|
| `web_search_advanced_exa` | Advanced web search with full control over filters, domains, dates, and content options | When specific filters like date ranges or category filters are needed |
### Deprecated Tools
The following tools are deprecated but still available for backwards compatibility:
| Deprecated Tool | Replacement | Notes |
|-----------------|-------------|-------|
| `get_code_context_exa` | `web_search_exa` | Code search now part of standard search |
| `company_research_exa` | `web_search_advanced_exa` | Use category filter instead |
| `crawling_exa` | `web_fetch_exa` | Renamed for clarity |
| `people_search_exa` | `web_search_advanced_exa` | Use category:people instead |
| `linkedin_search_exa` | `web_search_advanced_exa` | Use category:people instead |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) | External API endpoint |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) | External API endpoint |
| `deep_search_exa` | `web_search_advanced_exa` | Consolidated into advanced search |
Source: [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Tool Configuration
### Enabling Specific Tools
Use the `tools` URL parameter to enable specific tools:
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
**Note:** Community issue #48 reported that tool selection behavior changed after a new release. If tools are not being selected as expected, verify the comma-separated format matches the documentation.
Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
### Available Tool Values
| Parameter Value | Tool Name |
|-----------------|-----------|
| `web_search_exa` | Standard Web Search |
| `web_search_advanced_exa` | Advanced Web Search |
| `web_fetch_exa` | Web Content Fetching |
Source: [api/well-known-mcp-config.ts:5-7](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts#L5-L7)
## Connection Methods by Client
### Claude Code
```bash
claude mcp add --transport http exa https://mcp.exa.ai/mcp
```
Or with specific tools:
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"
```
### Claude Desktop
Exa is available as a native Claude Connector through the Connectors interface in settings.
### Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"exa": {
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
### VS Code
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
### Local npm Installation
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## Error Handling
The server implements robust error handling with automatic retry logic and user-friendly messages.
### Rate Limit Handling
```mermaid
graph TD
A[Request] --> B{Hit Rate Limit?}
B -->|Yes| C{User Provided API Key?}
B -->|No| D[Process Request]
C -->|No| E[Show Free MCP Rate Limit Message]
C -->|Yes| F[Standard Rate Limit Error]
E --> G[Redirect to API Key Creation]
style E fill:#ffcdd2
style G fill:#c8e6c9
```
**Free MCP Rate Limit Message:**
> You've hit Exa's free MCP rate limit. To continue using without limits, create your own Exa API key.
>
> Fix: Create API key at https://dashboard.exa.ai/api-keys, and then update Exa MCP URL to: `https://mcp.exa.ai/mcp?exaApiKey=YOUR_EXA_API_KEY`
Source: [src/utils/errorHandler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/errorHandler.ts)
### Retry Logic
The server retries on transient server errors (5xx) with exponential backoff:
| Status Code | Retry Behavior |
|-------------|----------------|
| 429 | Rate limit - handled with user message |
| 500, 502, 503, 504 | Retry with exponential backoff |
| Other | Pass through to client |
Source: [src/utils/errorHandler.ts:10](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/errorHandler.ts#L10)
## Known Issues and Limitations
### Community-Reported Issues
| Issue | Status | Workaround |
|-------|--------|------------|
| **#86: HTTP 405 for GET requests** | The remote endpoint at `https://mcp.exa.ai/mcp` returns `405 Method Not Allowed` for standard SSE GET connections. Some clients (like Claude Code) use POST and work correctly. | Use clients that support POST method for SSE, or use tool-based requests |
| **#108: Server downtime** | Occasional connectivity issues to the hosted endpoint | Check status at https://mcp.exa.ai/mcp or use local npm installation |
| **#65: Multiple shebang lines** | The `.smithery/index.cjs` file may contain multiple shebang lines, breaking stdio transport | Build process issue - reported for Smithery integration |
Source: Community Issues [#86](https://github.com/exa-labs/exa-mcp-server/issues/86), [#108](https://github.com/exa-labs/exa-mcp-server/issues/108), [#65](https://github.com/exa-labs/exa-mcp-server/issues/65)
## Advanced Search Parameters
The `web_search_advanced_exa` tool supports extensive filtering options:
### Core Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Search query (required) |
| `numResults` | number | Number of results (1-100, default: 10) |
| `type` | enum | Search type: "auto", "fast", "instant" |
### Category Filter
Use category to narrow results:
| Category | Use Case |
|----------|----------|
| `research paper` | Academic papers from arxiv.org, openreview.net |
| `company` | Company profiles and information |
| `news` | News articles and publications |
| `personal site` | Personal blogs and portfolios |
### Domain Filtering
| Parameter | Description |
|-----------|-------------|
| `includeDomains` | Array of domains to include |
| `excludeDomains` | Array of domains to exclude |
### Date Filtering (ISO 8601)
| Parameter | Description |
|-----------|-------------|
| `startPublishedDate` | Earliest publication date |
| `endPublishedDate` | Latest publication date |
| `startCrawlDate` | Earliest crawl date |
| `endCrawlDate` | Latest crawl date |
### Text Filtering
| Parameter | Description |
|-----------|-------------|
| `includeText` | Must contain ALL specified text (single-item array only) |
| `excludeText` | Exclude if ANY match (single-item array only) |
**Important:** `includeText` and `excludeText` only support **single-item arrays**. Multi-item arrays cause 400 errors.
Source: [src/tools/webSearchAdvanced.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts)
## Debugging
Enable debug logging by adding the `debug` parameter:
```
https://mcp.exa.ai/mcp?debug=true
```
Debug output is written to stderr with the prefix `[EXA-MCP-DEBUG]` and includes:
- Request IDs for tracking
- Tool names
- Query strings
- Error messages
- Completion status
Source: [src/utils/logger.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/logger.ts)
## Related Resources
| Resource | URL |
|----------|-----|
| Full Documentation | https://docs.exa.ai/reference/exa-mcp |
| npm Package | https://www.npmjs.com/package/exa-mcp-server |
| API Key Management | https://dashboard.exa.ai/api-keys |
| GitHub Repository | https://github.com/exa-labs/exa-mcp-server |
| Research API | https://docs.exa.ai/reference/research/create-a-task |
---
## Quick Start Guide
### Related Pages
Related topics: [Introduction to Exa MCP Server](#introduction), [IDE Integration Guide](#ide-integration), [Environment Variables and API Configuration](#environment-setup)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
# Quick Start Guide
The Exa MCP Server is a Model Context Protocol (MCP) server that provides real-time web search and web crawling capabilities through the Exa AI search engine. This guide covers all supported installation methods, configuration options, and basic usage patterns to get you up and running quickly.
## Prerequisites
Before getting started, ensure you have the following:
| Requirement | Description |
|-------------|-------------|
| Node.js | Version 20 or higher required for local installation |
| npm or yarn | Package manager for installing the server |
| Exa API Key | Optional for local installation; remote MCP uses server's fallback key |
| MCP Client | Claude Code, Cursor, or any MCP-compatible client |
Source: [package.json:4](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
## Installation Methods
### Remote MCP (Recommended)
The simplest setup uses the hosted remote MCP server at `https://mcp.exa.ai/mcp`. This method requires no local installation and uses the server's fallback API key.
```
https://mcp.exa.ai/mcp
```
**Advantages:**
- No API key required by default
- Automatic tool updates with server releases
- Works immediately with any MCP-compatible client
**Limitations:**
- Rate limiting may apply under heavy usage
- Custom tool selection requires URL parameter configuration
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
### Local npm Installation
For production environments or custom configurations, install the package globally:
```bash
npm install -g exa-mcp-server
```
The package provides a CLI binary named `exa-mcp-server`:
```bash
exa-mcp-server --help
```
Source: [package.json:7-8](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
### Local Source Installation
Clone and build from source for development or customization:
```bash
git clone https://github.com/exa-labs/exa-mcp-server.git
cd exa-mcp-server
npm install
npm run build
```
Source: [package.json:11](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
## Client Configuration
### Claude Code Configuration
Add the Exa MCP server to your Claude Code configuration:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
**For Remote MCP (HTTP Transport):**
```json
{
"mcpServers": {
"exa": {
"command": "claude",
"args": ["mcp", "add", "--transport", "http", "exa", "https://mcp.exa.ai/mcp"]
}
}
}
```
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
### Cursor Configuration
For Cursor editor, add to your MCP settings:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
## Tool Selection
The server provides multiple tools with different default states. Use the `tools` URL parameter to enable specific tools.
### Available Tools
| Tool | Default | Description |
|------|---------|-------------|
| `web_search_exa` | Enabled | Real-time web search for any topic |
| `web_fetch_exa` | Enabled | Extract content from specific URLs |
| `web_search_advanced_exa` | Disabled | Advanced search with full filter control |
**Enable additional tools:**
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
Source: [src/mcp-handler.ts:19-23](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
### Deprecated Tools
The following tools are deprecated but still available for backwards compatibility:
| Deprecated Tool | Replace With |
|-----------------|--------------|
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `deep_search_exa` | `web_search_advanced_exa` |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) |
Source: [src/mcp-handler.ts:24-35](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Configuration Parameters
Configure the MCP server using URL query parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| `exaApiKey` | string | Your Exa API key (optional for remote MCP) |
| `tools` | string | Comma-separated list of tools to enable |
| `debug` | boolean | Enable debug logging for troubleshooting |
### Configuration Schema
The server exposes a JSON Schema at `/.well-known/mcp-config` for client discovery:
```json
{
"type": "object",
"properties": {
"exaApiKey": {
"type": "string",
"description": "Your Exa AI API key (optional - server has fallback)"
},
"tools": {
"type": "string",
"description": "Comma-separated list of tools to enable"
},
"debug": {
"type": "boolean",
"default": false
}
}
}
```
Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Environment Variables
For local installations, configure using environment variables:
```bash
EXA_API_KEY=your_api_key_here
```
Create an `.env` file based on `env.example` for local development.
## Basic Usage Examples
### Web Search
```javascript
// Using web_search_exa
{
"query": "latest AI research developments 2024",
"numResults": 10
}
```
```javascript
// Using category filters
{
"query": "category:company Anthropic funding",
"numResults": 20
}
```
Source: [src/tools/webSearch.ts:1-20](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
### Web Fetch
```javascript
// Get full content from a URL
{
"url": "https://example.com/article"
}
```
### Advanced Search
```javascript
{
"query": "LLM training efficiency",
"category": "research paper",
"includeDomains": ["arxiv.org", "openreview.net"],
"numResults": 20,
"type": "deep"
}
```
Source: [src/types.ts:1-20](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
## Architecture Overview
```mermaid
graph TD
A[MCP Client] -->|HTTP/STDIO| B[Exa MCP Server]
B -->|API Requests| C[Exa API]
C -->|Search Results| B
B -->|Formatted Response| A
D[Config Layer] -->|URL Params| B
E[Environment] -->|API Key| B
F[Tool Registry] -->|web_search_exa| B
F -->|web_fetch_exa| B
F -->|web_search_advanced_exa| B
```
## Search Categories
The `web_search_advanced_exa` tool supports specialized categories:
| Category | Use Case | Available Filters |
|----------|----------|-------------------|
| `company` | Company info, competitors, financials | Basic metadata only |
| `news` | Press coverage, announcements | Domain + date filters |
| `people` | LinkedIn profiles (public data) | Basic search |
| `research paper` | Academic papers, arXiv | All filters |
| `personal site` | Blogs, portfolios | All filters |
| `auto` | General web results | All filters |
**Note:** When using `category: company`, domain and date filters are not available.
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## Transport Methods
### HTTP/SSE Transport (Default for Remote)
The remote endpoint uses Server-Sent Events over HTTP POST:
```
https://mcp.exa.ai/mcp
```
**Note:** Some MCP clients may experience 405 Method Not Allowed errors when using GET requests. The server expects POST requests for SSE connections.
### STDIO Transport (Local Installation)
For local installations, the server supports STDIO transport:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"]
}
}
}
```
Source: [package.json:7](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
## Troubleshooting
### Issue: Tools Not Appearing After Update
After a server release, existing configurations may not reflect new tool availability. **Solution:** Restart your MCP client to refresh the tool list.
Reference: Community issue #48
### Issue: 405 Method Not Allowed
Generic MCP clients using HTTP GET for SSE connections receive 405 errors. **Solution:** Use POST-based connection or switch to a client that supports POST for SSE (like Claude Code).
Reference: Community issue #86
### Issue: Service Unavailable (503)
The hosted endpoint may be temporarily unavailable. **Solution:** Check [status page](https://status.exa.ai) and retry after a few minutes.
Reference: Community issue #108
### Issue: Multiple Shebang Error (Smithery)
When using the npm package via Smithery, multiple shebang lines may break stdio transport. **Solution:** Use direct npx installation instead of the Smithery marketplace version.
Reference: Community issue #65
### Debug Mode
Enable debug logging for troubleshooting:
```
https://mcp.exa.ai/mcp?debug=true
```
Or set environment variable:
```bash
DEBUG=true exa-mcp-server
```
Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Getting Help
- **Documentation:** [docs.exa.ai/reference/exa-mcp](https://docs.exa.ai/reference/exa-mcp)
- **API Keys:** [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
- **GitHub Issues:** [github.com/exa-labs/exa-mcp-server/issues](https://github.com/exa-labs/exa-mcp-server/issues)
---
## MCP Protocol Implementation
### Related Pages
Related topics: [Transport Layer (HTTP/SSE and STDIO)](#transport-layer), [Search Tools Reference](#search-tools)
Related Source Files
The following source files were used to generate this page:
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/utils/mcpClientMetadata.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/mcpClientMetadata.ts)
- [src/utils/logger.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/logger.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/webSearchAdvanced.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts)
- [src/tools/exaCode.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/exaCode.ts)
# MCP Protocol Implementation
## Overview
The exa-mcp-server implements the Model Context Protocol (MCP) to bridge AI assistants with Exa's search capabilities. This server acts as an intermediary layer that exposes Exa's web search, code search, and content extraction APIs through the standardized MCP interface, enabling AI assistants like Claude to perform real-time web searches, retrieve content from specific URLs, and conduct advanced searches with fine-grained filtering. Source: [src/mcp-handler.ts:1-15]()
## Architecture
The implementation follows a modular architecture with three primary layers:
| Layer | Responsibility |
|-------|----------------|
| **MCP Handler** | Registers tools, manages tool registry, processes incoming MCP requests |
| **Tool Implementations** | Individual search tools (web search, web fetch, advanced search, etc.) |
| **Utilities** | Logging, error handling, response sanitization, client metadata |
```mermaid
graph TD
A[MCP Client] -->|JSON-RPC| B[MCP Handler]
B --> C[Tool Registry]
C --> D[web_search_exa]
C --> E[web_search_advanced_exa]
C --> F[web_fetch_exa]
C --> G[Deprecated Tools]
D --> H[Exa API]
E --> H
F --> H
G --> H
H -->|Sanitized Results| B
B -->|JSON-RPC Response| A
```
### Request Flow
```mermaid
sequenceDiagram
participant Client
participant Handler
participant Tool
participant ExaAPI
participant Logger
Client->>Handler: MCP Request (tool call)
Handler->>Logger: Start request logging
Handler->>Tool: Invoke tool handler
Tool->>ExaAPI: Search/Crawl request
ExaAPI-->>Tool: Raw response
Tool->>Tool: Sanitize response
Tool->>Logger: Complete logging
Tool-->>Handler: Formatted result
Handler-->>Client: JSON-RPC Response
```
## Tool Registry System
The MCP handler maintains a centralized tool registry that controls which tools are available to clients. Each tool entry contains metadata about its name, description, and enabled status. Source: [src/mcp-handler.ts:21-38]()
### Default Enabled Tools
| Tool Name | Display Name | Description | Enabled by Default |
|-----------|--------------|-------------|-------------------|
| `web_search_exa` | Web Search (Exa) | Real-time web search using Exa AI | Yes |
| `web_fetch_exa` | Web Crawling | Extract content from specific URLs | Yes |
### Disabled by Default
| Tool Name | Display Name | Description |
|-----------|--------------|-------------|
| `web_search_advanced_exa` | Advanced Web Search (Exa) | Full filter control including category filters, domain restrictions, date ranges, highlights, summaries, and subpage crawling |
### Deprecated Tools (Still Available)
| Deprecated Tool | Use Instead | Notes |
|-----------------|-------------|-------|
| `get_code_context_exa` | `web_search_exa` | Code search functionality |
| `company_research_exa` | `web_search_advanced_exa` | Company research |
| `crawling_exa` | `web_fetch_exa` | Web crawling |
| `people_search_exa` | `web_search_advanced_exa` | People search |
| `linkedin_search_exa` | `web_search_advanced_exa` | LinkedIn profiles |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) | Deep research start |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) | Deep research check |
| `deep_search_exa` | `web_search_advanced_exa` | Deep search |
## Tool Selection via Configuration
Tools can be enabled/disabled through URL parameters when connecting to the hosted endpoint. The `tools` parameter accepts a comma-separated list of tool names. Source: [api/well-known-mcp-config.ts:1-45]()
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
### Available Tool Values
```typescript
const AVAILABLE_TOOLS = [
'web_search_exa',
'web_search_advanced_exa',
'web_fetch_exa',
];
```
### Configuration Schema
The server exposes a JSON Schema at `/.well-known/mcp-config` for MCP client discovery:
| Parameter | Type | Description |
|-----------|------|-------------|
| `exaApiKey` | string | Your Exa AI API key (optional - server has a fallback key) |
| `tools` | string | Comma-separated list of tools to enable |
| `debug` | boolean | Enable debug logging for troubleshooting |
Source: [api/well-known-mcp-config.ts:10-35]()
**Note:** Issue #48 reported that tool selection behavior changed after a new release, requiring users to reconfigure their MCP client settings to select which tools are available from the MCP server.
## Client Metadata Handling
The implementation includes robust client metadata handling to track MCP client information for analytics and debugging purposes. Source: [src/utils/mcpClientMetadata.ts:1-60]()
### Metadata Fields
| Field | Type | Max Length | Description |
|-------|------|------------|-------------|
| `name` | string | 256 | Client application name |
| `title` | string | 256 | Client title |
| `version` | string | 256 | Client version |
| `source` | string | 256 | Connection source identifier |
| `sessionId` | string | 256 | Session identifier |
| `userAgent` | string | 512 | User agent string |
### Sanitization
The metadata handling includes automatic sanitization of control characters and truncation to prevent buffer overflow:
```typescript
function sanitizeMcpClientField(value: unknown, maxLength = MCP_CLIENT_FIELD_MAX_LENGTH): string | undefined {
// Removes control characters (code points <= 31 or == 127)
// Trims whitespace
// Truncates to max length
}
```
### Session TTL
Client sessions have a time-to-live of 24 hours (86,400 seconds), after which session metadata is discarded. Source: [src/utils/mcpClientMetadata.ts:1]()
```typescript
export const MCP_CLIENT_SESSION_TTL_SECONDS = 24 * 60 * 60;
```
## Logging System
The logging utility provides structured request logging with request ID tracking for debugging and monitoring. Source: [src/utils/logger.ts:1-30]()
### Logger Interface
| Method | Purpose |
|--------|---------|
| `log(message)` | General purpose logging |
| `start(query)` | Log request initiation with query |
| `error(error)` | Log errors with formatted message |
| `complete()` | Log successful completion |
### Log Format
```
[EXA-MCP-DEBUG] [requestId] [toolName] message
```
Example:
```
[EXA-MCP-DEBUG] [web_search_exa-1699999999999-abc123] [web_search_exa] Starting search for query: "TypeScript async/await"
```
## Transport Methods
The server supports multiple transport mechanisms for MCP connectivity.
### HTTP/SSE Transport
The hosted endpoint at `https://mcp.exa.ai/mcp` uses Server-Sent Events over HTTP. Source: [package.json:1-10]()
**Known Issue:** Issue #86 reported that the HTTP SSE endpoint returns `405 Method Not Allowed` for standard GET connections. Some clients (like Claude Code) work around this by using POST requests. This may break generic MCP clients that expect standard SSE/GET behavior.
### Stdio Transport
For local installation via npm, the server uses stdio (standard input/output) transport, which is the default for local MCP servers. Source: [package.json:1-20]()
```bash
npx exa-mcp-server
```
**Known Issue:** Issue #65 documented that multiple shebang lines in `.smithery/index.cjs` break stdio transport due to incorrect build process output.
## Web Search Tool Implementation
The primary web search tool (`web_search_exa`) is implemented with the following structure: Source: [src/tools/webSearch.ts:1-60]()
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query |
| `numResults` | number | No | Number of results (default varies) |
### Search Type Options
| Type | Use Case |
|------|----------|
| `auto` | Default search mode |
| `fast` | Quick results |
| `deep` | Comprehensive search |
| `instant` | Instant results |
## Advanced Search Tool
The `web_search_advanced_exa` tool provides full control over Exa API parameters. Source: [src/types.ts:1-60]()
### Supported Categories
| Category | Description |
|----------|-------------|
| `company` | Business information, news, insights |
| `news` | Press coverage, announcements |
| `github` | Code repositories |
| `pdf` | PDF documents |
| `paper` | Research papers |
| `personal site` | Personal websites and blogs |
| `people` | LinkedIn profiles (public data) |
| `financial report` | SEC filings, earnings reports |
### Category-Specific Restrictions
When using `category: "company"`:
- `includeDomains` / `excludeDomains` cause 400 errors
- `startPublishedDate` / `endPublishedDate` cause 400 errors
- `startCrawlDate` / `endCrawlDate` cause 400 errors
**Universal restriction:** `includeText` and `excludeText` only support **single-item arrays**. Multi-item arrays cause 400 errors across all categories.
## Error Handling
The implementation uses retry logic with exponential backoff for transient failures: Source: [src/tools/webSearch.ts:1]()
```typescript
import { retryWithBackoff, formatToolError } from "../utils/errorHandler.js";
```
### Retry Strategy
| Attempt | Backoff Delay |
|---------|---------------|
| 1 | 500ms |
| 2 | 1000ms |
| 3 | 2000ms |
## Response Sanitization
All Exa API responses pass through a sanitization layer that normalizes the response structure and removes any potentially sensitive or unnecessary fields. Source: [src/tools/webSearch.ts:1]()
```typescript
import { sanitizeSearchResponse } from "../utils/exaResponseSanitizer.js";
```
## Integration with Exa Analytics
The server integrates with Agnost (telemetry) for tracking MCP usage: Source: [src/mcp-handler.ts:1-5]()
```typescript
import { trackMCP, createConfig } from 'agnost';
```
## Installation and Configuration
### Cursor
```
https://cursor.com/en/install-mcp?name=exa&config={"name":"exa","type":"http","url":"https://mcp.exa.ai/mcp"}
```
### VS Code
```
https://vscode.dev/redirect/mcp/install?name=exa&config={"type":"http","url":"https://mcp.exa.ai/mcp"}
```
### Claude Code CLI
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"
```
### npm Package
```bash
npm install exa-mcp-server
```
Environment variable configuration:
```json
{
"exa-mcp-server": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
```
## Related Issues
| Issue | Topic | Status |
|-------|-------|--------|
| #48 | Tool selection after new release | Community discussion |
| #65 | Multiple shebang lines breaking stdio transport | Bug report |
| #86 | HTTP SSE 405 Method Not Allowed | Bug report |
| #108 | Server downtime reporting | Community discussion |
---
## Transport Layer (HTTP/SSE and STDIO)
### Related Pages
Related topics: [MCP Protocol Implementation](#mcp-protocol-implementation), [Common Issues and Troubleshooting](#common-issues), [Smithery Integration](#smithery-integration)
Related Source Files
The following source files were used to generate this page:
- [src/stdio.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio.ts)
- [src/stdio-cli.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio-cli.ts)
- [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# Transport Layer (HTTP/SSE and STDIO)
The Exa MCP Server supports two primary transport mechanisms for communicating with Model Context Protocol clients: **HTTP with Server-Sent Events (SSE)** and **STDIO (Standard Input/Output)**. These transport layers handle the bidirectional communication between AI assistants and the Exa search infrastructure.
## Overview
The transport layer is responsible for:
- Establishing connections between MCP clients and the server
- Serializing/deserializing JSON-RPC messages
- Managing request/response lifecycles
- Handling connection lifecycle events (initialize, terminate)
| Transport | Use Case | Protocol |
|-----------|----------|----------|
| HTTP/SSE | Remote connections, hosted deployments | HTTP POST for requests, SSE stream for responses |
| STDIO | Local installations, CLI tools, npm packages | stdin/stdout pipes |
## Architecture Diagram
```mermaid
graph TD
A[MCP Client] --> B{Transport Selection}
B -->|Remote URL| C[HTTP/SSE Transport]
B -->|Local Install| D[STDIO Transport]
C --> E[Exa MCP Server]
D --> E
E --> F[Exa API]
C --> G[SSE Stream Handler]
D --> H[STDIO Message Loop]
G --> I[Response Writer]
H --> J[stdout Writer]
```
## HTTP/SSE Transport
The HTTP/SSE transport is designed for remote MCP server deployments. The server exposes an HTTP endpoint that accepts POST requests for method calls and streams responses using Server-Sent Events.
### Endpoint Configuration
The HTTP/SSE transport is configured through URL query parameters:
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa
```
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `exaApiKey` | string | Exa API key for authentication | Server fallback key |
| `tools` | string | Comma-separated list of enabled tools | `web_search_exa,web_fetch_exa` |
| `debug` | boolean | Enable debug logging | `false` |
Source: [api/well-known-mcp-config.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
### HTTP Methods and Connection Issues
**Important:** The HTTP endpoint uses `POST` for sending JSON-RPC requests. Standard SSE clients that attempt `GET` connections will receive a `405 Method Not Allowed` error.
This behavior has been reported in community issue [#86](https://github.com/exa-labs/exa-mcp-server/issues/86) where generic MCP clients expecting `GET` for SSE connections experience compatibility issues. Clients like Claude Code handle this by automatically using `POST` requests.
### Request Flow
```mermaid
sequenceDiagram
participant Client
participant Server as HTTP/SSE Server
participant ExaAPI as Exa API
Client->>Server: POST /mcp (JSON-RPC Request)
Server->>ExaAPI: Exa Search API Call
ExaAPI-->>Server: Search Results
Server-->>Client: SSE Stream Response
```
### MCP Configuration Discovery
The server exposes a JSON Schema at `/.well-known/mcp-config` for client configuration discovery:
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "/.well-known/mcp-config",
"title": "Exa MCP Server Configuration",
"type": "object",
"properties": {
"exaApiKey": {
"type": "string",
"description": "Your Exa AI API key for search operations"
},
"tools": {
"type": "string",
"examples": [
"web_search_exa,web_search_advanced_exa",
"web_search_exa,web_search_advanced_exa,web_fetch_exa"
]
},
"debug": {
"type": "boolean",
"default": false
}
}
}
```
Source: [api/well-known-mcp-config.ts:7-35](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## STDIO Transport
The STDIO transport is designed for local installations via npm and CLI usage. It communicates through standard input and output streams using JSON-RPC message format.
### Installation
```bash
npm install -g exa-mcp-server
```
Or run directly with npx:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Source: [package.json:20-28](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
### Entry Points
| File | Purpose |
|------|---------|
| `src/stdio.ts` | Main STDIO module entry point |
| `src/stdio-cli.ts` | CLI wrapper for executable usage |
The `package.json` defines the binary entry point:
```json
{
"bin": {
"exa-mcp-server": "dist/stdio.cjs"
},
"module": "./src/stdio.ts"
}
```
Source: [package.json:20-28](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
### Build Process
The STDIO transport requires compilation to CommonJS for executable distribution:
```bash
npm run build:stdio
```
This esbuild command:
1. Bundles `src/stdio-cli.ts`
2. Targets Node.js 20
3. Outputs to `dist/stdio.cjs`
4. Adds shebang banner for executable execution
```bash
esbuild src/stdio-cli.ts \
--bundle \
--platform=node \
--target=node20 \
--format=cjs \
--outfile=dist/stdio.cjs \
--banner:js="#!/usr/bin/env node" \
&& chmod +x dist/stdio.cjs
```
Source: [package.json:31-35](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
### STDIO Message Loop
The STDIO transport implements a message loop that:
1. Reads JSON-RPC requests from stdin
2. Parses and validates the request
3. Routes to appropriate tool handler
4. Writes JSON-RPC responses to stdout
## Tool Configuration by Transport
### Default Tools by Transport
| Tool | HTTP/SSE (Default) | STDIO (Default) |
|------|-------------------|-----------------|
| `web_search_exa` | ✅ Enabled | ✅ Enabled |
| `web_fetch_exa` | ✅ Enabled | ✅ Enabled |
| `web_search_advanced_exa` | ❌ Disabled | ❌ Disabled |
### Enabling Additional Tools
Both transports support tool configuration via the `tools` parameter:
**HTTP/SSE:**
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
**STDIO (Environment Variable):**
```bash
EXA_MCP_TOOLS=web_search_exa,web_search_advanced_exa,web_fetch_exa exa-mcp-server
```
### Tool Registry
Source: [src/mcp-handler.ts:25-45](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
| Tool Name | Status | Description |
|-----------|--------|-------------|
| `web_search_exa` | Enabled | Real-time web search using Exa AI |
| `web_search_advanced_exa` | Disabled | Advanced web search with full filter control |
| `web_fetch_exa` | Enabled | Extract content from specific URLs |
| `get_code_context_exa` | Deprecated | Use `web_search_exa` instead |
| `company_research_exa` | Deprecated | Use `web_search_advanced_exa` instead |
| `deep_search_exa` | Deprecated | Use `web_search_advanced_exa` instead |
## Client Metadata Handling
Both transports support MCP client metadata for session tracking and analytics:
```typescript
interface McpClientMetadata {
source?: string;
sessionId?: string;
clientInfo?: {
name?: string;
title?: string;
version?: string;
};
userAgent?: string;
}
```
Source: [src/utils/mcpClientMetadata.ts:10-17](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/mcpClientMetadata.ts)
### Session TTL
Client sessions are tracked with a 24-hour TTL:
```typescript
const MCP_CLIENT_SESSION_TTL_SECONDS = 24 * 60 * 60; // 24 hours
```
Source: [src/utils/mcpClientMetadata.ts:3](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/mcpClientMetadata.ts)
## Known Issues and Limitations
### Issue #65: Multiple Shebang Lines
The npm package may fail via stdio transport due to multiple shebang lines being added to `.smithery/index.cjs` during the build process. This breaks the stdio transport when used with the Smithery package manager.
**Workaround:** Ensure only a single shebang line exists at the top of the compiled `dist/stdio.cjs` file.
### Issue #86: HTTP 405 for GET Requests
The remote MCP endpoint (`https://mcp.exa.ai/mcp`) returns `405 Method Not Allowed` for standard SSE connections using HTTP `GET`. Clients must use `POST` requests with SSE streaming responses.
### Issue #48: Tool Selection After Release
Tool selection configuration may require updating after new releases. Users should verify their `tools` parameter configuration matches the available tools list.
## Configuration Quick Reference
### Claude Code Configuration
**STDIO (Local):**
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
**HTTP/SSE (Remote):**
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa"
```
### Cursor Configuration
```json
{
"mcpServers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
### VS Code Configuration
```json
{
"mcpServers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
## Environment Variables
| Variable | Description | Applicable Transport |
|----------|-------------|---------------------|
| `EXA_API_KEY` | Exa API authentication key | Both |
| `EXA_MCP_TOOLS` | Comma-separated tool list | STDIO |
| `EXA_MCP_DEBUG` | Enable debug logging | Both |
---
## Search Tools Reference
### Related Pages
Related topics: [Tool Selection and Configuration](#tool-configuration), [Quick Start Guide](#quick-start)
Related Source Files
The following source files were used to generate this page:
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/webSearchAdvanced.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts)
- [src/tools/webFetch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webFetch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/tools/exaCode.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/exaCode.ts)
- [src/tools/companyResearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/companyResearch.ts)
- [src/tools/peopleSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/peopleSearch.ts)
- [src/tools/linkedInSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/linkedInSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
# Search Tools Reference
The Exa MCP Server provides a comprehensive suite of search tools that enable real-time web searches, advanced filtering, and content retrieval. These tools expose the Exa API's search capabilities through the Model Context Protocol (MCP), allowing AI assistants like Claude to perform web research, code search, company discovery, and people finding.
## Overview
The search tools are implemented as MCP tool handlers registered during server initialization. Each tool wraps the Exa API with specific parameter schemas and response formatting.
```mermaid
graph TD
A[MCP Client Request] --> B[MCP Handler]
B --> C{Which Tool?}
C -->|web_search_exa| D[webSearch.ts]
C -->|web_search_advanced_exa| E[webSearchAdvanced.ts]
C -->|web_fetch_exa| F[webFetch.ts]
C -->|deep_search_exa| G[deepSearch.ts]
C -->|exa_code| H[exaCode.ts]
C -->|company_research_exa| I[companyResearch.ts]
C -->|people_search_exa| J[peopleSearch.ts]
C -->|linkedin_search_exa| K[linkedInSearch.ts]
D --> L[Exa API]
E --> L
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
L --> M[Formatted Response]
M --> N[MCP Client]
```
## Tool Registry
The server maintains a registry of all available tools with their enabled status:
| Tool | Name | Description | Default State |
|------|------|-------------|---------------|
| `web_search_exa` | Web Search | Real-time web search using Exa AI | **Enabled** |
| `web_search_advanced_exa` | Advanced Web Search | Full Exa API control with filters, domains, dates, highlights, summaries, subpage crawling | Disabled |
| `web_fetch_exa` | Web Crawling | Extract content from specific URLs | **Enabled** |
| `get_code_context_exa` | Code Context Search | Search for code snippets and documentation | Disabled |
| `company_research_exa` | Company Research | Research companies and organizations | Disabled |
| `people_search_exa` | People Search | Search for people and professional profiles | Disabled |
| `linkedin_search_exa` | LinkedIn Search | Search LinkedIn profiles | Disabled |
| `deep_search_exa` | Deep Search | Deep search with query expansion | Disabled |
Source: [src/mcp-handler.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Enabling Tools
By default, only `web_search_exa` and `web_fetch_exa` are enabled. Additional tools must be explicitly enabled via the MCP endpoint URL.
### Remote MCP Endpoint
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
### Local/STDIO Configuration
For stdio transport, specify enabled tools in the configuration:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server", "--tools", "web_search_exa,web_search_advanced_exa,web_fetch_exa"]
}
}
}
```
> **Community Note:** Issue #48 reported that tool selection behavior changed after a new release. The current implementation uses URL parameters (`?tools=...`) for the remote endpoint and command-line arguments for local installations.
## Core Search Tools
### web_search_exa
The primary search tool for general-purpose web searches. It uses natural language queries and returns clean, ready-to-use content.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query describing the ideal page |
| `numResults` | number | No | Number of results to return (default: 10) |
**Query Tips:**
- Describe the ideal page, not just keywords
- Example: `"blog post comparing React and Vue performance"` instead of `"React vs Vue"`
- Use `category:people` or `category:company` to focus on specific result types
The tool automatically extracts category hints from the query string using a regex pattern that matches `category:(company|research paper|news|personal site|people)`. Source: [src/tools/webSearch.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
**Request Hint Annotations:**
The tool declares the following hints for MCP clients:
| Hint | Value | Purpose |
|------|-------|---------|
| `readOnlyHint` | true | Safe for read operations |
| `destructiveHint` | false | No data modification |
| `openWorldHint` | false | Does not access external systems beyond the web |
| `idempotentHint` | true | Safe to retry |
### web_search_advanced_exa
Advanced search tool providing full control over all Exa API parameters. This tool supports category-specific filtering, domain restrictions, date ranges, content extraction options, and subpage crawling.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query |
| `type` | enum | No | Search type: `"auto"`, `"keyword"`, `"neural"`, `"deep"` (default: auto) |
| `numResults` | number | No | Number of results (default: 10) |
| `category` | string | No | Filter by category type |
**Category Types:**
| Category | Description |
|----------|-------------|
| `company` | Homepages, rich metadata (headcount, location, funding, revenue) |
| `research paper` | Academic papers from arxiv.org, openreview.net, etc. |
| `news` | Press coverage, announcements |
| `pdf` | PDF documents |
| `github` | GitHub repositories |
| `personal site` | Personal websites and blogs |
| `people` | LinkedIn profiles (public data) |
| `financial report` | SEC filings, earnings reports |
Source: [src/types.ts:1-100](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
**Domain Filtering:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `includeDomains` | string[] | Restrict results to specific domains |
| `excludeDomains` | string[] | Exclude specific domains |
**Date Filtering:**
| Parameter | Type | Format | Description |
|-----------|------|--------|-------------|
| `startPublishedDate` | string | ISO 8601 | Filter by publication date (e.g., `"2024-01-01"`) |
| `endPublishedDate` | string | ISO 8601 | End of publication date range |
| `startCrawlDate` | string | ISO 8601 | Filter by when URL was crawled |
| `endCrawlDate` | string | ISO 8601 | End of crawl date range |
**Text Filtering:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `includeText` | string[] | Results must contain ALL specified text (single-item arrays only) |
| `excludeText` | string[] | Exclude if ANY text matches (single-item arrays only) |
> **Critical Restriction:** `includeText` and `excludeText` only support **single-item arrays**. Multi-item arrays (2+ items) cause 400 errors. To match multiple terms, include them in the query string or run separate searches.
Source: [src/types.ts:100-200](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
**Category-Specific Filter Restrictions:**
When using `category: "company"`, the following parameters cause 400 errors:
- `includeDomains` / `excludeDomains`
- `startPublishedDate` / `endPublishedDate`
- `startCrawlDate` / `endCrawlDate`
**Content Extraction Options:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `textMaxCharacters` | number | Maximum characters for extracted text |
| `contextMaxCharacters` | number | Maximum characters for surrounding context |
| `enableSummary` | boolean | Enable AI-generated summary |
| `summaryQuery` | string | Custom query for summary generation |
| `enableHighlights` | boolean | Enable highlight extraction |
| `highlightsNumSentences` | number | Number of highlight sentences (default: 5) |
| `highlightsPerUrl` | number | Highlights per URL |
| `highlightsQuery` | string | Custom query for highlights |
| `livecrawl` | enum | Live crawl mode: `"never"`, `"fallback"`, `"always"`, `"preferred"` |
| `subpages` | number | Number of subpages to crawl |
| `subpageTarget` | string[] | Target patterns for subpage discovery |
### web_fetch_exa
Retrieves full content from specific URLs. Used when you have known URLs and want the complete page content.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | URL of the webpage to fetch |
| `query` | string | No | Specific information to extract from the page |
The tool handles rate limiting, retries failed requests, and extracts clean text content from the fetched page.
## Deep Search Tool
### deep_search_exa
Provides deep search with query expansion and synthesized answers. Supports structured output mode for programmatic consumption.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `objective` | string | Yes | Natural language description of what to find |
| `search_queries` | string[] | No | Optional keyword queries (max 5, up to 5 words each) |
| `type` | enum | No | Search depth: `"deep"` (4-12s) or `"deep-reasoning"` (12-50s) |
| `numResults` | number | No | Number of results (default: 8) |
| `highlightMaxCharacters` | number | No | Max characters for highlights (default: 4000) |
| `outputSchema` | object | No | JSON schema for structured output |
| `systemPrompt` | string | No | Custom instructions for result processing |
| `structuredOutput` | boolean | No | Return structured JSON instead of markdown |
**Search Depth Modes:**
| Mode | Duration | Use Case |
|------|----------|----------|
| `deep` | 4-12 seconds | Fast deep search with query expansion |
| `deep-reasoning` | 12-50 seconds | Thorough analysis with reasoning chains |
Source: [src/tools/deepSearch.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
**Output Schema:**
When providing `outputSchema`, it must include:
- `type` field set to `"object"` or `"text"`
- For `"object"` type: optionally include `properties` and `required` fields
- Maximum 10 total properties
- Maximum nesting depth of 2
```json
{
"outputSchema": {
"type": "object",
"properties": {
"companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"founded": { "type": "number" }
}
}
}
}
}
}
```
## Deprecated Search Tools
The following tools are deprecated but still available for backwards compatibility:
| Deprecated Tool | Replacement |
|-----------------|--------------|
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `people_search_exa` | `web_search_advanced_exa` |
| `linkedin_search_exa` | `web_search_advanced_exa` |
| `deep_search_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) |
Source: [src/mcp-handler.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Response Format
All search tools return results in a standardized format with the following structure:
```typescript
interface ExaSearchResponse {
requestId: string;
autopromptString?: string;
autoDate?: string;
resolvedSearchType: string;
context?: string;
output?: {
content: string | Record;
grounding?: Array<{
field: string;
citations: Array<{ url: string; title: string }>;
confidence: string;
}>;
};
statuses?: ExaSearchStatus[];
results: ExaSearchResult[];
searchTime?: number;
costDollars?: ExaCostDollars;
}
```
**Individual Result Structure:**
```typescript
interface ExaSearchResult {
id?: string;
title?: string | null;
url?: string;
publishedDate?: string;
author?: string;
text?: string;
summary?: string;
highlights?: string[];
highlightScores?: number[];
image?: string;
favicon?: string;
score?: number;
entities?: Record[];
extras?: {
links?: string[];
imageLinks?: string[];
};
subpages?: ExaSearchResult[];
}
```
Source: [src/types.ts:200-350](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
## Common Usage Patterns
### Basic Web Search
```json
web_search_exa {
"query": "latest developments in quantum computing",
"numResults": 10
}
```
### Company Research with Filters
```json
web_search_advanced_exa {
"query": "AI infrastructure startups San Francisco",
"category": "company",
"numResults": 20,
"type": "auto"
}
```
### News Search with Date Range
```json
web_search_advanced_exa {
"query": "Anthropic AI safety",
"category": "news",
"numResults": 15,
"startPublishedDate": "2024-01-01"
}
```
### Research Paper Search
```json
web_search_advanced_exa {
"query": "LLM training efficiency",
"category": "research paper",
"includeDomains": ["arxiv.org", "openreview.net"],
"includeText": ["transformer"],
"numResults": 20,
"type": "deep"
}
```
### Deep Search with Structured Output
```json
deep_search_exa {
"objective": "Find information about major Anthropic funding rounds and valuations",
"type": "deep",
"numResults": 8,
"outputSchema": {
"type": "object",
"properties": {
"funding_rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"round": { "type": "string" },
"amount": { "type": "string" },
"date": { "type": "string" },
"valuation": { "type": "string" }
}
}
}
}
}
}
```
## Search Type Reference
| Type | Description | Best For |
|------|-------------|----------|
| `auto` | Automatically selects best search method | General queries |
| `keyword` | Keyword-based search | Exact term matching |
| `neural` | Semantic/AI-powered search | Conceptual queries |
| `deep` | Deep search with query expansion | Comprehensive research |
| `deep-reasoning` | Deep search with reasoning chains | Complex analysis |
## Best Practices
1. **Use Descriptive Queries:** Describe the ideal page content rather than listing keywords
2. **Start Broad, Then Refine:** Begin with general searches, then narrow with filters
3. **Use Appropriate Categories:** Leverage category filters for targeted results
4. **Handle Rate Limits:** Implement exponential backoff for bulk searches
5. **Check Enabled Tools:** Verify required tools are enabled before searching
6. **Use Structured Output:** For programmatic consumption, use `outputSchema` with `deep_search_exa`
## Troubleshooting
### 400 Errors with includeText/excludeText
**Cause:** Using multi-item arrays with text filtering parameters
**Solution:** Use single-item arrays or include multiple terms in the query string
### 405 Method Not Allowed (Remote Endpoint)
> **Community Note:** Issue #86 reported that the remote MCP endpoint (`https://mcp.exa.ai/mcp`) returns 405 errors for standard SSE GET connections. Some clients (like Claude Code) connect successfully by using POST. Ensure your MCP client supports POST-based SSE transport.
**Solution:** Use a client that supports POST-based SSE, or use the local stdio transport as an alternative.
### Insufficient Results
**Cause:** Query too narrow or filters too restrictive
**Solution:**
- Remove domain filters
- Expand date ranges
- Use `type: "deep"` for broader coverage
- Try multiple query phrasings
---
## Tool Selection and Configuration
### Related Pages
Related topics: [Search Tools Reference](#search-tools), [Environment Variables and API Configuration](#environment-setup)
Related Source Files
The following source files were used to generate this page:
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
# Tool Selection and Configuration
The Exa MCP Server provides a flexible tool registry system that allows MCP clients to enable or disable specific search capabilities. This page documents how tools are registered, configured, and exposed to connected clients.
## Overview
The Exa MCP Server implements a **tool selection and configuration system** that controls which search capabilities are available at runtime. This system addresses a common requirement identified in community issue #48, where users need granular control over which tools their MCP clients can access after releases. Source: [src/mcp-handler.ts:29-45]()
### Design Principles
| Principle | Description |
|-----------|-------------|
| **Opt-in by Default** | Most advanced tools are disabled unless explicitly enabled |
| **URL-Based Configuration** | Tools are selected via query parameters on the MCP endpoint |
| **Declarative Registry** | All tools are registered in a central `availableTools` object |
| **Lazy Registration** | Tools are only registered if explicitly enabled in configuration |
Source: [src/mcp-handler.ts:29-45]()
## Tool Registry
### Available Tools Reference
The server maintains a registry of all tools with their default enabled states:
| Tool ID | Name | Default | Status |
|---------|------|---------|--------|
| `web_search_exa` | Web Search | **Enabled** | Active |
| `web_search_advanced_exa` | Advanced Web Search | Disabled | Active |
| `web_fetch_exa` | Web Crawling | **Enabled** | Active |
| `get_code_context_exa` | Code Context Search | Disabled | Deprecated |
| `company_research_exa` | Company Research | Disabled | Deprecated |
| `crawling_exa` | Web Crawling (Legacy) | Disabled | Deprecated |
| `people_search_exa` | People Search | Disabled | Deprecated |
| `linkedin_search_exa` | LinkedIn Search | Disabled | Deprecated |
| `deep_researcher_start` | Deep Researcher Start | Disabled | Deprecated |
| `deep_researcher_check` | Deep Researcher Check | Disabled | Deprecated |
| `deep_search_exa` | Deep Search | Disabled | Deprecated |
Source: [src/mcp-handler.ts:29-45]()
### Registry Implementation
The tool registry is defined as a constant object in `src/mcp-handler.ts`:
```typescript
const availableTools = {
'web_search_exa': {
name: 'Web Search (Exa)',
description: 'Real-time web search using Exa AI',
enabled: true
},
'web_search_advanced_exa': {
name: 'Advanced Web Search (Exa)',
description: 'Advanced web search with full Exa API control including category filters, domain restrictions, date ranges, highlights, summaries, and subpage crawling',
enabled: false
},
// ... additional tools
};
```
Each tool entry contains:
- `name`: Human-readable display name
- `description`: Explanation of the tool's capabilities
- `enabled`: Default state (boolean)
Source: [src/mcp-handler.ts:29-45]()
## Configuration Schema
### MCP Configuration Endpoint
The server exposes a JSON Schema at `/.well-known/mcp-config` for client discovery. This follows the standard MCP well-known configuration pattern. Source: [api/well-known-mcp-config.ts:1-15]()
### Configuration Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `exaApiKey` | string | No | Server fallback | Your Exa AI API key for search operations |
| `tools` | string | No | `web_search_exa,web_fetch_exa` | Comma-separated list of tools to enable |
| `debug` | boolean | No | `false` | Enable debug logging for troubleshooting |
Source: [api/well-known-mcp-config.ts:16-43]()
### Configuration Schema Definition
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "/.well-known/mcp-config",
"title": "Exa MCP Server Configuration",
"description": "Configuration for connecting to the Exa MCP server",
"x-query-style": "dot+bracket",
"type": "object",
"properties": {
"exaApiKey": {
"type": "string",
"title": "Exa API Key",
"description": "Your Exa AI API key for search operations (optional - server has a fallback key). Get one at https://exa.ai"
},
"tools": {
"type": "string",
"title": "Enabled Tools",
"description": "Comma-separated list of tools to enable. Leave empty for defaults (web_search_exa, web_fetch_exa).",
"examples": [
"web_search_exa,web_search_advanced_exa",
"web_search_exa,web_search_advanced_exa,web_fetch_exa"
],
"x-available-values": ["web_search_exa", "web_search_advanced_exa", "web_fetch_exa"]
},
"debug": {
"type": "boolean",
"title": "Debug Mode",
"description": "Enable debug logging for troubleshooting",
"default": false
}
}
}
```
Source: [api/well-known-mcp-config.ts:16-43]()
## Configuration Resolution
### Priority Order
The server resolves configuration from multiple sources with the following priority:
1. **x-api-key header** (highest priority)
2. **OAuth JWT Bearer token**
3. **Plain Bearer API key**
4. **Query parameter** (`exaApiKey`, `tools`)
5. **Environment variable** (`EXA_API_KEY`)
6. **Server defaults** (lowest priority)
Source: [api/mcp.ts:16-25]()
### Request Configuration Interface
```typescript
interface RequestConfig {
exaApiKey?: string;
enabledTools?: string[];
debug: boolean;
userProvidedApiKey: boolean;
authMethod: 'oauth' | 'api_key' | 'free_tier';
exaSource?: string;
mcpSessionId?: string;
mcpClient?: McpClientMetadata;
defaultSearchType?: 'auto' | 'fast';
invalidOAuthJwt: boolean;
}
```
Source: [api/mcp.ts:16-30]()
## Tool Selection Workflow
The following diagram illustrates how tools are registered during server initialization:
```mermaid
graph TD
A[MCP Server Starts] --> B[Parse Configuration from Request]
B --> C{tools parameter present?}
C -->|Yes| D[Split comma-separated tools]
C -->|No| E[Use default tools]
D --> F{debug enabled?}
E --> F
F -->|Yes| G[Log available tools]
F -->|No| H[Skip debug logging]
G --> I[Iterate through availableTools registry]
H --> I
I --> J{Current tool in enabledTools?}
J -->|Yes| K[Register tool with MCP server]
J -->|No| L[Skip registration]
K --> M[Tool available to clients]
L --> N{Next tool exists?}
N -->|Yes| I
N -->|No| O[Server ready]
M --> N
```
This workflow addresses community concern #48 by ensuring that tool selection is consistently applied after releases.
## Enabling Specific Tools
### URL Query Parameter Method
The primary method for selecting tools is via the `tools` query parameter:
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
This example enables all three core tools.
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
### Claude Code Configuration
For Claude Code, add the following to your MCP configuration:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Then enable specific tools using the URL endpoint with query parameters.
Source: [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
### Cursor / VS Code Configuration
For Cursor:
```
https://cursor.com/en/install-mcp?name=exa&config=eyJuYW1lIjoiZXhhIiwidHlwZSI6Imh0dHAiLCJ1cmwiOiJodHRwczovL21jcC5leGEuYWkvbWNwIn0=
```
For VS Code:
```
https://vscode.dev/redirect/mcp/install?name=exa&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.exa.ai%2Fmcp%22%7D
```
Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## Tool Registration Process
### Registration Flow
When a tool is enabled, the registration process follows this pattern:
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant Registry as Tool Registry
participant ExaAPI as Exa API
Client->>Server: Connect with tools=parameter
Server->>Registry: Check if tool.enabled = true
Registry-->>Server: Tool configuration
Server->>ExaAPI: Initialize Exa client
ExaAPI-->>Server: Client ready
Server->>Client: Register tool handlers
Client->>Server: Tool call request
Server->>ExaAPI: Execute search
ExaAPI-->>Server: Search results
Server-->>Client: Formatted response
```
### Tool Handler Registration
Each tool is registered with the MCP server using its registration function:
```typescript
// From src/mcp-handler.ts
import { registerWebSearchTool } from "./tools/webSearch.js";
import { registerWebSearchAdvancedTool } from "./tools/webSearchAdvanced.js";
import { registerWebFetchTool } from "./tools/webFetch.js";
// ... additional imports
```
Source: [src/mcp-handler.ts:68-77]()
### Available Tool Registration Functions
| Function | File | Purpose |
|----------|------|---------|
| `registerWebSearchTool` | src/tools/webSearch.ts | Basic web search |
| `registerWebSearchAdvancedTool` | src/tools/webSearchAdvanced.ts | Advanced search with filters |
| `registerWebFetchTool` | src/tools/webFetch.ts | Content extraction from URLs |
| `registerCompanyResearchTool` | src/tools/companyResearch.ts | Company-specific search |
| `registerPeopleSearchTool` | src/tools/peopleSearch.ts | People/professional search |
| `registerLinkedInSearchTool` | src/tools/linkedInSearch.ts | LinkedIn profile search |
| `registerDeepResearchStartTool` | src/tools/deepResearchStart.ts | Research task initiation |
| `registerDeepResearchCheckTool` | src/tools/deepResearchCheck.ts | Research status checking |
| `registerExaCodeTool` | src/tools/exaCode.ts | Code search |
| `registerDeepSearchTool` | src/tools/deepSearch.ts | Deep search with reasoning |
Source: [src/mcp-handler.ts:68-77]()
## Default Tool Behavior
### Always-Enabled Tools
The following tools are enabled by default when no `tools` parameter is specified:
| Tool | Purpose | Key Features |
|------|---------|---------------|
| `web_search_exa` | Basic web search | Natural language queries, category extraction |
| `web_fetch_exa` | Content fetching | URL-based content extraction |
Source: [src/mcp-handler.ts:29-45]()
### Basic Web Search Tool
The `web_search_exa` tool provides straightforward web search:
```typescript
{
query: lenientString().describe("Natural language search query..."),
numResults: lenientOptionalNumber().describe("Number of search results to return (default: 10)."),
}
```
Features:
- Semantic search with natural language queries
- Category extraction from query string (e.g., `category:people John Doe`)
- Read-only, idempotent operations
Source: [src/tools/webSearch.ts:1-30]()
### Web Fetch Tool
The `web_fetch_exa` tool extracts content from specific URLs:
| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | URL to fetch |
| `textMaxCharacters` | number | Maximum text characters |
| `highlightQuery` | string | Query for relevant highlights |
Source: [src/types.ts:1-40]()
## Advanced Tool Enablement
### Advanced Web Search Tool
The `web_search_advanced_exa` tool provides full control over Exa search parameters. It is disabled by default and must be explicitly enabled:
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
**Key Features:**
| Feature | Parameters |
|---------|------------|
| Category filtering | `category`: company, research paper, news, pdf, github, personal site, people, financial report |
| Domain filtering | `includeDomains`, `excludeDomains` |
| Date filtering | `startPublishedDate`, `endPublishedDate`, `startCrawlDate`, `endCrawlDate` |
| Text filtering | `includeText`, `excludeText` (single-item arrays only) |
| Content extraction | `textMaxCharacters`, `contextMaxCharacters`, `enableSummary`, `enableHighlights` |
| Subpage crawling | `subpages`, `subpageTarget` |
Source: [src/types.ts:1-40]()
### Deep Search Tool
The `deep_search_exa` tool (deprecated, use `web_search_advanced_exa`) provides deep search with reasoning:
```typescript
{
objective: lenientString().describe("Natural language description of what to search for"),
search_queries: z.array(z.string()).optional().describe("Related keyword queries"),
type: z.enum(['deep', 'deep-reasoning']).optional().describe("Search depth"),
numResults: lenientOptionalNumber().describe("Number of results (default: 8)"),
outputSchema: z.record(z.string(), z.unknown()).optional().describe("Structured output schema"),
systemPrompt: z.string().max(32000).optional().describe("Agent instructions"),
structuredOutput: lenientOptionalBoolean().describe("Return structured JSON"),
}
```
**Search Types:**
- `deep`: Fast deep search (4-12 seconds)
- `deep-reasoning`: Thorough search with reasoning (12-50 seconds)
Source: [src/tools/deepSearch.ts:1-50]()
## Search Response Types
### ExaSearchResult
```typescript
interface ExaSearchResult {
id?: string;
title?: string | null;
url?: string;
publishedDate?: string;
author?: string;
text?: string;
summary?: string;
highlights?: string[];
highlightScores?: number[];
image?: string;
favicon?: string;
score?: number;
entities?: Record[];
extras?: {
links?: string[];
imageLinks?: string[];
};
subpages?: ExaSearchResult[];
}
```
Source: [src/types.ts:41-68]()
### ExaSearchResponse
```typescript
interface ExaSearchResponse {
requestId: string;
autopromptString?: string;
autoDate?: string;
resolvedSearchType: string;
context?: string;
output?: {
content: string | Record;
grounding?: Array<{
field: string;
citations: Array<{ url: string; title: string }>;
confidence: string;
}>;
};
statuses?: ExaSearchStatus[];
results: ExaSearchResult[];
searchTime?: number;
costDollars?: ExaCostDollars;
}
```
Source: [src/types.ts:82-100]()
## Debug Mode Configuration
Enable debug logging to troubleshoot tool selection and configuration issues:
```
https://mcp.exa.ai/mcp?tools=web_search_exa&debug=true
```
Debug mode enables:
- Configuration parsing logs
- Tool registration status
- Analytics tracking setup status
- Request/response logging
Source: [src/mcp-handler.ts:120-140]()
## Analytics Integration
The MCP server integrates with Agnost analytics for usage tracking:
```typescript
trackMCP(underlyingServer, "f0df908b-3703-40a0-a905-05c907da1ca3", createConfig({
endpoint: "https://api.agnost.ai",
disableLogs: true,
disableInput: true,
disableOutput: true,
disableError: false
}));
```
This integration is non-critical—server operation continues even if analytics setup fails.
Source: [src/mcp-handler.ts:115-135]()
## Best Practices
### Recommended Tool Configuration
| Use Case | Recommended Tools |
|----------|-------------------|
| Basic web search | `web_search_exa` (default) |
| Research tasks | `web_search_exa,web_search_advanced_exa,web_fetch_exa` |
| Company intelligence | `web_search_exa,web_search_advanced_exa` |
| Content aggregation | `web_search_advanced_exa,web_fetch_exa` |
### Handling Category-Specific Restrictions
When using `category: "company"`, these parameters cause 400 errors:
- `includeDomains` / `excludeDomains`
- `startPublishedDate` / `endPublishedDate`
- `startCrawlDate` / `endCrawlDate`
**Universal restriction:** `includeText` and `excludeText` only support **single-item arrays** across all categories.
### Performance Considerations
- `web_search_exa`: Low latency, suitable for real-time queries
- `web_search_advanced_exa`: Variable latency depending on content extraction
- `deep_search_exa`: 4-50 seconds depending on reasoning depth
## Troubleshooting
### Tool Not Available
If a tool is not available to your client:
1. Verify the `tools` parameter is correctly formatted: `?tools=tool1,tool2`
2. Check that the tool ID matches exactly (case-sensitive)
3. Enable debug mode: `?debug=true` to see registration logs
### Configuration Not Persisting
As noted in community issue #48, tool selection may need to be reconfigured after server updates. Always verify your MCP client configuration reflects your intended tool selection.
### API Key Issues
If you receive authentication errors:
1. Ensure `EXA_API_KEY` environment variable is set (for local deployment)
2. Or pass `exaApiKey` as a query parameter (for hosted endpoint)
3. Or use the `x-api-key` header (highest priority)
Source: [api/mcp.ts:16-30]()
---
## IDE Integration Guide
### Related Pages
Related topics: [Quick Start Guide](#quick-start), [Environment Variables and API Configuration](#environment-setup), [Smithery Integration](#smithery-integration)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
- [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
# IDE Integration Guide
The Exa MCP Server enables AI assistants in integrated development environments (IDEs) to perform real-time web searches, content retrieval, and advanced search operations. This guide covers integration with popular AI-enabled IDEs including Cursor, VS Code, and Claude Code.
## Overview
The MCP (Model Context Protocol) server acts as a bridge between your IDE's AI assistant and Exa's search infrastructure. By configuring your IDE to connect to either the hosted remote server (`https://mcp.exa.ai/mcp`) or a locally installed instance, you gain access to web search capabilities directly within your development workflow.
### Supported Transport Methods
| Transport | Description | Use Case |
|-----------|-------------|----------|
| HTTP/SSE | Remote connection via Server-Sent Events | Cloud-hosted, no local setup |
| Stdio | Standard input/output pipe | Local npm installation |
| Streamable HTTP | Modern HTTP streaming | Cursor, Claude Code clients |
> **Note:** The remote endpoint requires the `POST` HTTP method for SSE connections. Standard `GET` requests return `405 Method Not Allowed`. This is by design for security and compatibility with MCP clients. Source: [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
## Supported IDEs
### Cursor
Cursor provides one-click MCP integration through its installation system.
**Installation:**
1. Click the Install in Cursor badge in the README
2. Or manually configure in Cursor settings with:
```json
{
"mcpServers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
### VS Code
VS Code with the Copilot extension supports MCP servers through configuration.
**Manual Configuration:**
```json
{
"mcpServers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
Access via: `https://vscode.dev/redirect/mcp/install?name=exa&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.exa.ai%2Fmcp%22%7D`
### Claude Code (Desktop)
Claude Code supports both HTTP and stdio transports.
**HTTP Transport (Recommended):**
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp"
```
**Stdio Transport (Local Installation):**
```bash
claude mcp add --transport stdio exa "npx exa-mcp-server"
```
## Configuration Options
The MCP server accepts configuration through URL query parameters or environment variables. Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
### URL Parameter Configuration
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `exaApiKey` | string | Your Exa API key | Server fallback key |
| `tools` | string | Comma-separated list of tools to enable | `web_search_exa,web_fetch_exa` |
| `debug` | boolean | Enable debug logging | `false` |
### Example Configured Endpoint
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
### Environment Variables
| Variable | Description |
|----------|-------------|
| `EXA_API_KEY` | API key for Exa search operations |
| `DEBUG` | Set to `true` for debug logging |
### Configuration Priority
Configuration is resolved in this order (highest to lowest priority):
1. `x-api-key` HTTP header
2. OAuth JWT Bearer token
3. Plain Bearer API key
4. URL query parameter (`exaApiKey`)
5. Environment variable (`EXA_API_KEY`)
Source: [api/mcp.ts:33-52](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
## Tool Selection
### Default Tools
The following tools are enabled by default without additional configuration:
| Tool | Description |
|------|-------------|
| `web_search_exa` | Real-time web search for any topic |
| `web_fetch_exa` | Extract content from specific URLs |
### Advanced Tools
These tools are disabled by default and must be explicitly enabled via the `tools` parameter:
| Tool | Description |
|------|-------------|
| `web_search_advanced_exa` | Full control over filters, domains, dates, highlights, and subpage crawling |
| `deep_search_exa` | Deep search with query expansion (deprecated, use advanced) |
| `company_research_exa` | Company research (deprecated, use advanced) |
| `people_search_exa` | People/professional profiles (deprecated, use advanced) |
> **Community Issue #48:** After releases, some users report that tool selection via configuration stops working. Verify your configuration uses the correct `tools` parameter format: `tools=tool1,tool2,tool3` (comma-separated, no spaces). Source: [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
### Enabling All Tools
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
## Claude Code Skills
Claude Code supports skill files that define best practices for using Exa search. Skills are pasted directly into Claude Code and handle MCP connection and tool usage patterns. Source: [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
### Available Skills
| Skill | Use Case |
|-------|----------|
| `company-research` | Company discovery, financials, news, LinkedIn profiles |
| `web-search-advanced-research-paper` | Academic papers, arxiv.org, openreview.net |
| `web-search-advanced-personal-site` | Personal blogs, portfolios, independent websites |
### Installing a Skill
1. Copy the skill content from the README dropdown
2. Paste into Claude Code
3. Claude Code handles MCP configuration automatically
4. Restart Claude Code to apply changes
## Local Installation
For environments requiring local execution, install the npm package:
```bash
npm install -g exa-mcp-server
```
### Build Output
The package builds to `dist/stdio.cjs` with the following entry point:
```json
{
"bin": {
"exa-mcp-server": "dist/stdio.cjs"
}
}
```
Source: [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
### Smithery Integration
> **Community Issue #65:** The `.smithery/index.cjs` file may contain multiple shebang lines (`#!/usr/bin/env node`), causing stdio transport to fail. If you encounter this issue:
> 1. Remove duplicate shebang lines manually
> 2. Ensure only one `#!/usr/bin/env node` at the top of the file
> 3. Report the issue to the maintainers
## API Key Management
### Obtaining an API Key
1. Visit [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
2. Generate a new API key
3. Configure via URL parameter or environment variable
### Security Considerations
- Never commit API keys to version control
- Use environment variables in production
- The hosted endpoint includes a fallback key for limited usage
### Authentication Methods
The server supports three authentication tiers:
| Method | Description |
|--------|-------------|
| `oauth` | Full API access via OAuth |
| `api_key` | Standard API key authentication |
| `free_tier` | Limited access without API key |
Source: [api/mcp.ts:21](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
## Architecture Overview
```mermaid
graph TD
subgraph "IDE Client"
A[AI Assistant]
end
subgraph "MCP Transport Layer"
B[HTTP/SSE or Stdio]
C[Streamable HTTP]
end
subgraph "Exa MCP Server"
D[Configuration Parser]
E[Tool Registry]
F[Request Logger]
end
subgraph "Exa API"
G[Search API]
H[Deep Search API]
I[Web Fetch API]
end
A -->|MCP Protocol| B
A -->|MCP Protocol| C
B --> D
C --> D
D --> E
E --> F
F -->|web_search| G
F -->|deep_search| H
F -->|web_fetch| I
style G fill:#90EE90
style H fill:#90EE90
style I fill:#90EE90
```
## Troubleshooting
### Connection Issues
| Symptom | Solution |
|---------|----------|
| `405 Method Not Allowed` | Use `POST` method for SSE connections. The endpoint requires POST requests. |
| `mcp.exa.ai/mcp down` | Check [status.exa.ai](https://status.exa.ai) for outages |
| Connection timeout | Verify network connectivity and firewall rules |
### Tool Not Available
| Symptom | Solution |
|---------|----------|
| Tool not found | Ensure the tool is enabled in the `tools` URL parameter |
| 400 Bad Request | Check that `includeText` and `excludeText` use single-item arrays only |
### Stdio Transport Issues
| Symptom | Solution |
|---------|----------|
| Multiple shebang error | Manually fix `.smithery/index.cjs` - remove duplicate shebang lines |
| Command not found | Reinstall: `npm install -g exa-mcp-server` |
## Quick Reference
### Minimal Configuration (Remote)
```
https://mcp.exa.ai/mcp
```
### Full Configuration (Remote)
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
### Claude Code Setup
```bash
# Add MCP connection
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"
# Restart Claude Code to apply
```
### Get Help
- Documentation: [docs.exa.ai/reference/exa-mcp](https://docs.exa.ai/reference/exa-mcp)
- GitHub Issues: [github.com/exa-labs/exa-mcp-server/issues](https://github.com/exa-labs/exa-mcp-server/issues)
- API Keys: [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
---
## Environment Variables and API Configuration
### Related Pages
Related topics: [Quick Start Guide](#quick-start), [IDE Integration Guide](#ide-integration), [Tool Selection and Configuration](#tool-configuration)
Related Source Files
The following source files were used to generate this page:
- [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
# Environment Variables and API Configuration
The exa-mcp-server supports multiple authentication and configuration mechanisms to accommodate different deployment scenarios, including local development, hosted remote servers, and programmatic API usage.
## Overview
The MCP server extracts configuration from three sources with a strict priority order: request headers, URL query parameters, and environment variables. This layered approach allows the same deployment to serve different clients with varying access levels while maintaining a secure fallback for unauthenticated requests.
Source: [api/mcp.ts:1-10]()
```mermaid
graph TD
A[Incoming Request] --> B{Header: x-api-key?}
B -->|Yes| C[Use header API key]
B -->|No| D{OAuth Bearer Token?}
D -->|Yes| E[Validate JWT]
D -->|No| F{Plain Bearer API key?}
F -->|Yes| G[Use Bearer API key]
F -->|No| H{URL: exaApiKey param?}
H -->|Yes| I[Use URL parameter]
H -->|No| J{ENV: EXA_API_KEY?}
J -->|Yes| K[Use environment variable]
J -->|No| L[Use server fallback key
Free tier access]
style C fill:#90EE90
style G fill:#90EE90
style I fill:#90EE90
style K fill:#90EE90
style L fill:#FFE4B5
```
## Environment Variables
### Required Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `EXA_API_KEY` | Your Exa AI API key for search operations | No (server has fallback key) | Server-provided free tier key |
### Optional Variables
| Variable | Description | Values | Default |
|----------|-------------|--------|---------|
| `DEBUG` | Enable debug logging for troubleshooting | `true` / `false` | `false` |
### Setting the API Key
For local development with stdio transport, set the environment variable before running the server:
```bash
export EXA_API_KEY=your_api_key_here
npx exa-mcp-server
```
Or inline:
```bash
EXA_API_KEY=your_api_key_here npx exa-mcp-server
```
Source: [README.md:1-50]()
### Debug Mode
Enable verbose logging to troubleshoot connection issues or understand request flow:
```bash
DEBUG=true exa-mcp-server
```
When debug mode is active, the server logs:
- Request initialization details
- Analytics tracking status
- Tool registration information
- Configuration parsing results
Source: [src/mcp-handler.ts:1-50]()
## URL Query Parameter Configuration
The hosted remote MCP endpoint (`https://mcp.exa.ai/mcp`) accepts configuration via URL query parameters. This is the preferred method for remote MCP clients like Claude Code.
### Available Parameters
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `exaApiKey` | string | Your Exa API key | Server fallback key |
| `tools` | string | Comma-separated list of enabled tools | `web_search_exa,web_fetch_exa` |
| `debug` | boolean | Enable debug mode | `false` |
### Tool Selection Example
The community issue #48 highlighted that tool selection via URL parameters was working before a release but regressed. The current implementation supports tool selection through the `tools` parameter:
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
Source: [README.md:50-100]()
### Enabling Advanced Search
The `web_search_advanced_exa` tool is disabled by default. To enable it:
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
Source: [api/well-known-mcp-config.ts:1-30]()
## Request Header Configuration
For programmatic API usage, the server accepts configuration through HTTP headers:
| Header | Description | Priority |
|--------|-------------|----------|
| `x-api-key` | Exa API key | Highest (overrides all others) |
Example request with header authentication:
```bash
curl -X POST 'https://mcp.exa.ai/mcp' \
-H 'x-api-key: your_api_key_here' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```
Source: [api/mcp.ts:20-40]()
## Authentication Methods
The server supports three authentication tiers:
| Auth Method | Source | Access Level |
|-------------|--------|--------------|
| `api_key` | Header, Bearer token, URL param | Full (user-provided key) |
| `oauth` | OAuth Bearer JWT | Full (validated OAuth token) |
| `free_tier` | Server fallback key | Limited (uses server's rate limits) |
### OAuth JWT Validation
When a Bearer token is provided but fails OAuth validation (expired, invalid signature, wrong issuer/audience), the server sets `invalidOAuthJwt: true` in the request config and may reject the request.
Source: [api/mcp.ts:10-25]()
## Well-Known Configuration Schema
The server exposes a JSON Schema at `/.well-known/mcp-config` for MCP client discovery:
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "/.well-known/mcp-config",
"title": "Exa MCP Server Configuration",
"description": "Configuration for connecting to the Exa MCP server",
"x-query-style": "dot+bracket",
"type": "object",
"properties": {
"exaApiKey": {
"type": "string",
"title": "Exa API Key",
"description": "Your Exa AI API key for search operations (optional - server has a fallback key)"
},
"tools": {
"type": "string",
"title": "Enabled Tools",
"description": "Comma-separated list of tools to enable",
"x-available-values": ["web_search_exa", "web_search_advanced_exa", "web_fetch_exa"]
},
"debug": {
"type": "boolean",
"title": "Debug Mode",
"description": "Enable debug logging for troubleshooting",
"default": false
}
}
}
```
Access the schema via:
```bash
curl https://mcp.exa.ai/.well-known/mcp-config
```
Source: [api/well-known-mcp-config.ts:1-50]()
## Default Tool Configuration
### Enabled by Default
| Tool | Description |
| ---- | ----------- |
| `web_search_exa` | Search the web for any topic and get clean, ready-to-use content |
| `web_fetch_exa` | Get the full content of a specific webpage from a known URL |
### Off by Default
| Tool | Description |
| ---- | ----------- |
| `web_search_advanced_exa` | Advanced web search with full control over filters, domains, dates, and content options |
### Deprecated Tools (Still Available)
| Tool | Use Instead |
| ---- | ----------- |
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `people_search_exa` | `web_search_advanced_exa` |
| `linkedin_search_exa` | `web_search_advanced_exa` |
| `deep_researcher_start` | Research API |
| `deep_researcher_check` | Research API |
| `deep_search_exa` | `web_search_advanced_exa` |
Source: [src/mcp-handler.ts:50-80]()
## Request Context Metadata
Each request can include client metadata that gets tracked for analytics and debugging:
| Field | Description |
|-------|-------------|
| `exaSource` | Source identifier for the request |
| `mcpSessionId` | Unique session identifier |
| `mcpClient` | Client metadata (name, version, vendor) |
| `defaultSearchType` | Default search type (`auto` or `fast`) |
Source: [api/mcp.ts:15-30]()
## Configuration for Claude Code
For Claude Code users, configure the MCP in your settings:
### Using URL Parameters
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa"
```
### Using Environment Variables (Stdio)
In your MCP configuration file:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Source: [README.md:100-150]()
## Common Configuration Patterns
### Local Development with Stdio
```bash
# Set your API key
export EXA_API_KEY=your_key_here
# Run with debug logging
DEBUG=true npx exa-mcp-server
```
### Remote MCP with Specific Tools
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa
```
### Production Deployment with All Tools
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa&debug=false
```
## Troubleshooting
### API Key Issues
If you encounter 401 errors or rate limiting:
1. Verify your API key is valid at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
2. Ensure the key is passed correctly via header, URL param, or environment variable
3. Check that the key hasn't expired
### Tool Not Found Errors
If `web_search_advanced_exa` is not available:
1. Ensure it's included in your `tools` URL parameter
2. Restart your MCP client after changing configuration
### Debug Mode
Enable `DEBUG=true` to see detailed request/response logs:
```bash
DEBUG=true EXA_API_KEY=your_key npx exa-mcp-server
```
Source: [package.json:1-20]()
## Related Documentation
- [Exa MCP Documentation](https://docs.exa.ai/reference/exa-mcp)
- [Get Your Exa API Key](https://dashboard.exa.ai/api-keys)
- [Research API Reference](https://docs.exa.ai/reference/research/create-a-task)
---
## Common Issues and Troubleshooting
### Related Pages
Related topics: [Transport Layer (HTTP/SSE and STDIO)](#transport-layer), [Smithery Integration](#smithery-integration), [Tool Selection and Configuration](#tool-configuration)
Related Source Files
The following source files were used to generate this page:
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
# Common Issues and Troubleshooting
This page documents common issues encountered when using the Exa MCP Server, along with diagnostic steps and solutions. The troubleshooting guidance covers configuration problems, connection issues, transport layer errors, and API-related failures.
## Tool Configuration Issues
### Tools Not Appearing After Release
Following a new release, some users report that the tool selection configuration stops working as expected. This regression occurs when the configuration schema changes between versions.
**Symptoms:**
- Previously configured tools are not available
- MCP client shows fewer tools than expected
- Configuration changes have no effect
**Solution:**
Verify your configuration matches the current schema by using the well-known configuration endpoint:
```
https://mcp.exa.ai/.well-known/mcp-config
```
For Claude Code, remove the existing MCP configuration and reinstall:
```bash
claude mcp remove exa
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa"
```
**Source:** [src/mcp-handler.ts:1-25](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
### Enabling Advanced Tools
The `web_search_advanced_exa` tool is disabled by default and requires explicit enablement.
**Current tool status:**
| Tool | Enabled by Default | Requires Explicit Config |
|------|-------------------|-------------------------|
| `web_search_exa` | Yes | No |
| `web_fetch_exa` | Yes | No |
| `web_search_advanced_exa` | No | Yes |
Enable additional tools via URL parameter:
```
https://mcp.exa.ai/mcp?tools=web_search_advanced_exa
```
Multiple tools can be enabled:
```
https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
**Source:** [api/well-known-mcp-config.ts:1-30](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## HTTP Connection Issues
### 405 Method Not Allowed Error
Some MCP clients using standard Server-Sent Events (SSE) connections with HTTP GET receive a `405 Method Not Allowed` response.
**Affected clients:**
- Generic MCP clients using GET method for SSE
- Clients that do not support POST-based transport
**Working clients:**
- Claude Code (uses POST transport)
**Solution:**
Use a client that supports POST-based SSE transport, or configure your client to use the appropriate HTTP method. The hosted endpoint at `https://mcp.exa.ai/mcp` expects POST requests for SSE connections.
**Source:** Community issue [#86](https://github.com/exa-labs/exa-mcp-server/issues/86)
### Service Availability
Intermittent service unavailability has been reported at the hosted endpoint `https://mcp.exa.ai/mcp`.
**Symptoms:**
- Connection timeouts
- HTTP 500 or 503 errors
- Client reports service unavailable
**Diagnostic steps:**
1. Check the endpoint status directly:
```bash
curl -X POST https://mcp.exa.ai/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
```
2. Verify your network connectivity
3. Check for planned maintenance announcements
**Source:** Community issue [#108](https://github.com/exa-labs/exa-mcp-server/issues/108)
## STDIO Transport Issues
### Multiple Shebang Lines in Smithery Package
The npm package `exa-mcp-server` contains a build artifact issue where multiple shebang lines are added to `.smithery/index.cjs`, causing stdio transport failures.
**Error message:**
```
/usr/bin/env node: No such file or directory
```
**Cause:**
The build process using esbuild adds a shebang line (`#!/usr/bin/env node`) during bundling, and when combined with Smithery's own shebang, results in malformed output.
**Solution:**
1. **Use the remote MCP endpoint instead of npm:**
```
https://mcp.exa.ai/mcp
```
2. **Alternative fix for Smithery users:**
Use the non-smithery build or manually remove the duplicate shebang from the packaged file.
3. **Local development fix:**
```bash
npm install
npm run build:stdio
```
The build command generates `dist/stdio.cjs` with proper shebang handling:
```json
// package.json
{
"scripts": {
"build:stdio": "esbuild src/stdio-cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/stdio.cjs --banner:js=\"#!/usr/bin/env node\" && chmod +x dist/stdio.cjs"
}
}
```
**Source:** Community issue [#65](https://github.com/exa-labs/exa-mcp-server/issues/65)
## API Key Issues
### Missing or Invalid API Key
When using local installation with `web_search_advanced_exa` or `deep_search_exa`, an API key is required.
**Configuration methods:**
| Method | Description |
|--------|-------------|
| URL parameter | `?exaApiKey=YOUR_KEY` |
| Environment variable | `EXA_API_KEY=your_api_key` |
| Remote endpoint | Uses server's fallback key (limited) |
**Obtain an API key:**
Visit [https://dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
**Remote endpoint limitation:**
The hosted MCP server (`https://mcp.exa.ai/mcp`) includes a fallback API key for basic functionality. However, for production use or high-volume requests, configure your own key.
**Source:** [api/well-known-mcp-config.ts:10-20](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Deep Search Timeout Issues
### Search Taking Too Long
Deep search operations have variable completion times depending on the search type selected.
**Expected timeouts:**
| Type | Expected Duration | Use Case |
|------|------------------|----------|
| `deep` | 4-12 seconds | Fast deep search |
| `deep-reasoning` | 12-50 seconds | Thorough research with reasoning |
**Parameters:**
```typescript
{
objective: string; // Required: What to search for
search_queries?: string[]; // Optional: Up to 5 keyword queries
type?: 'deep' | 'deep-reasoning';
numResults?: number;
highlightMaxCharacters?: number;
}
```
**Note:** The `type` parameter is optional. When omitted, `deep` is used as the default.
**Source:** [src/tools/deepSearch.ts:1-30](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
## Category Filter Errors
### 400 Bad Request with Category Filters
When using `category: "company"` with certain parameters, the API returns 400 errors.
**Restricted parameters for `category: "company"`:**
- `includeDomains` / `excludeDomains`
- `startPublishedDate` / `endPublishedDate`
- `startCrawlDate` / `endCrawlDate`
**Working combinations:**
| Category | Domain Filters | Date Filters | Text Filters |
|----------|---------------|--------------|--------------|
| `company` | ❌ | ❌ | ✅ |
| `news` | ✅ | ✅ | ✅ |
| `research paper` | ✅ | ✅ | ✅ |
| `personal site` | ✅ | ✅ | ✅ |
| `people` | ❌ | ❌ | ❌ |
| `auto` (no category) | ✅ | ✅ | ✅ |
**Array size restriction:**
`includeText` and `excludeText` only support **single-item arrays**. Multi-item arrays cause 400 errors across all categories.
**Source:** [src/types.ts:1-50](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
## Deprecated Tool Warnings
Several tools are deprecated but remain available for backwards compatibility.
| Deprecated Tool | Replacement | Status |
|----------------|-------------|--------|
| `get_code_context_exa` | `web_search_exa` | Deprecated |
| `company_research_exa` | `web_search_advanced_exa` | Deprecated |
| `crawling_exa` | `web_fetch_exa` | Deprecated |
| `people_search_exa` | `web_search_advanced_exa` | Deprecated |
| `linkedin_search_exa` | `web_search_advanced_exa` | Deprecated |
| `deep_researcher_start` | Research API | Deprecated |
| `deep_researcher_check` | Research API | Deprecated |
| `deep_search_exa` | `web_search_advanced_exa` | Deprecated |
**Migration path:**
Replace deprecated tool calls with their recommended alternatives:
```javascript
// Before (deprecated)
{
"name": "get_code_context_exa",
"arguments": { "query": "React hooks example" }
}
// After (recommended)
{
"name": "web_search_exa",
"arguments": { "query": "React hooks example" }
}
```
**Source:** [src/mcp-handler.ts:5-15](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Debug Mode
Enable debug logging to troubleshoot connection and request issues.
**Configuration:**
```
https://mcp.exa.ai/mcp?debug=true
```
Debug mode outputs:
- Request/response logging
- Error stack traces
- Internal state changes
**Source:** [api/well-known-mcp-config.ts:25-30](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Getting Help
If issues persist after trying the above solutions:
1. **Check existing issues:** [github.com/exa-labs/exa-mcp-server/issues](https://github.com/exa-labs/exa-mcp-server/issues)
2. **Review documentation:** [docs.exa.ai/reference/exa-mcp](https://docs.exa.ai/reference/exa-mcp)
3. **API status:** [status.exa.ai](https://status.exa.ai)
---
## Smithery Integration
### Related Pages
Related topics: [Transport Layer (HTTP/SSE and STDIO)](#transport-layer), [Common Issues and Troubleshooting](#common-issues), [IDE Integration Guide](#ide-integration)
Related Source Files
The following source files were used to generate this page:
- [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/stdio.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# Smithery Integration
Smithery is a platform that enables one-click installation of Model Context Protocol (MCP) servers into AI coding assistants like Cursor, Claude Code, and other MCP-compatible tools. The exa-mcp-server provides native integration with Smithery, allowing users to easily discover, install, and configure the Exa search capabilities without manual setup.
## Overview
Smithery acts as a registry and installation bridge for MCP servers. When a user installs an MCP server through Smithery, the platform generates configuration files and handles the transport layer setup automatically. For the exa-mcp-server, Smithery integration is particularly important because it provides a simplified path to enable Exa's web search, web crawling, and advanced search capabilities in AI assistants.
The integration enables two primary deployment scenarios:
1. **Smithery CLI Installation** — Using Smithery's command-line interface to generate MCP configuration for local AI tools
2. **Smithery Registry Discovery** — Publishing and discovering the exa-mcp-server through Smithery's web interface
Source: [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
## Architecture
The Smithery integration for exa-mcp-server involves several components working together to provide seamless installation and operation.
```mermaid
graph TD
A[User] -->|Installs via Smithery| B[Smithery Platform]
B -->|Generates config| C[.smithery/index.cjs]
C -->|stdio transport| D[AI Coding Assistant]
D -->|MCP Protocol| E[exa-mcp-server]
E -->|Exa API| F[Exa.ai Services]
G[npm Registry] -->|npm install| H[exa-mcp-server Package]
H -->|uses| I[dist/stdio.cjs]
```
### Build Output
The npm package produces a Smithery-compatible entry point at `.smithery/index.cjs`. This file is the executable that Smithery uses when installing the server via stdio transport.
Source: [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json#L8-L9)
```json
{
"name": "exa-mcp-server",
"version": "3.2.1",
"bin": {
"exa-mcp-server": "dist/stdio.cjs"
}
}
```
## Known Issue: Multiple Shebang Lines
There is a documented bug affecting Smithery integration (Issue #65) where the `.smithery/index.cjs` file contains multiple shebang lines, causing the stdio transport to fail.
### Problem Description
During the build process, additional shebang lines (`#!/usr/bin/env node`) are prepended to the output file. This results in invalid JavaScript that breaks the Node.js runtime when Smithery attempts to execute the server via stdio transport.
### Error Behavior
When this bug occurs, the MCP server fails to start with an error indicating invalid syntax or unexpected characters at the beginning of the file.
### Workaround
Until this issue is resolved, users experiencing stdio transport failures can:
1. Manually edit the `.smithery/index.cjs` file to remove duplicate shebang lines
2. Use the HTTP transport endpoint instead: `https://mcp.exa.ai/mcp`
3. Install directly via npm without Smithery
Source: [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
## Installation via Smithery
### Prerequisites
- Node.js 20 or later
- An Exa API key (optional for hosted remote MCP, required for full functionality)
### Standard Smithery Configuration
When Smithery generates a configuration for the exa-mcp-server, the resulting JSON structure follows the standard MCP client format:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Source: [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
### Smithery CLI Installation
Using Smithery's CLI tool, you can install the exa-mcp-server with a single command:
```bash
npx -y @smithery/cli install exa-mcp-server
```
This command downloads the package, generates the appropriate configuration, and sets up the transport layer.
## Available Tools via Smithery
When installed through Smithery, the following tools are available by default:
| Tool | Description | Enabled |
|------|-------------|---------|
| `web_search_exa` | Search the web for any topic and get clean, ready-to-use content | Yes |
| `web_fetch_exa` | Get the full content of a specific webpage from a known URL | Yes |
| `web_search_advanced_exa` | Advanced web search with full control over filters, domains, dates, and content options | No |
To enable additional tools, include the `tools` parameter in your Smithery configuration:
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server", "--tools", "web_search_exa,web_search_advanced_exa,web_fetch_exa"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
Source: [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Stdio Transport Configuration
The Smithery integration relies on the stdio transport mechanism for communication between the MCP client and the exa-mcp-server.
### How Stdio Transport Works
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as exa-mcp-server
participant ExaAPI as Exa API
Client->>Server: Start process (stdio)
Server->>Client: Initialize handshake
Client->>Server: JSON-RPC request
Server->>ExaAPI: Search request
ExaAPI->>Server: Search results
Server->>Client: JSON-RPC response
```
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `EXA_API_KEY` | Your Exa API key for search operations | No (server has fallback key) |
| `DEBUG` | Enable debug logging for troubleshooting | No |
Source: [src/stdio.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio.ts)
## Configuration Schema
Smithery supports the well-known MCP configuration endpoint that exposes available configuration options:
| Parameter | Type | Description |
|-----------|------|-------------|
| `exaApiKey` | string | Your Exa AI API key for search operations (optional) |
| `tools` | string | Comma-separated list of tools to enable |
| `debug` | boolean | Enable debug logging |
Source: [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## Remote MCP Alternative
For users encountering issues with the Smithery/stdio integration, an alternative is to use the hosted remote MCP endpoint:
```
https://mcp.exa.ai/mcp
```
This endpoint supports HTTP transport and can be configured directly in MCP clients without requiring the npm package installation.
Source: [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
## Tool Categories Supported
When installed via Smithery, the exa-mcp-server supports category-based searches through the `web_search_advanced_exa` tool:
| Category | Use Case | Available Filters |
|----------|----------|-------------------|
| `company` | Company information, news, homepages | Limited (no domain/date filters) |
| `research paper` | Academic papers, publications | Full filter support |
| `news` | Press coverage, announcements | Full filter support |
| `people` | LinkedIn profiles | None (public data only) |
| `financial report` | SEC filings, earnings reports | Full filter support |
| `personal site` | Blogs, portfolios | Full filter support |
Source: [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
## Troubleshooting
### Smithery Installation Fails
1. Verify Node.js version is 20 or later
2. Clear npm cache: `npm cache clean --force`
3. Try direct npm installation instead
### Stdio Transport Errors
If you encounter errors like `shebang line issues` or `unexpected token`:
1. The `.smithery/index.cjs` file may have build artifacts
2. Use HTTP transport instead: `https://mcp.exa.ai/mcp`
3. Report the issue at https://github.com/exa-labs/exa-mcp-server/issues/65
### Tools Not Available
Ensure the `tools` parameter includes the required tools:
```
exa?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
Source: [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## Related Documentation
- [Exa MCP Documentation](https://docs.exa.ai/reference/exa-mcp)
- [Get Your Exa API Key](https://dashboard.exa.ai/api-keys)
- [GitHub Repository](https://github.com/exa-labs/exa-mcp-server)
---
---
## Pitfall Log
Project: exa-labs/exa-mcp-server
Summary: Found 8 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.
## 1. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_814fe712ae6543ce9f086d0fb4433748 | https://github.com/exa-labs/exa-mcp-server/issues/334
## 2. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server
## 3. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server
## 4. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server
## 5. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server
## 6. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_77ed9b7438ae4eafb0ed10e4ed50639a | https://github.com/exa-labs/exa-mcp-server/issues/347
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server
## 8. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server