概述

exa-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于将 AI 助手连接到 Exa 的搜索能力。项目由 Exa Labs 开发维护，提供实时网络搜索、内容抓取和高级搜索功能。

核心能力：

• Web 搜索：通用的网络信息检索
• 高级搜索：支持完整的过滤参数配置
• Web 内容抓取：从特定 URL 提取完整内容
• 深度搜索：基于 AI 推理的深度搜索模式

资料来源：README.md

项目信息

资料来源：package.json

架构设计

系统架构图

graph TD
    subgraph "MCP 客户端"
        A[Claude Code / Cursor / VS Code]
    end
    
    subgraph "exa-mcp-server"
        B[MCP Handler<br/>工具路由分发]
        C[Web Search Tool]
        D[Web Fetch Tool]
        E[Deep Search Tool]
    end
    
    subgraph "Exa API"
        F[Exa Search API]
        G[Exa Contents API]
    end
    
    A -->|MCP Protocol| B
    B -->|web_search_exa| C
    B -->|web_fetch_exa| D
    B -->|web_search_advanced_exa| E
    C --> F
    D --> G
    E --> F
    E --> G

工具配置架构

项目支持通过 URL 参数动态配置启用的工具，配置遵循 /.well-known/mcp-config 规范：

graph LR
    A[URL 参数] --> B[exaApiKey]
    A --> C[tools]
    A --> D[debug]
    B --> E[API 密钥配置]
    C --> F[工具列表配置]
    D --> G[调试模式开关]

资料来源：api/well-known-mcp-config.ts

可用工具

默认启用的工具

资料来源：README.md

可选工具

已废弃工具（保持向后兼容）

资料来源：src/mcp-handler.ts

搜索类别支持

高级搜索工具支持多种搜索类别，适用于不同的搜索场景：

通用限制：

• includeText 和 excludeText 仅支持单元素数组，多元素数组会导致 400 错误

资料来源：README.md

数据类型定义

搜索请求类型

interface ExaSearchRequest {
  query: string;
  category?: 'company' | 'research paper' | 'news' | 'pdf' | 'github' | 'personal site' | 'people' | 'financial report';
  includeDomains?: string[];
  excludeDomains?: string[];
  startPublishedDate?: string;
  endPublishedDate?: string;
  startCrawlDate?: string;
  endCrawlDate?: string;
  includeText?: string[];
  excludeText?: string[];
  contents: {
    text?: { maxCharacters?: number; } | boolean;
    context?: { maxCharacters?: number; } | boolean;
    summary?: { query?: string; } | boolean;
    highlights?: {
      maxCharacters?: number;
      numSentences?: number;
      highlightsPerUrl?: number;
      query?: string;
    };
  };
}

搜索结果类型

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;
  subpages?: ExaSearchResult[];
}

搜索响应类型

interface ExaSearchResponse {
  requestId: string;
  resolvedSearchType: string;
  results: ExaSearchResult[];
  searchTime?: number;
  costDollars?: {
    total: number;
    search?: Record<string, number>;
    contents?: Record<string, number>;
  };
}

资料来源：src/types.ts

安装与配置

远程 MCP（推荐）

使用 Exa 托管的远程 MCP 服务器，无需本地安装 API 密钥：

https://mcp.exa.ai/mcp

本地安装

npm install exa-mcp-server

Claude Code 配置示例

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

启用高级工具

通过 URL 参数启用额外的工具：

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

配置参数说明

资料来源：api/well-known-mcp-config.ts

使用示例

基础 Web 搜索

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

高级搜索 - 公司研究

web_search_advanced_exa {
  "query": "Anthropic funding rounds valuation 2024",
  "category": "company",
  "numResults": 20,
  "type": "auto"
}

高级搜索 - 学术论文

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

内容抓取

web_fetch_exa {
  "url": "https://example.com/article",
  "contents": {
    "text": true,
    "summary": {
      "query": "Extract key findings and methodology"
    }
  }
}

资料来源：src/tools/webSearch.ts

社区反馈与已知问题

