Related Pages

Related topics: Quick Start Guide, MCP Protocol Implementation

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

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.

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

Source: README.md

Architecture

The server is built on the Model Context Protocol SDK and provides multiple transport mechanisms for different use cases.

Transport Options

graph TD
    subgraph "Transport Types"
        HTTP[HTTP/SSE<br/>Remote MCP]
        STDIO[STDIO<br/>Local npm package]
    end
    
    HTTP --> Preferred[Preferred for most users]
    STDIO --> Local[Local development & self-hosting]
    
    style HTTP fill:#c8e6c9
    style STDIO fill:#ffe0b2

Source: package.json:7

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

Available Tools

The server provides the following tools, with varying default states:

Default Enabled Tools

Off by Default

Deprecated Tools

The following tools are deprecated but still available for backwards compatibility:

Source: 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

Available Tool Values

Source: api/well-known-mcp-config.ts:5-7

Connection Methods by Client

Claude Code

claude mcp add --transport http exa https://mcp.exa.ai/mcp

Or with specific tools:

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:

{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

Local npm Installation

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

Source: README.md

Error Handling

The server implements robust error handling with automatic retry logic and user-friendly messages.

Rate Limit Handling

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

Retry Logic

The server retries on transient server errors (5xx) with exponential backoff:

Source: src/utils/errorHandler.ts:10

Known Issues and Limitations

Community-Reported Issues

Source: Community Issues #86, #108, #65

Advanced Search Parameters

The web_search_advanced_exa tool supports extensive filtering options:

Core Parameters

Category Filter

Use category to narrow results:

Domain Filtering

Date Filtering (ISO 8601)

Text Filtering

Important: includeText and excludeText only support single-item arrays. Multi-item arrays cause 400 errors.

Source: 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

Related Resources

Related Pages

Related topics: Introduction to Exa MCP Server, IDE Integration Guide, Environment Variables and API Configuration

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:

Source: package.json:4

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

Local npm Installation

For production environments or custom configurations, install the package globally:

npm install -g exa-mcp-server

The package provides a CLI binary named exa-mcp-server:

exa-mcp-server --help

Source: package.json:7-8

Local Source Installation

Clone and build from source for development or customization:

git clone https://github.com/exa-labs/exa-mcp-server.git
cd exa-mcp-server
npm install
npm run build

Source: package.json:11

Client Configuration

Claude Code Configuration

Add the Exa MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

For Remote MCP (HTTP Transport):

{
  "mcpServers": {
    "exa": {
      "command": "claude",
      "args": ["mcp", "add", "--transport", "http", "exa", "https://mcp.exa.ai/mcp"]
    }
  }
}

Source: README.md

Cursor Configuration

For Cursor editor, add to your MCP settings:

{
  "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

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

Deprecated Tools

The following tools are deprecated but still available for backwards compatibility:

Source: src/mcp-handler.ts:24-35

Configuration Parameters

Configure the MCP server using URL query parameters:

Configuration Schema

The server exposes a JSON Schema at /.well-known/mcp-config for client discovery:

{
  "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

Environment Variables

For local installations, configure using environment variables:

EXA_API_KEY=your_api_key_here

Create an .env file based on env.example for local development.

Basic Usage Examples

Web Search

// Using web_search_exa
{
  "query": "latest AI research developments 2024",
  "numResults": 10
}

// Using category filters
{
  "query": "category:company Anthropic funding",
  "numResults": 20
}

Source: src/tools/webSearch.ts:1-20

Web Fetch

// Get full content from a URL
{
  "url": "https://example.com/article"
}

Advanced Search

{
  "query": "LLM training efficiency",
  "category": "research paper",
  "includeDomains": ["arxiv.org", "openreview.net"],
  "numResults": 20,
  "type": "deep"
}

Source: src/types.ts:1-20

Architecture Overview

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:

Note: When using category: company, domain and date filters are not available.

Source: 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:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"]
    }
  }
}

Source: package.json:7

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 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:

DEBUG=true exa-mcp-server

Source: api/well-known-mcp-config.ts

Getting Help

• Documentation: docs.exa.ai/reference/exa-mcp
• API Keys: dashboard.exa.ai/api-keys
• GitHub Issues: github.com/exa-labs/exa-mcp-server/issues

Related Pages

Related topics: Transport Layer (HTTP/SSE and STDIO), Search Tools Reference

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:

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

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

Disabled by Default

Deprecated Tools (Still Available)

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

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:

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

Sanitization

The metadata handling includes automatic sanitization of control characters and truncation to prevent buffer overflow:

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

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

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

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

Search Type Options

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-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

import { retryWithBackoff, formatToolError } from "../utils/errorHandler.js";

Retry Strategy

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

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

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

claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"

npm Package

npm install exa-mcp-server

Environment variable configuration:

{
  "exa-mcp-server": {
    "command": "npx",
    "args": ["-y", "exa-mcp-server"],
    "env": {
      "EXA_API_KEY": "your_api_key"
    }
  }
}

Related Issues

Related Pages

Related topics: MCP Protocol Implementation, Common Issues and Troubleshooting, Smithery Integration

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)

Architecture Diagram

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

Source: api/well-known-mcp-config.ts:1-50

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 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

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:

{
  "$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

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

npm install -g exa-mcp-server

Or run directly with npx:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

Source: package.json:20-28

Entry Points

The package.json defines the binary entry point:

{
  "bin": {
    "exa-mcp-server": "dist/stdio.cjs"
  },
  "module": "./src/stdio.ts"
}

Source: package.json:20-28

Build Process

The STDIO transport requires compilation to CommonJS for executable distribution:

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

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

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

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):

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

Client Metadata Handling

Both transports support MCP client metadata for session tracking and analytics:

interface McpClientMetadata {
  source?: string;
  sessionId?: string;
  clientInfo?: {
    name?: string;
    title?: string;
    version?: string;
  };
  userAgent?: string;
}

Source: src/utils/mcpClientMetadata.ts:10-17

Session TTL

Client sessions are tracked with a 24-hour TTL:

const MCP_CLIENT_SESSION_TTL_SECONDS = 24 * 60 * 60; // 24 hours

Source: src/utils/mcpClientMetadata.ts:3

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):

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

HTTP/SSE (Remote):

claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa"

Cursor Configuration

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

VS Code Configuration

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

Environment Variables

Related Pages

Related topics: Tool Selection and Configuration, Quick Start Guide

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.

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:

Source: src/mcp-handler.ts:1-50

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:

{
  "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:

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

Request Hint Annotations:

The tool declares the following hints for MCP clients:

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:

Category Types:

Source: src/types.ts:1-100

Domain Filtering:

Date Filtering:

Text Filtering:

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

Category-Specific Filter Restrictions:

When using category: "company", the following parameters cause 400 errors:

• includeDomains / excludeDomains
• startPublishedDate / endPublishedDate
• startCrawlDate / endCrawlDate

Content Extraction Options:

web_fetch_exa

Retrieves full content from specific URLs. Used when you have known URLs and want the complete page content.

Parameters:

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:

Search Depth Modes:

Source: src/tools/deepSearch.ts:1-50

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

{
  "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:

Source: src/mcp-handler.ts:1-50

Response Format

All search tools return results in a standardized format with the following structure:

interface ExaSearchResponse {
  requestId: string;
  autopromptString?: string;
  autoDate?: string;
  resolvedSearchType: string;
  context?: string;
  output?: {
    content: string | Record<string, unknown>;
    grounding?: Array<{
      field: string;
      citations: Array<{ url: string; title: string }>;
      confidence: string;
    }>;
  };
  statuses?: ExaSearchStatus[];
  results: ExaSearchResult[];
  searchTime?: number;
  costDollars?: ExaCostDollars;
}

Individual Result Structure:

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<string, unknown>[];
  extras?: {
    links?: string[];
    imageLinks?: string[];
  };
  subpages?: ExaSearchResult[];
}

Source: src/types.ts:200-350

Common Usage Patterns

Basic Web Search

web_search_exa {
  "query": "latest developments in quantum computing",
  "numResults": 10
}

Company Research with Filters

web_search_advanced_exa {
  "query": "AI infrastructure startups San Francisco",
  "category": "company",
  "numResults": 20,
  "type": "auto"
}

News Search with Date Range

web_search_advanced_exa {
  "query": "Anthropic AI safety",
  "category": "news",
  "numResults": 15,
  "startPublishedDate": "2024-01-01"
}

Research Paper Search

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

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

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

Related Pages

Related topics: Search Tools Reference, Environment Variables and API Configuration

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

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:

Source: src/mcp-handler.ts:29-45

Registry Implementation

The tool registry is defined as a constant object in src/mcp-handler.ts:

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

Source: api/well-known-mcp-config.ts:16-43

Configuration Schema Definition

{
  "$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

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:

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

Claude Code Configuration

For Claude Code, add the following to your MCP configuration:

{
  "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

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

Tool Registration Process

Registration Flow

When a tool is enabled, the registration process follows this pattern:

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:

// 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

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:

Source: src/mcp-handler.ts:29-45

Basic Web Search Tool

The web_search_exa tool provides straightforward web search:

{
  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:

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:

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:

{
  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

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<string, unknown>[];
  extras?: {
    links?: string[];
    imageLinks?: string[];
  };
  subpages?: ExaSearchResult[];
}

Source: src/types.ts:41-68

ExaSearchResponse

interface ExaSearchResponse {
  requestId: string;
  autopromptString?: string;
  autoDate?: string;
  resolvedSearchType: string;
  context?: string;
  output?: {
    content: string | Record<string, unknown>;
    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:

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

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

Related Pages

Related topics: Quick Start Guide, Environment Variables and API Configuration, Smithery Integration

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

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

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:

{
  "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:

{
  "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):

claude mcp add --transport http exa "https://mcp.exa.ai/mcp"

Stdio Transport (Local Installation):

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

URL Parameter Configuration

Example Configured Endpoint

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

Environment Variables

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

Tool Selection

Default Tools

The following tools are enabled by default without additional configuration:

Advanced Tools

These tools are disabled by default and must be explicitly enabled via the tools parameter:

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

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

Available Skills

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:

npm install -g exa-mcp-server

Build Output

The package builds to dist/stdio.cjs with the following entry point:

{
  "bin": {
    "exa-mcp-server": "dist/stdio.cjs"
  }
}

Source: 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
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:

Source: api/mcp.ts:21

Architecture Overview

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

Tool Not Available

Stdio Transport Issues

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

# 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
• GitHub Issues: github.com/exa-labs/exa-mcp-server/issues
• API Keys: dashboard.exa.ai/api-keys

Related Pages

Related topics: Quick Start Guide, IDE Integration Guide, Tool Selection and Configuration

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

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<br/>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

Optional Variables

Setting the API Key

For local development with stdio transport, set the environment variable before running the server:

export EXA_API_KEY=your_api_key_here
npx exa-mcp-server

Or inline:

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:

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

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:

Example request with header authentication:

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:

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:

{
  "$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:

curl https://mcp.exa.ai/.well-known/mcp-config

Source: api/well-known-mcp-config.ts:1-50

Default Tool Configuration

Enabled by Default

Off by Default

Deprecated Tools (Still Available)

Source: src/mcp-handler.ts:50-80

Request Context Metadata

Each request can include client metadata that gets tracked for analytics and debugging:

Source: api/mcp.ts:15-30

Configuration for Claude Code

For Claude Code users, configure the MCP in your settings:

Using URL Parameters

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:

{
  "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

# 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
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:

DEBUG=true EXA_API_KEY=your_key npx exa-mcp-server

Source: package.json:1-20

Related Documentation

• Exa MCP Documentation
• Get Your Exa API Key
• Research API Reference

Related Pages

Related topics: Transport Layer (HTTP/SSE and STDIO), Smithery Integration, Tool Selection and Configuration

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:

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

Enabling Advanced Tools

The web_search_advanced_exa tool is disabled by default and requires explicit enablement.

Current tool status:

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

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

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:

``bash curl -X POST https://mcp.exa.ai/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' ``

1. Check the endpoint status directly:

1. Verify your network connectivity

1. Check for planned maintenance announcements

Source: Community issue #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:

`` https://mcp.exa.ai/mcp ``

1. Use the remote MCP endpoint instead of npm:

1. Alternative fix for Smithery users:

Use the non-smithery build or manually remove the duplicate shebang from the packaged file.

``bash npm install npm run build:stdio ``

1. Local development fix:

The build command generates dist/stdio.cjs with proper shebang handling:

// 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

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:

Obtain an API key: Visit 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

Deep Search Timeout Issues

Search Taking Too Long

Deep search operations have variable completion times depending on the search type selected.

Expected timeouts:

Parameters:

{
  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

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:

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

Deprecated Tool Warnings

Several tools are deprecated but remain available for backwards compatibility.

Migration path:

Replace deprecated tool calls with their recommended alternatives:

// 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

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

Getting Help

If issues persist after trying the above solutions:

1. Check existing issues: github.com/exa-labs/exa-mcp-server/issues
2. Review documentation: docs.exa.ai/reference/exa-mcp
3. API status: status.exa.ai

Related Pages

Related topics: Transport Layer (HTTP/SSE and STDIO), Common Issues and Troubleshooting, IDE Integration Guide

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

Architecture

The Smithery integration for exa-mcp-server involves several components working together to provide seamless installation and operation.

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

{
  "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

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:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

Source: npm.readme.md

Smithery CLI Installation

Using Smithery's CLI tool, you can install the exa-mcp-server with a single command:

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:

To enable additional tools, include the tools parameter in your Smithery configuration:

{
  "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

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

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

Source: src/stdio.ts

Configuration Schema

Smithery supports the well-known MCP configuration endpoint that exposes available configuration options:

Source: 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

Tool Categories Supported

When installed via Smithery, the exa-mcp-server supports category-based searches through the web_search_advanced_exa tool:

Source: 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

Related Documentation

• Exa MCP Documentation
• Get Your Exa API Key
• GitHub Repository

Doramagic Pitfall Log

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
• 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.
• Recommended 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
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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
• 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.
• Recommended 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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
• 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.
• Recommended 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
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using exa-mcp-server with real data or production workflows.

• Proposal: Free AI Agent identity verification for Exa MCP - github / github_issue
• Remote MCP docs show API key in URL query string - github / github_issue
• Capability evidence risk requires verification - GitHub / issue