工具选择回归问题 (#48)

社区反馈在新版本发布后，通过配置选择可用工具的方式发生了变化。建议用户使用 URL 参数 tools 来显式指定启用的工具列表。

HTTP GET 方法兼容性 (#86)

远程 MCP 端点 https://mcp.exa.ai/mcp 对标准的 Server-Sent Events (SSE) GET 请求返回 405 Method Not Allowed 错误。部分客户端（如 Claude Code）使用 POST 方法可以正常连接。

构建问题 (#65)

npm 包在通过 stdio transport 运行时，由于 .smithery/index.cjs 文件中添加了多个 shebang 行导致失败。

服务可用性 (#108)

社区报告了 mcp.exa.ai/mcp 服务暂时不可用的情况。

项目链接

概述

本指南涵盖 exa-mcp-server 的所有安装方式，包括远程 MCP 服务器连接（推荐方式）和本地 npm 包安装两种方案。

• 远程 MCP 服务器：无需安装，直接通过 https://mcp.exa.ai/mcp 端点连接
• 本地安装：通过 npm 包 exa-mcp-server 在本地运行，支持 stdio 传输协议

[!NOTE]

推荐使用远程 MCP 服务器方式，配置更简单且始终保持最新版本。

架构概览

graph TB
    subgraph 客户端层
        AI[AI 助手 / Claude Code]
        MCPClient[MCP 客户端]
    end
    
    subgraph 传输层
        HTTP[HTTP/SSE 传输]
        STDIO[stdio 传输]
    end
    
    subgraph 服务层
        MCPServer[MCP 服务器核心]
        Handler[MCP Handler]
        Tools[工具注册表]
    end
    
    subgraph 业务层
        WebSearch[web_search_exa]
        AdvancedSearch[web_search_advanced_exa]
        WebFetch[web_fetch_exa]
        DeepSearch[deep_search_exa]
    end
    
    subgraph 外部服务
        ExaAPI[Exa API]
        RemoteEndpoint[远程 MCP 端点<br/>mcp.exa.ai]
    end
    
    AI --> MCPClient
    MCPClient --> HTTP
    MCPClient --> STDIO
    HTTP --> MCPServer
    STDIO --> MCPServer
    MCPServer --> Handler
    Handler --> Tools
    Tools --> WebSearch
    Tools --> AdvancedSearch
    Tools --> WebFetch
    Tools --> DeepSearch
    WebSearch --> ExaAPI
    AdvancedSearch --> ExaAPI
    WebFetch --> ExaAPI
    DeepSearch --> ExaAPI
    RemoteEndpoint --> ExaAPI

核心组件

传输层

Exa MCP Server 支持两种 MCP 传输协议：

HTTP/SSE 传输：通过 Server-Sent Events 实现服务器推送，适合云端部署场景。社区 issue #86 指出部分 MCP 客户端使用 GET 方法连接时会收到 405 错误，这是因为服务端仅支持 POST 方法的 SSE 连接。

stdio 传输：通过标准输入输出进行 JSON-RPC 通信，适合本地集成和调试。

MCP Handler 模块

MCP Handler 是服务器的核心调度器，负责：

• 工具注册与管理
• 请求路由与响应格式化
• API Key 验证
• 工具选择与启用控制

graph LR
    Request[入站请求] --> Parse[JSON-RPC 解析]
    Parse --> Route{工具路由}
    Route -->|web_search_exa| WS[webSearch.ts]
    Route -->|web_search_advanced_exa| WAS[webSearch.ts]
    Route -->|web_fetch_exa| WF[webFetch.ts]
    Route -->|deep_search_exa| DS[deepSearch.ts]
    WS --> ExaAPI1[Exa API]
    WAS --> ExaAPI2[Exa API]
    WF --> ExaAPI3[Exa API]
    DS --> ExaAPI4[Exa API]
    ExaAPI1 --> Format1[结果格式化]
    ExaAPI2 --> Format2[结果格式化]
    ExaAPI3 --> Format3[结果格式化]
    ExaAPI4 --> Format4[结果格式化]
    Format1 --> Response[JSON-RPC 响应]
    Format2 --> Response
    Format3 --> Response
    Format4 --> Response

工具注册在 src/mcp-handler.ts 中定义：

'web_search_exa': { name: 'Web Search', description: 'Search the web for any topic', enabled: true },
'web_search_advanced_exa': { name: 'Advanced Web Search', description: 'Advanced search with filters', enabled: false },
'web_fetch_exa': { name: 'Web Crawling', description: 'Extract content from specific URLs', enabled: true }

资料来源：src/mcp-handler.ts

工具体系

工具分类

搜索工具参数架构

基础搜索请求类型定义 (src/types.ts)：

interface ExaSearchRequest {
  query: string;
  category?: 'company' | 'research paper' | 'news' | 'pdf' | 
           'github' | 'personal site' | 'people' | 'financial report';
  includeDomains?: string[];      // 包含的域名
  excludeDomains?: string[];       // 排除的域名
  startPublishedDate?: string;     // ISO 8601 格式
  endPublishedDate?: string;
  startCrawlDate?: string;
  endCrawlDate?: string;
  includeText?: string[];          // 必须包含的文本
  excludeText?: string[];          // 排除包含的文本
  numResults?: number;
  contents: {
    text?: { maxCharacters?: number } | boolean;
    context?: { maxCharacters?: number } | boolean;
    summary?: { query?: string } | boolean;
    highlights?: { ... };
  };
}

资料来源：src/types.ts

Category 分类限制

graph TB
    A{选择 Category} --> B{category: company}
    A --> C{category: people}
    A --> D{无 category<br/>或 news}
    A --> E{category:<br/>research paper}
    
    B --> B1[支持]
    B1 --> B2[✓ numResults]
    B1 --> B3[✓ type]
    B1 --> B4[✓ 分类特定元数据]
    B1 --> B5[✗ includeDomains]
    B1 --> B6[✗ excludeDomains]
    B1 --> B7[✗ startPublishedDate]
    B1 --> B8[✗ endPublishedDate]
    
    C --> C1[支持]
    C1 --> C2[✓ numResults]
    C1 --> C3[✓ 公开 LinkedIn]
    C1 --> C4[✗ 其他过滤参数]
    
    D --> D1[支持]
    D1 --> D2[✓ 全部过滤参数]
    D1 --> D3[✓ 域名过滤]
    D1 --> D4[✓ 日期过滤]
    
    E --> E1[支持]
    E1 --> E2[✓ 全部过滤参数]
    E1 --> E3[✓ arXiv/openreview]

通用限制：includeText 和 excludeText 仅支持单元素数组，多元素数组会导致 400 错误。

配置体系

URL 参数配置（HTTP 传输）

远程 MCP 端点支持通过 URL 查询参数配置：

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

默认启用工具：web_search_exa, web_fetch_exa

完整可用工具：web_search_exa, web_search_advanced_exa, web_fetch_exa

配置发现机制

服务端在 /.well-known/mcp-config 路径暴露 JSON Schema 配置描述：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/.well-known/mcp-config",
  "title": "Exa MCP Server Configuration",
  "type": "object",
  "properties": {
    "exaApiKey": { "type": "string" },
    "tools": { "type": "string" },
    "debug": { "type": "boolean", "default": false }
  }
}

资料来源：api/well-known-mcp-config.ts

环境变量配置（stdio 传输）

本地运行时通过环境变量配置：

部署模式

远程托管模式

graph LR
    User[用户] -->|Claude Code / AI 助手| CloudEndpoint["https://mcp.exa.ai/mcp"]
    CloudEndpoint --> ExaAPI[Exa API]
    ExaAPI --> CloudEndpoint
    CloudEndpoint -->|SSE 流| User

优点：无需本地安装，无 API Key 泄露风险

本地部署模式

graph LR
    User[用户] --> Claude[Claude Code]
    Claude -->|stdio JSON-RPC| LocalMCP["exa-mcp-server<br/>(本地进程)"]
    LocalMCP -->|HTTP| ExaAPI[Exa API]
    ExaAPI --> LocalMCP

本地部署通过 npx exa-mcp-server 启动，需设置 EXA_API_KEY 环境变量。

版本与构建

构建脚本 (package.json)：

{
  "scripts": {
    "build": "npm run build:stdio",
    "build:stdio": "esbuild src/stdio-cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/stdio.cjs --banner:js=\"#!/usr/bin/env node\""
  }
}

资料来源：package.json

社区问题与架构关联

社区反馈表明工具选择配置是用户关注的核心功能点，Issue #48 指出新版本可能改变了工具启用的配置方式。

传输层概述

Exa MCP Server 当前实现了两类传输机制：

这种双传输架构使得同一个 MCP 服务器能够同时服务于本地 CLI 工具和远程 API 消费者。

资料来源：package.json:5-8

Stdio 传输实现

工作原理

Stdio 传输是最基础的 MCP 传输方式，通过标准输入（stdin）接收客户端请求，通过标准输出（stdout）返回响应。这种方式特别适合本地进程调用和命令行工具集成。

graph LR
    A[MCP 客户端] -->|写入 stdin| B[exa-mcp-server 进程]
    B -->|读取 stdout| A
    B -->|stderr| C[日志/调试输出]

构建配置

Stdio 传输通过 esbuild 打包为独立的 CommonJS 可执行文件：

{
  "bin": {
    "exa-mcp-server": "dist/stdio.cjs"
  },
  "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"
  }
}

关键配置点：

资料来源：package.json:14-16

已知的 Stdio 传输问题

#### 多重 shebang 问题

社区反馈 Issue #65 报告了 .smithery/index.cjs 文件在构建过程中被添加多重 shebang 行，导致 stdio 传输失败。这是一个构建管道问题，会破坏 MCP 协议的消息解析。

错误表现：

Error: Invalid JSON-RPC message format

根本原因：构建过程中多次对同一文件添加 shebang 前缀。

影响范围：使用 @smithery/npm 集成的用户。

资料来源：社区 Issue #65

使用方式

通过 npm 全局安装后，CLI 会自动配置 PATH：

npx exa-mcp-server

或作为 npm 依赖使用：

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

资料来源：npm.readme.md:1-15

HTTP + SSE 传输实现

远程端点架构

HTTP + SSE 传输用于 Exa 的托管 MCP 服务，端点地址为 https://mcp.exa.ai/mcp。这种传输方式支持服务端推送，使服务器能够主动向客户端发送消息。

graph LR
    A[MCP 客户端] -->|HTTP POST /mcp| B[API Gateway]
    B -->|SSE Stream| A
    B -->|转发请求| C[MCP Handler]
    C -->|调用| D[Exa API]
    D -->|搜索结果| C
    C -->|处理结果| B

Server-Sent Events 配置

SSE 传输要求客户端使用 HTTP POST 方法建立连接。这一实现细节在社区 Issue #86 中被指出：标准 GET 请求会返回 405 Method Not Allowed。

支持的 HTTP 方法：

请求头要求：

Content-Type: application/json
Accept: text/event-stream

资料来源：社区 Issue #86

端点配置

远程 MCP 端点支持通过 URL 查询参数进行配置：

完整端点示例：

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

资料来源：README.md:可用工具部分

MCP 配置发现

服务器实现了 .well-known/mcp-config 端点，遵循 MCP 规范的配置发现机制：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/.well-known/mcp-config",
  "title": "Exa MCP Server Configuration",
  "x-query-style": "dot+bracket",
  "properties": {
    "exaApiKey": { "type": "string" },
    "tools": { "type": "string" },
    "debug": { "type": "boolean", "default": false }
  }
}

资料来源：api/well-known-mcp-config.ts:1-30

部署架构

Vercel 部署

远程 MCP 服务部署在 Vercel 平台上，通过 vercel.json 配置边缘函数：

{
  "version": 2,
  "rewrites": [
    { "source": "/mcp", "destination": "/api/mcp" }
  ]
}

所有 /mcp 路径的请求被重写到 /api/mcp 处理程序。

资料来源：vercel.json

Docker 部署

对于需要自托管的场景，项目提供了 Dockerfile 支持容器化部署：

# 基础镜像、构建步骤、启动命令

Docker 部署特别适合企业内网环境或需要完全控制基础设施的场景。

资料来源：Dockerfile

工具启用与传输关系

不同的传输层对工具可用性有不同影响：

Stdio 传输默认启用基础工具，高级工具需通过环境变量配置。HTTP 传输通过 URL 参数 tools 控制。

工具选择配置问题

社区 Issue #48 反映新版本发布后工具选择配置出现回归（regression）。用户之前可以通过配置文件选择可用工具，但新版本可能改变了这一行为。

受影响配置：

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

建议的解决方案：

1. 使用默认工具配置
2. 对于高级工具，使用 web_search_advanced_exa 而非已弃用的 company_research_exa

资料来源：社区 Issue #48

消息协议

JSON-RPC 消息格式

MCP 协议使用 JSON-RPC 2.0 规范进行消息交换：

请求消息：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "web_search_exa",
    "arguments": {
      "query": "示例搜索"
    }
  }
}

响应消息：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "搜索结果内容"
      }
    ]
  }
}

错误处理

最佳实践

Stdio 传输

1. 环境变量配置：将 EXA_API_KEY 设置在环境变量中，避免硬编码
2. 版本锁定：使用 [email protected] 锁定版本，防止意外更新
3. 错误日志：监控 stderr 输出以获取调试信息

HTTP 传输

1. 安全密钥管理：不要在 URL 中明文传递 API 密钥（考虑使用服务端代理）
2. 连接复用：SSE 连接应保持长连接以获得最佳性能
3. 错误重试：实现指数退避重试机制应对临时性故障

传输选择指南

相关文档

• 完整文档
• npm 包
• API 密钥获取

工具体系架构

Exa MCP Server 的工具系统遵循模块化设计原则，核心工具与高级工具分离，支持灵活的启用/禁用控制。

graph TD
    A[Exa MCP Server] --> B[核心工具<br/>默认启用]
    A --> C[高级工具<br/>按需启用]
    A --> D[已废弃工具<br/>向后兼容]
    
    B --> B1[web_search_exa]
    B --> B2[web_fetch_exa]
    
    C --> C1[web_search_advanced_exa]
    
    D --> D1[get_code_context_exa]
    D --> D2[company_research_exa]
    D --> D3[deep_search_exa]
    D --> D4[crawling_exa]
    D --> D5[people_search_exa]
    D --> D6[linkedin_search_exa]
    D --> D7[deep_researcher_start]
    D --> D8[deep_researcher_check]

工具分类与状态

根据工具配置文档，工具分为三类状态：

资料来源：src/mcp-handler.ts:1-15

核心工具

1. web_search_exa（网页搜索）

基础网页搜索工具，提供语义化的自然语言搜索能力。

// 工具定义（src/tools/webSearch.ts）
async ({ query, numResults }) => {
  const toolId = toolName || 'web_search_exa';
  // 从查询字符串提取 category:<type>
  const categoryMatch = query.match(/\bcategory:(company|research\s*paper|news|personal\s*site|people)\b/i);
}

资料来源：src/tools/webSearch.ts:30-45

#### 参数说明

#### 查询修饰符

可在查询中嵌入以下修饰符：

#### 使用示例

// 基础搜索
{
  "query": "best practices for React hooks",
  "numResults": 5
}

// 公司搜索
{
  "query": "category:company Anthropic funding rounds",
  "numResults": 10
}

2. web_fetch_exa（网页抓取）

从指定 URL 提取完整网页内容，支持动态页面和子页面爬取。

// 工具定义签名（src/tools/webFetch.ts）
async ({ url, query, contents, subpages, subpageTarget }) => {
  // contents 配置内容提取选项
  // subpages 配置子页面爬取
}

资料来源：src/tools/webFetch.ts:1-30

#### 参数说明

#### contents 配置子对象

高级工具

3. web_search_advanced_exa（高级搜索）

提供完整的搜索过滤功能，包括域名限制、日期范围、内容过滤和子页面爬取。

// 工具定义（src/tools/webSearchAdvanced.ts）
// 支持完整的参数配置

资料来源：src/tools/webSearchAdvanced.ts:1-50

#### 搜索类型

#### 类别过滤

#### 重要限制

⚠️ 已知问题：includeText 和 excludeText 参数仅支持单元素数组。多元素数组会导致 400 错误。如需匹配多个术语，请将它们放在 query 字符串中或运行单独搜索。

资料来源：src/types.ts:15-25

#### 参数说明

已废弃工具（向后兼容）

以下工具仍可用，但建议迁移到新工具：

资料来源：src/mcp-handler.ts:8-14

工具启用配置

URL 参数配置

通过查询参数控制工具启用状态：

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

资料来源：api/well-known-mcp-config.ts:15-30

可用工具列表

Claude Code 配置示例

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

工具响应格式

搜索响应结构

interface ExaSearchResponse {
  requestId: string;
  autopromptString?: string;
  autoDate?: string;
  resolvedSearchType: string;
  results: ExaSearchResult[];
  searchTime?: number;
  costDollars?: ExaCostDollars;
}

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[];
}

资料来源：src/types.ts:50-75

响应字段说明

常见问题与已知问题

Issue #48: 新版本工具选择回归

问题描述：新版本发布后，原有的工具选择配置方式可能发生变化。

解决方案：使用 URL 查询参数 tools 明确指定要启用的工具列表：

https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa

Issue #86: HTTP SSE 405 错误

问题描述：部分 MCP 客户端使用 GET 方法连接时收到 405 Method Not Allowed 错误。

状态：已知问题，部分客户端（如 Claude Code）使用 POST 方法可以正常连接。

Issue #65: stdio transport shebang 问题

问题描述：npm 包构建过程中可能产生多个 shebang 行，导致 stdio transport 失败。

临时解决方案：自行从源码构建，避免使用预编译包：

npm run build:stdio

工作流程图

graph TD
    A[用户发起搜索请求] --> B{选择工具}
    B -->|基础搜索| C[web_search_exa]
    B -->|高级搜索| D[web_search_advanced_exa]
    B -->|内容抓取| E[web_fetch_exa]
    
    C --> F{查询包含 category?}
    D --> F
    F -->|是| G[提取 category 修饰符]
    F -->|否| H[使用 type:auto]
    G --> I[调用 Exa API]
    H --> I
    
    E --> J[解析 URL 和 contents 配置]
    J --> I
    
    I --> K{API 响应}
    K -->|成功| L[格式化结果]
    K -->|错误| M[返回错误信息]
    
    L --> N[返回 MCP 响应]
    M --> N

总结

Exa MCP Server 的工具体系设计清晰，分为三个层次：

1. 核心工具：满足大多数使用场景，开箱即用
2. 高级工具：提供完整配置能力，适合复杂搜索需求
3. 废弃工具：保持向后兼容，引导用户使用新工具

使用时应根据具体需求选择合适的工具，并通过 URL 参数 tools 控制工具启用状态，以获得最佳性能和功能体验。

概述

基础搜索工具是 Exa MCP Server 提供的一组核心功能模块，包括 web_search_exa（基础网页搜索）和 web_fetch_exa（网页内容抓取）。这两个工具默认启用，为 AI 助手提供实时网页搜索和内容提取能力。

在 MCP 工具生态中，基础搜索工具扮演着默认入口的角色。用户无需额外配置即可使用，满足日常网页搜索和简单内容抓取需求。对于更复杂的高级搜索场景（如精确的域名过滤、日期范围控制等），则需要启用 web_search_advanced_exa 高级搜索工具。资料来源：src/mcp-handler.ts:1-15

工具架构

graph TD
    A[MCP 客户端] --> B[Exa MCP Server]
    B --> C{工具选择}
    C -->|基础搜索| D[web_search_exa]
    C -->|内容抓取| E[web_fetch_exa]
    C -->|高级搜索| F[web_search_advanced_exa]
    D --> G[Exa Search API]
    E --> G
    F --> G
    G --> H[搜索结果/网页内容]
    
    style D fill:#90EE90
    style E fill:#90EE90
    style F fill:#FFE4B5

核心工具详解

web_search_exa（基础网页搜索）

web_search_exa 是最常用的搜索工具，设计目标是快速获取与查询相关的网页内容。

#### 功能特点

#### 支持的分类类型

资料来源：src/tools/webSearch.ts:1-30

#### 使用示例

// 基础网页搜索
web_search_exa {
  "query": "最新人工智能发展趋势",
  "numResults": 10
}

// 带分类的搜索
web_search_exa {
  "query": "category:company Anthropic 公司介绍",
  "numResults": 5
}

// 语义化查询示例
web_search_exa {
  "query": "blog post comparing React and Vue performance",
  "numResults": 8
}

#### 工具元数据标记

工具定义中包含以下语义提示，用于 MCP 客户端优化调用行为：

资料来源：src/tools/webSearch.ts:55-60

web_fetch_exa（网页内容抓取）

web_fetch_exa 用于获取特定 URL 的完整网页内容，作为搜索结果的深度补充。

#### 功能定位

当 web_search_exa 返回的高亮片段（highlights）不足以满足需求时，可使用此工具获取目标网页的完整内容。

#### 使用场景

1. 深入阅读：搜索结果摘要不完整，需要全文内容
2. 结构化提取：提取网页中的特定信息（如联系方式、价格表等）
3. 动态页面：需要执行 JavaScript 才能渲染的页面

搜索结果数据结构

ExaSearchResult 类型定义

资料来源：src/types.ts:1-40

查询解析机制

category 字段提取

web_search_exa 支持在查询字符串中嵌入分类指令。解析逻辑如下：

graph LR
    A[原始查询字符串] --> B{正则匹配<br/>category:XXX}
    B -->|匹配成功| C[提取分类值]
    B -->|无匹配| D[category = undefined]
    C --> E[清理查询字符串]
    D --> E
    E --> F[传递给 Exa API]

支持的分类正则模式：

/\bcategory:(company|research\s*paper|news|personal\s*site|people)\b/i

资料来源：src/tools/webSearch.ts:42-48

请求日志与调试

每个搜索请求都会生成唯一的请求 ID，用于日志追踪：

const requestId = `${toolId}-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
const logger = createRequestLogger(requestId, toolId);

日志记录包括：

• 请求开始时间
• 查询参数
• API 响应状态
• 结果数量和内容长度

社区相关问题

工具选择配置问题

Issue #48 反映了用户在新版本发布后遇到工具选择配置回归问题。用户反映在指定 MCP 配置时，之前可以正常选择可用工具的方式在新版本中出现问题。

建议：使用 URL 参数方式启用特定工具：

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

资料来源：社区 Issue #48

SSE 端点兼容性问题

Issue #86 报告了 HTTP SSE 端点对 GET 方法返回 405 错误的问题。某些 MCP 客户端使用标准 SSE GET 请求连接，但 Exa 端点期望 POST 方法。

影响范围：基础搜索工具通过 HTTP 传输时可能受影响，但 Claude Code 等使用 POST 的客户端可正常连接。

资料来源：社区 Issue #86

配置与部署

默认启用状态

远程 MCP 配置

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

使用托管端点

推荐使用 Exa 托管的远程 MCP 服务器：

https://mcp.exa.ai/mcp

此端点默认启用基础搜索工具，无需本地安装。

与高级搜索工具对比

资料来源：README.md:1-50

最佳实践

1. 查询优化

推荐做法：描述理想页面而非罗列关键词

// ✅ 推荐：语义化描述
"blog post comparing React and Vue performance"

// ❌ 不推荐：关键词堆砌
"React Vue performance comparison blog"

2. 工具组合使用

1. web_search_exa → 快速定位相关网页
2. web_fetch_exa → 获取目标 URL 的完整内容
3. 如需精确过滤 → 启用 web_search_advanced_exa

3. 结果验证

检查返回结果中的 score 字段（相关度得分）和 highlightScores 数组来评估结果质量。

相关文件

• 工具实现：src/tools/webSearch.ts、src/tools/webFetch.ts
• 类型定义：src/types.ts
• 工具注册：src/mcp-handler.ts
• 响应处理：src/utils/exaResponseSanitizer.ts
• 验证逻辑：src/tools/validation.ts

概述

高级搜索工具（web_search_advanced_exa）是 Exa MCP Server 提供的增强型搜索功能，相较于基础搜索工具，提供了更细粒度的控制能力。该工具默认情况下处于禁用状态，需要通过配置参数显式启用。资料来源：src/mcp-handler.ts:14

高级搜索工具的核心项目括：

• 完整过滤器支持：支持域名过滤、日期范围、文本匹配等所有高级参数
• 内容类别搜索：针对特定内容类型（公司、研究论文、新闻等）优化的搜索模式
• 内容提取控制：可自定义摘要生成、高亮提取和子页面爬取
• 结构化输出：支持自定义 JSON 输出格式

graph TD
    A[用户请求] --> B{工具选择}
    B -->|基础搜索| C[web_search_exa]
    B -->|高级搜索| D[web_search_advanced_exa]
    D --> E[提取 category 参数]
    E --> F[验证过滤器兼容性]
    F --> G[调用 Exa API]
    G --> H[格式化响应]
    H --> I[返回结果]

工具配置与启用

启用方式

高级搜索工具需要通过 tools 查询参数显式启用：

https://mcp.exa.ai/mcp?tools=web_search_advanced_exa

资料来源：api/well-known-mcp-config.ts:8-12

默认工具列表

资料来源：api/well-known-mcp-config.ts:3-5

API 参数详解

核心参数

资料来源：src/types.ts:1-15

域名过滤参数

日期过滤参数（ISO 8601 格式）

文本过滤参数

重要限制：includeText 和 excludeText 仅支持单元素数组。多元素数组会导致 400 错误。

资料来源：src/types.ts:12-13

内容类别系统

支持的类别

graph LR
    A[高级搜索] --> B[company<br/>公司主页]
    A --> C[research paper<br/>研究论文]
    A --> D[news<br/>新闻报道]
    A --> E[pdf<br/>PDF文档]
    A --> F[github<br/>代码仓库]
    A --> G[personal site<br/>个人网站]
    A --> H[people<br/>人物搜索]
    A --> I[financial report<br/>财务报告]

类别说明

资料来源：src/types.ts:2

company 类别的特殊限制

当使用 category: "company" 时，以下参数会导致 400 错误：

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

内容提取配置

内容块配置

contents: {
  text?: { maxCharacters?: number } | boolean;
  context?: { maxCharacters?: number } | boolean;
  summary?: { query?: string } | boolean;
  highlights?: {
    maxCharacters?: number;
    numSentences?: number;
    highlightsPerUrl?: number;
    query?: string;
  };
  livecrawl?: 'never' | 'fallback' | 'always' | 'preferred';
  maxAgeHours?: number;
  livecrawlTimeout?: number;
  subpages?: number;
  subpageTarget?: string[];
}

资料来源：src/types.ts:15-35

配置项说明

搜索结果模型

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[];
}

资料来源：src/types.ts:37-54

深度搜索模式

深度搜索（deepSearch）是高级搜索的扩展模式，提供更深入的分析能力：

资料来源：src/tools/deepSearch.ts:8-25

深度搜索输出格式

深度搜索会自动格式化响应，包含：

1. 摘要部分：基于 objective 的分析摘要
2. 引用部分：所有引用的 Markdown 链接格式
3. 结果部分：逐条呈现的搜索结果，包含标题、URL、日期、图片和高亮

资料来源：src/tools/deepSearch.ts:55-80

使用示例

基础公司研究

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

研究论文搜索

{
  "query": "LLM reasoning capabilities",
  "includeDomains": ["arxiv.org", "openreview.net"],
  "includeText": ["transformer"],
  "numResults": 20,
  "type": "deep"
}

带内容提取的深度搜索

{
  "objective": "分析 AI 安全领域的最新研究进展",
  "search_queries": ["AI safety research 2024", "LLM alignment"],
  "type": "deep-reasoning",
  "numResults": 10,
  "outputSchema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "key_findings": { "type": "array" },
      "researchers": { "type": "array" }
    }
  }
}

社区已知问题

工具选择配置回归（Issue #48）

在新版本发布后，部分用户反馈工具选择配置方式发生了变化。之前的配置文件格式可能不再兼容，建议使用标准的 URL 参数方式 ?tools=web_search_advanced_exa 来启用高级搜索工具。

HTTP 方法兼容性问题（Issue #86）

远程 MCP 端点 https://mcp.exa.ai/mcp 目前对标准 SSE 连接使用的 HTTP GET 方法返回 405 错误。部分客户端（如 Claude Code）通过使用 POST 方法可以正常连接。

相关资源

• 完整文档
• API Key 获取
• npm 包

部署方式概览

环境变量配置

必需参数

获取 API Key

访问 Exa Dashboard API Keys 页面创建新的 API 密钥。

环境变量配置示例

# Linux/macOS
export EXA_API_KEY="your_api_key_here"

# Windows (PowerShell)
$env:EXA_API_KEY="your_api_key_here"

构建时环境变量

根据 package.json 中的构建配置：

{
  "scripts": {
    "build": "npm run build:stdio",
    "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"
  }
}

资料来源：package.json:1-45

本地 stdio 部署

stdio 传输是 Model Context Protocol 的标准本地通信方式，适用于 Claude Code Desktop、Smithery 等桌面集成场景。

安装方式

# 通过 npx 直接运行
npx -y exa-mcp-server

# 全局安装
npm install -g exa-mcp-server

Claude Code 配置

在 Claude Code 中配置 MCP 服务器，需要修改 Claude Code 的 MCP 配置文件：

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

资料来源：README.md:1-200

Smithery 部署注意事项

根据社区 Issue #65 的反馈，使用 Smithery 集成时存在多 shebang 行问题：

问题描述：npm 包 exa-mcp-server 通过 stdio 传输运行失败，因为在构建过程中 .smithery/index.cjs 文件被添加了多个 shebang 行。

这是由于 package.json 中的构建脚本在打包时可能产生重复的 shebang：

{
  "scripts": {
    "build:stdio": "esbuild ... --banner:js=\"#!/usr/bin/env node\" && chmod +x dist/stdio.cjs"
  }
}

临时解决方案：手动修复 .smithery/index.cjs 文件，删除重复的 shebang 行。

远程 HTTP/SSE 部署

远程部署允许客户端通过 HTTP 连接访问 MCP 服务器，无需本地安装。

基础端点配置

启用工具选择

通过 tools 查询参数指定启用的工具集：

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

资料来源：README.md:1-200

可用工具列表

默认启用的工具：

默认禁用的工具（需要显式启用）：

已废弃工具（保持向后兼容）

资料来源：src/mcp-handler.ts:1-30

HTTP 方法兼容性

根据社区 Issue #86 的反馈：

问题描述：远程 MCP 端点 (https://mcp.exa.ai/mcp) 对标准的 HTTP GET 方法返回 405 Method Not Allowed 错误。

影响范围：

• 使用标准 Server-Sent Events (SSE) 的客户端可能连接失败
• Claude Code 等使用 POST 方法的客户端可以正常连接

建议：客户端应使用 HTTP POST 方法进行连接，兼容所有 MCP 客户端。

部署架构流程

graph TD
    A[客户端] --> B{传输方式选择}
    B -->|stdio| C[本地 exa-mcp-server]
    B -->|HTTP/SSE| D[远程 mcp.exa.ai]
    
    C --> E[环境变量 EXA_API_KEY]
    D --> F[URL 参数 exaApiKey]
    
    E --> G[Exa API]
    F --> G
    
    G --> H{搜索类型}
    H -->|基础搜索| I[web_search_exa]
    H -->|高级搜索| J[web_search_advanced_exa]
    H -->|内容抓取| K[web_fetch_exa]
    
    I --> L[搜索结果]
    J --> L
    K --> L

Docker 部署

构建镜像

# 示例 Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

CMD ["node", "dist/stdio.cjs"]

运行容器

# 构建镜像
docker build -t exa-mcp-server .

# 运行容器
docker run -e EXA_API_KEY="your_api_key" exa-mcp-server

Vercel 部署配置

vercel.json 配置

{
  "builds": [
    {
      "src": "src/vercel-server.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/mcp",
      "dest": "src/vercel-server.ts"
    }
  ]
}

构建脚本

根据 package.json 中的 Vercel 构建配置：

{
  "scripts": {
    "build:vercel": "npm install typescript && ./node_modules/.bin/tsc"
  }
}

资料来源：package.json:1-45

工具配置参考

高级搜索分类配置

当使用 web_search_advanced_exa 时，搜索类别决定可用参数：

资料来源：README.md:1-200

通用参数限制

常见部署问题

Issue #48：工具选择回归

问题：新版本发布后，工具选择配置方式发生变化。

影响：之前通过配置指定可用工具的方式不再生效。

解决方案：使用 URL 查询参数 tools 指定工具列表：

https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa

Issue #108：服务可用性

问题：用户报告 mcp.exa.ai/mcp 端点不可用。

排查步骤：

1. 检查网络连接
2. 验证端点是否支持客户端的 HTTP 方法
3. 考虑使用本地部署作为备选方案

快速部署指南

方式一：远程（推荐新手）

# Claude Code 配置
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY"

方式二：本地 stdio

# 安装 npm 包
npm install -g exa-mcp-server

# 配置 Claude Code
# 在 Claude Code MCP 配置中添加：
# {
#   "mcpServers": {
#     "exa": {
#       "command": "exa-mcp-server",
#       "env": {
#         "EXA_API_KEY": "your_api_key"
#       }
#     }
#   }
# }

方式三：Docker

docker pull exalabs/exa-mcp-server:latest
docker run -d -p 3000:3000 -e EXA_API_KEY="your_key" exalabs/exa-mcp-server

相关资源

概述

Exa MCP Server 的认证与授权系统主要包含以下核心功能：

资料来源：api/well-known-mcp-config.ts:1-60

API Key 认证

环境变量方式（推荐）

在本地部署或通过 npx 运行 MCP Server 时，推荐使用环境变量配置 API 密钥：

export EXA_API_KEY="your_api_key_here"
npx exa-mcp-server

对于不同的 MCP 客户端配置方式：

// Claude Code 配置示例
{
  "mcpServers": {
    "exa-mcp-server": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

资料来源：npm.readme.md

URL 参数方式

对于远程 MCP 端点，可以通过 URL 查询参数传递 API 密钥：

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

这种方式的配置结构如下：

资料来源：api/well-known-mcp-config.ts:17-35

API Key 安全配置架构

graph TD
    A[用户请求] --> B{认证方式}
    B -->|环境变量| C[EXA_API_KEY]
    B -->|URL参数| D[exaApiKey 查询参数]
    B -->|OAuth| E[OAuth Token]
    C --> F[认证服务]
    D --> F
    E --> F
    F --> G{验证结果}
    G -->|通过| H[API 请求处理]
    G -->|失败| I[返回 401/403 错误]

工具级别授权

默认工具

系统默认启用以下工具：

资料来源：npm.readme.md

自定义工具配置

通过 tools URL 参数可以精确控制可用工具：

# 仅启用基础搜索
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa

# 启用所有工具
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

可用工具完整列表：

资料来源：api/well-known-mcp-config.ts:35-45

已废弃工具（向后兼容）

以下工具已废弃但仍可用：

OAuth 2.0 授权

受保护资源配置

Exa MCP Server 实现了 OAuth 2.0 受保护资源发现端点，支持标准的授权流程：

// 资源配置数据结构
interface ProtectedResource {
  resource: string;
  scopes_supported: string[];
  authorization_types_supported: string[];
  token_endpoint_auth_methods_supported: string[];
  endpoint_aliases: string[];
}

资料来源：api/well-known-oauth-protected-resource.ts

OAuth 认证流程

sequenceDiagram
    participant C as MCP 客户端
    participant S as Exa MCP Server
    participant A as 授权服务器
    
    C->>S: 访问受保护资源端点
    S-->>C: 返回 401 + WWW-Authenticate
    C->>A: 发起授权请求
    A-->>C: 授权码
    C->>A: 交换授权码获取 Token
    A-->>C: Access Token
    C->>S: 携带 Token 重试请求
    S->>S: 验证 Token
    S-->>C: 返回受保护资源

授权端点元数据

客户端元数据

元数据收集机制

MCP Server 会收集客户端元数据用于审计和安全追踪：

interface MCPClientMetadata {
  clientId?: string;        // 客户端标识符
  clientName?: string;       // 客户端名称
  clientVersion?: string;   // 客户端版本
  transportType?: string;    // 传输类型 (stdio/http)
  endpoint?: string;        // 连接的端点
}

资料来源：src/utils/mcpClientMetadata.ts

元数据用途

安全最佳实践

环境变量 vs URL 参数

安全建议

1. 优先使用环境变量 - API 密钥不应出现在 URL、代码仓库或日志中
2. 最小权限原则 - 仅启用必需的 tools，减少攻击面
3. 定期轮换密钥 - 定期更换 API 密钥降低泄露风险
4. 监控访问日志 - 关注异常访问模式
5. 使用 HTTPS - 确保传输层加密

故障排除

常见认证错误

社区相关问题

Issue #86: HTTP SSE 端点返回 405 错误

部分 MCP 客户端（如通用 MCP 客户端）使用标准 Server-Sent Events 的 GET 方法连接，但当前端点配置导致返回 405 Method Not Allowed。建议使用支持 POST 方法的客户端或检查官方文档获取最新支持的方法。

Issue #48: 新版本发布后工具选择问题

有用户反馈新版本发布后，通过配置选择可用工具的方式发生了变化。确保使用正确的 URL 参数格式 ?tools=web_search_exa,web_search_advanced_exa。

相关文件参考

延伸阅读

• Exa MCP 完整文档
• Exa API 密钥管理
• npm 包说明

常见问题概览

连接问题

HTTP 405 错误

问题描述：远程 MCP 端点 (https://mcp.exa.ai/mcp) 返回 405 Method Not Allowed 错误，标准 Server-Sent Events (SSE) 连接使用 HTTP GET 方法被拒绝。

根本原因：部分 MCP 客户端使用 GET 请求连接远程端点，但服务器要求 POST 请求进行 SSE 流式传输。

解决方案：

1. 使用兼容的 MCP 客户端：Claude Code 等客户端自动使用 POST 方法，可正常连接
2. 检查客户端配置：确保客户端使用正确的 HTTP 方法
3. 查看官方支持的客户端列表：某些客户端可能需要特定版本才支持 POST 方法

服务宕机

问题描述：访问 mcp.exa.ai/mcp 时出现超时或连接拒绝。

排查步骤：

graph TD
    A[服务连接失败] --> B{检查网络连接}
    B -->|正常| C{检查 API Key 配置}
    B -->|异常| D[检查本地网络]
    C -->|已配置| E{查看状态页面}
    C -->|未配置| F[配置 EXA_API_KEY]
    E --> G{服务正常?}
    G -->|是| H[检查防火墙/代理]
    G -->|否| I[等待服务恢复]

应急方案：

• 使用本地部署的 MCP 服务器替代远程端点
• 检查 Exa 官方状态页面确认服务可用性

工具配置问题

工具选择失效

问题描述：新版本发布后，通过配置文件指定可用工具的方式不再生效。

背景：Issue #48 报告此问题。用户习惯通过配置指定工具列表，但版本更新后配置方式发生变化。

当前配置方式：

通过 URL 参数指定启用的工具：

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

可用工具列表：

配置示例（Claude Code）：

{
  "mcpServers": {
    "exa": {
      "command": "claude",
      "args": ["mcp", "add", "--transport", "http", "exa", "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa"]
    }
  }
}

工具参数错误

问题描述：调用 web_search_advanced_exa 时返回 400 错误。

常见原因：

1. 数组参数限制：includeText 和 excludeText 仅支持单元素数组

// 错误写法
{
  "includeText": ["LLM", "transformer"]  // 会导致 400 错误
}

// 正确写法
{
  "includeText": ["LLM"],
  "query": "transformer"  // 将第二个词放入查询字符串
}

1. category 特定限制：当使用 category: "company" 时，以下参数会导致 400 错误：

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

API 认证问题

API Key 配置

方式一：环境变量

export EXA_API_KEY=your_api_key_here

方式二：URL 参数

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY

验证配置：可访问 Exa Dashboard 查看 API Key 状态。

认证失败处理

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as Exa MCP Server
    participant API as Exa API
    
    Client->>Server: 请求执行搜索
    Server->>API: 转发请求 (含 API Key)
    API-->>Server: 401 Unauthorized
    Server-->>Client: 返回认证错误
    
    Note over Client: 检查 EXA_API_KEY 配置
    Client->>Server: 重试请求
    Server->>API: 转发新请求
    API-->>Server: 200 OK
    Server-->>Client: 返回搜索结果

Stdio 传输问题

多重 Shebang 问题

问题描述：Issue #65 报告 npm 包 exa-mcp-server 通过 stdio 传输运行时失败。

错误现象：.smithery/index.cjs 文件在构建过程中被添加了多重 shebang 行。

构建配置分析：

根据 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"
  }
}

构建流程使用 esbuild 生成单文件输出，--banner:js 参数确保 shebang 正确添加。

临时解决方案：

1. 手动清理生成文件中的重复 shebang
2. 使用 HTTP 传输模式替代 stdio 模式

Deep Search 错误处理

超时配置

deepSearch 工具具有内置超时机制：

错误响应格式

interface ExaSearchStatus {
  id: string;
  status: string;
  source: string;
  error?: {
    tag: string;
    httpStatusCode?: number | null;
  };
}

常见错误标签：

日志调试

启用调试模式

通过 debug 参数启用详细日志：

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&debug=true

日志输出示例：

每个请求会生成唯一请求 ID：

const requestId = `${toolId}-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;

日志包含：

• 请求参数
• API 响应时间 (searchTime)
• 成本信息 (costDollars)
• 错误详情

日志内容结构

interface ExaSearchResponse {
  requestId: string;
  autopromptString?: string;
  autoDate?: string;
  resolvedSearchType: string;
  results: ExaSearchResult[];
  searchTime?: number;
  costDollars?: ExaCostDollars;
}

interface ExaCostDollars {
  total: number;
  search?: Record<string, number>;
  contents?: Record<string, number>;
}

客户端兼容性

支持的传输方式

客户端配置示例

Cursor：

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

VS Code：

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

本地部署：

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

获取帮助

如果问题仍未解决：

1. 查看官方文档：Exa MCP 文档
2. 检查 npm 包信息：exa-mcp-server
3. 提交 Issue：在 GitHub 仓库 报告问题

版本信息

当前稳定版本：3.2.1

建议始终使用最新版本以获得 bug 修复和性能改进。

Pitfall Log / 踩坑日志

项目：exa-labs/exa-mcp-server

摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Remote MCP docs show API key in URL query string。

1. 安全/权限坑 · 来源证据：Remote MCP docs show API key in URL query string

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Remote MCP docs show API key in URL query string
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_814fe712ae6543ce9f086d0fb4433748 | https://github.com/exa-labs/exa-mcp-server/issues/334 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Proposal: Free AI Agent identity verification for Exa MCP

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: Free AI Agent identity verification for Exa MCP
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_77ed9b7438ae4eafb0ed10e4ed50639a | https://github.com/exa-labs/exa-mcp-server/issues/347 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:895291604 | https://github.com/exa-labs/exa-mcp-server | release_recency=unknown