# https://github.com/exa-labs/exa-mcp-server 项目说明书
生成时间：2026-05-30 21:10:20 UTC
## 目录
- [项目介绍](#page-introduction)
- [安装指南](#page-installation)
- [系统架构](#page-architecture)
- [传输层实现](#page-transport)
- [工具概览](#page-tools-overview)
- [基础搜索工具](#page-web-search)
- [高级搜索工具](#page-advanced-search)
- [部署配置](#page-deployment)
- [认证与授权](#page-authentication)
- [故障排除指南](#page-troubleshooting)
## 项目介绍
### 相关页面
相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# 项目介绍
## 概述
exa-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于将 AI 助手连接到 Exa 的搜索能力。项目由 Exa Labs 开发维护，提供实时网络搜索、内容抓取和高级搜索功能。
**核心能力：**
- Web 搜索：通用的网络信息检索
- 高级搜索：支持完整的过滤参数配置
- Web 内容抓取：从特定 URL 提取完整内容
- 深度搜索：基于 AI 推理的深度搜索模式
资料来源：[README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## 项目信息
| 属性 | 值 |
|------|-----|
| **npm 包名** | exa-mcp-server |
| **当前版本** | 3.2.1 |
| **MCP 名称** | io.github.exa-labs/exa-mcp-server |
| **仓库地址** | git+https://github.com/exa-labs/exa-mcp-server.git |
| **模块类型** | ES Module |
| **Node 版本** | >=20 |
资料来源：[package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
## 架构设计
### 系统架构图
```mermaid
graph TD
subgraph "MCP 客户端"
A[Claude Code / Cursor / VS Code]
end
subgraph "exa-mcp-server"
B[MCP Handler
工具路由分发]
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` 规范：
```mermaid
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](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
## 可用工具
### 默认启用的工具
| 工具名称 | 功能描述 |
|---------|---------|
| `web_search_exa` | 搜索任意主题的网络内容，返回可直接使用的清洗结果 |
| `web_fetch_exa` | 从已知 URL 获取特定网页的完整内容 |
资料来源：[README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
### 可选工具
| 工具名称 | 功能描述 | 默认状态 |
|---------|---------|---------|
| `web_search_advanced_exa` | 高级网络搜索，支持完整的过滤参数、域名限制、日期范围、高亮和摘要提取 | 关闭 |
### 已废弃工具（保持向后兼容）
| 废弃工具 | 替代工具 |
|---------|---------|
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `people_search_exa` | `web_search_advanced_exa` |
| `linkedin_search_exa` | `web_search_advanced_exa` |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) |
| `deep_search_exa` | `web_search_advanced_exa` |
资料来源：[src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
## 搜索类别支持
高级搜索工具支持多种搜索类别，适用于不同的搜索场景：
| 类别 | 适用场景 | 支持域过滤 | 支持日期过滤 |
|------|---------|-----------|-------------|
| `company` | 公司主页、融资信息、员工规模、营收数据 | ❌ | ❌ |
| `news` | 新闻报道、公告发布 | ✅ | ✅ |
| `people` | LinkedIn 公开个人资料 | ✅ | ✅ |
| `research paper` | 学术论文、arXiv 预印本 | ✅ | ✅ |
| `personal site` | 个人博客、作品集网站 | ✅ | ✅ |
| `auto` | 通用搜索、无类别限制 | ✅ | ✅ |
**通用限制：**
- `includeText` 和 `excludeText` 仅支持**单元素数组**，多元素数组会导致 400 错误
资料来源：[README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
## 数据类型定义
### 搜索请求类型
```typescript
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;
};
};
}
```
### 搜索结果类型
```typescript
interface ExaSearchResult {
id?: string;
title?: string | null;
url?: string;
publishedDate?: string;
author?: string;
text?: string;
summary?: string;
highlights?: string[];
highlightScores?: number[];
image?: string;
favicon?: string;
score?: number;
subpages?: ExaSearchResult[];
}
```
### 搜索响应类型
```typescript
interface ExaSearchResponse {
requestId: string;
resolvedSearchType: string;
results: ExaSearchResult[];
searchTime?: number;
costDollars?: {
total: number;
search?: Record;
contents?: Record;
};
}
```
资料来源：[src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
## 安装与配置
### 远程 MCP（推荐）
使用 Exa 托管的远程 MCP 服务器，无需本地安装 API 密钥：
```
https://mcp.exa.ai/mcp
```
### 本地安装
```bash
npm install exa-mcp-server
```
### Claude Code 配置示例
```json
{
"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
```
### 配置参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `exaApiKey` | string | 否 | Exa API 密钥，服务端有备用密钥 |
| `tools` | string | 否 | 逗号分隔的工具列表，默认为 `web_search_exa,web_fetch_exa` |
| `debug` | boolean | 否 | 启用调试日志，默认 false |
资料来源：[api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/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](https://github.com/exa-labs/exa-mcp-server/blob/main/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` 服务暂时不可用的情况。
## 项目链接
| 资源 | 链接 |
|------|------|
| 文档 | https://docs.exa.ai/reference/exa-mcp |
| npm 包 | https://www.npmjs.com/package/exa-mcp-server |
| API Key | https://dashboard.exa.ai/api-keys |
| GitHub | https://github.com/exa-labs/exa-mcp-server |
---
## 安装指南
### 相关页面
相关主题：[项目介绍](#page-introduction), [部署配置](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
- [npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/npm.readme.md)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
# 安装指南
## 概述
本指南涵盖 exa-mcp-server 的所有安装方式，包括**远程 MCP 服务器连接**（推荐方式）和**本地 npm 包安装**两种方案。
- **远程 MCP 服务器**：无需安装，直接通过 `https://mcp.exa.ai/mcp` 端点连接
- **本地安装**：通过 npm 包 `exa-mcp-server` 在本地运行，支持 stdio 传输协议
> [!NOTE]
> 推荐使用远程 MCP 服务器方式，配置更简单且始终保持最新版本。
---
## 远程 MCP 服务器（推荐方式）
### 工作原理
```mermaid
graph LR
A[AI 客户端
Claude Code/Cursor] -->|HTTP POST
SSE| B[mcp.exa.ai/mcp]
B --> C[Exa 云端
MCP Handler]
C --> D[Exa Search API]
D --> B
B --> A
```
远程 MCP 服务器由 Exa 官方托管，客户端通过 HTTP/SSE 协议与其通信。
### 安装步骤
#### Claude Code
```bash
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"
```
#### Cursor
访问安装链接：
```
https://cursor.com/en/install-mcp?name=exa&config=eyJuYW1lIjoiZXhhIiwidHlwZSI6Imh0dHAiLCJ1cmwiOiJodHRwczovL21jcC5leGEuYWkvbWNwIn0=
```
#### 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
```
#### 通用 MCP 客户端 JSON 配置
```json
{
"mcpServers": {
"exa": {
"transport": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
}
```
> [!IMPORTANT]
> 部分 MCP 客户端可能使用 HTTP GET 方法连接远程端点。根据社区反馈（#86），当前端点对 GET 请求返回 `405 Method Not Allowed` 错误。如果连接失败，请确认客户端是否支持 POST 方法。
### API Key 配置
远程 MCP 服务器支持两种认证方式：
| 方式 | 配置方法 | 说明 |
|------|----------|------|
| 方式一 | URL 参数 | `https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY` |
| 方式二 | 请求头 | `Authorization: Bearer YOUR_KEY` |
---
## 本地 npm 安装
### 前置要求
- Node.js 20 或更高版本
- npm、yarn 或 pnpm 包管理器
- Exa API Key（从 [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) 获取）
### 安装命令
```bash
# 使用 npx（无需全局安装）
npx -y exa-mcp-server
# 或全局安装
npm install -g exa-mcp-server
# 或添加到项目依赖
npm install exa-mcp-server
```
### 配置文件格式
#### Claude Code 配置
```json
{
"mcpServers": {
"exa-mcp-server": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
#### Cursor 配置
```json
{
"mcp": {
"servers": {
"exa-mcp-server": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
}
```
### 环境变量配置
| 环境变量 | 必填 | 说明 |
|----------|------|------|
| `EXA_API_KEY` | 是 | Exa API 密钥，从 [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) 获取 |
### 传输协议
本地安装支持 **stdio** 传输协议，进程通过标准输入/输出与父进程通信。
> [!WARNING]
> 根据社区反馈（#65），构建过程中可能产生多个 shebang 行，导致 stdio 传输失败。如遇此问题，请尝试更新到最新版本（3.2.1+）或使用远程 MCP 服务器。
---
## 工具选择配置
### 可用工具列表
| 工具名称 | 默认启用 | 说明 |
|----------|----------|------|
| `web_search_exa` | ✓ | 通用网页搜索 |
| `web_fetch_exa` | ✓ | 从指定 URL 获取网页内容 |
| `web_search_advanced_exa` | ✗ | 高级搜索，支持完整过滤参数 |
### 远程 MCP 工具选择
通过 URL 参数 `tools` 指定启用的工具，多个工具用逗号分隔：
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
### 本地 MCP 工具选择
本地安装时，工具选择由 MCP 客户端配置决定。启用高级搜索工具：
```json
{
"mcpServers": {
"exa-mcp-server": {
"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"
}
}
}
}
```
> [!NOTE]
> 根据社区反馈（#48），新版本发布后工具选择配置方式可能发生变化。请确认使用的版本支持当前配置方式。
---
## 架构概览
```mermaid
graph TB
subgraph "客户端层"
A[Claude Code
Cursor
VS Code]
end
subgraph "MCP 传输层"
B[stdio 传输
本地安装]
C[HTTP/SSE 传输
远程连接]
end
subgraph "工具层"
D[web_search_exa]
E[web_search_advanced_exa]
F[web_fetch_exa]
end
subgraph "Exa API 层"
G[Exa Search API]
end
A --> B
A --> C
B --> D
B --> E
B --> F
C --> D
C --> E
C --> F
D --> G
E --> G
F --> G
```
---
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| `405 Method Not Allowed` | 客户端使用 GET 请求 | 确认客户端支持 POST，或使用远程 MCP 的其他客户端配置 |
| stdio 连接失败 | 构建产物包含多个 shebang 行 | 更新到最新版本或使用远程 MCP |
| `EXA_API_KEY` 缺失 | 未配置环境变量 | 设置 `EXA_API_KEY` 环境变量 |
| 工具不可用 | 未在配置中启用 | 使用 `tools` 参数启用所需工具 |
### 验证安装
安装完成后，可通过以下方式验证：
1. 重启 AI 客户端（Claude Code、Cursor 等）
2. 询问客户端可用工具列表
3. 执行简单搜索测试
---
## 相关资源
- [完整文档](https://docs.exa.ai/reference/exa-mcp)
- [npm 包地址](https://www.npmjs.com/package/exa-mcp-server)
- [GitHub 仓库](https://github.com/exa-labs/exa-mcp-server)
- [API Key 获取](https://dashboard.exa.ai/api-keys)
---
## 系统架构
### 相关页面
相关主题：[传输层实现](#page-transport), [工具概览](#page-tools-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
# 系统架构
Exa MCP Server 是一个基于 Model Context Protocol (MCP) 的搜索服务中间件，它连接 AI 助手与 Exa 搜索引擎，提供实时网页搜索、内容抓取和深度研究能力。
## 架构概览
```mermaid
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 端点
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 | `https://mcp.exa.ai/mcp` | 远程连接，无需本地安装 | URL 参数配置 |
| stdio | `npx exa-mcp-server` | 本地命令行运行 | 环境变量配置 |
**HTTP/SSE 传输**：通过 Server-Sent Events 实现服务器推送，适合云端部署场景。社区 issue #86 指出部分 MCP 客户端使用 GET 方法连接时会收到 405 错误，这是因为服务端仅支持 POST 方法的 SSE 连接。
**stdio 传输**：通过标准输入输出进行 JSON-RPC 通信，适合本地集成和调试。
### MCP Handler 模块
MCP Handler 是服务器的核心调度器，负责：
- 工具注册与管理
- 请求路由与响应格式化
- API Key 验证
- 工具选择与启用控制
```mermaid
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` 中定义：
```typescript
'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]()
## 工具体系
### 工具分类
| 工具名称 | 默认状态 | 功能描述 | 适用场景 |
|---------|---------|---------|---------|
| `web_search_exa` | 启用 | 语义化网页搜索 | 通用信息检索 |
| `web_search_advanced_exa` | 禁用 | 高级搜索，支持完整过滤参数 | 专业研究场景 |
| `web_fetch_exa` | 启用 | 提取指定 URL 的完整内容 | 内容深度抓取 |
| `deep_search_exa` | 禁用（已废弃） | 深度搜索+查询扩展 | 请使用 web_search_advanced_exa |
### 搜索工具参数架构
基础搜索请求类型定义 (`src/types.ts`)：
```typescript
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 分类限制
```mermaid
graph TB
A{选择 Category} --> B{category: company}
A --> C{category: people}
A --> D{无 category
或 news}
A --> E{category:
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
```
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| `exaApiKey` | string | 服务端备用密钥 | Exa API 密钥 |
| `tools` | string | 见下方 | 逗号分隔的工具列表 |
| `debug` | boolean | false | 启用调试日志 |
**默认启用工具**：`web_search_exa`, `web_fetch_exa`
**完整可用工具**：`web_search_exa`, `web_search_advanced_exa`, `web_fetch_exa`
### 配置发现机制
服务端在 `/.well-known/mcp-config` 路径暴露 JSON Schema 配置描述：
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "/.well-known/mcp-config",
"title": "Exa MCP Server Configuration",
"type": "object",
"properties": {
"exaApiKey": { "type": "string" },
"tools": { "type": "string" },
"debug": { "type": "boolean", "default": false }
}
}
```
资料来源：[api/well-known-mcp-config.ts]()
### 环境变量配置（stdio 传输）
本地运行时通过环境变量配置：
| 环境变量 | 说明 |
|---------|------|
| `EXA_API_KEY` | Exa API 密钥 |
| `DEBUG` | 启用调试模式 |
## 部署模式
### 远程托管模式
```mermaid
graph LR
User[用户] -->|Claude Code / AI 助手| CloudEndpoint["https://mcp.exa.ai/mcp"]
CloudEndpoint --> ExaAPI[Exa API]
ExaAPI --> CloudEndpoint
CloudEndpoint -->|SSE 流| User
```
优点：无需本地安装，无 API Key 泄露风险
### 本地部署模式
```mermaid
graph LR
User[用户] --> Claude[Claude Code]
Claude -->|stdio JSON-RPC| LocalMCP["exa-mcp-server
(本地进程)"]
LocalMCP -->|HTTP| ExaAPI[Exa API]
ExaAPI --> LocalMCP
```
本地部署通过 `npx exa-mcp-server` 启动，需设置 `EXA_API_KEY` 环境变量。
## 版本与构建
| 属性 | 值 |
|-----|---|
| 当前版本 | 3.2.1 |
| 入口模块 | `./src/stdio.ts` |
| 构建产物 | `dist/stdio.cjs` |
构建脚本 (`package.json`)：
```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 | 新版本后工具选择配置失效 | 工具注册机制、URL 参数解析 |
| #86 | HTTP GET 请求返回 405 | HTTP/SSE 传输层、POST-only 限制 |
| #65 | stdio 模式下多 shebang 行导致错误 | 构建流程、stdio 传输层 |
| #108 | 远程端点不可用 | 远程托管模式、可靠性 |
社区反馈表明工具选择配置是用户关注的核心功能点，Issue #48 指出新版本可能改变了工具启用的配置方式。
---
## 传输层实现
### 相关页面
相关主题：[系统架构](#page-architecture), [故障排除指南](#page-troubleshooting)
相关源码文件
以下源码文件用于生成本页说明：
- [src/stdio.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio.ts)
- [src/stdio-cli.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/stdio-cli.ts)
- [api/mcp.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [vercel.json](https://github.com/exa-labs/exa-mcp-server/blob/main/vercel.json)
- [Dockerfile](https://github.com/exa-labs/exa-mcp-server/blob/main/Dockerfile)
# 传输层实现
Exa MCP Server 支持多种传输层协议，以满足不同的部署场景和客户端需求。传输层是 MCP 协议栈中的关键组成部分，负责在 MCP 客户端与服务器之间传递 JSON-RPC 消息。
## 传输层概述
Exa MCP Server 当前实现了两类传输机制：
| 传输类型 | 用途 | 典型场景 |
|---------|------|---------|
| **Stdio** | 标准输入/输出流 | 本地安装、npm 包、Claude Code CLI |
| **HTTP + SSE** | HTTP 长连接 + Server-Sent Events | 远程 MCP 端点、浏览器端集成 |
这种双传输架构使得同一个 MCP 服务器能够同时服务于本地 CLI 工具和远程 API 消费者。
资料来源：[package.json:5-8]()
## Stdio 传输实现
### 工作原理
Stdio 传输是最基础的 MCP 传输方式，通过标准输入（stdin）接收客户端请求，通过标准输出（stdout）返回响应。这种方式特别适合本地进程调用和命令行工具集成。
```mermaid
graph LR
A[MCP 客户端] -->|写入 stdin| B[exa-mcp-server 进程]
B -->|读取 stdout| A
B -->|stderr| C[日志/调试输出]
```
### 构建配置
Stdio 传输通过 esbuild 打包为独立的 CommonJS 可执行文件：
```json
{
"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"
}
}
```
关键配置点：
| 参数 | 值 | 说明 |
|------|-----|------|
| `--format=cjs` | CommonJS | 兼容 Node.js 环境 |
| `--target=node20` | Node 20 | 最低运行环境要求 |
| `--banner:js` | shebang | 使文件可直接执行 |
| `chmod +x` | 可执行权限 | 允许直接运行脚本 |
资料来源：[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：
```bash
npx exa-mcp-server
```
或作为 npm 依赖使用：
```json
{
"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`。这种传输方式支持服务端推送，使服务器能够主动向客户端发送消息。
```mermaid
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 方法**：
| 方法 | 用途 | 状态 |
|------|------|------|
| POST | 初始化连接、发送请求 | ✅ 支持 |
| GET | SSE 流订阅 | ❌ 不支持 (返回 405) |
**请求头要求**：
```
Content-Type: application/json
Accept: text/event-stream
```
资料来源：[社区 Issue #86]()
### 端点配置
远程 MCP 端点支持通过 URL 查询参数进行配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `exaApiKey` | string | 服务器内置密钥 | Exa API 认证密钥 |
| `tools` | string (逗号分隔) | web_search_exa, web_fetch_exa | 启用的工具列表 |
| `debug` | boolean | false | 调试日志开关 |
**完整端点示例**：
```
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 规范的配置发现机制：
```json
{
"$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` 配置边缘函数：
```json
{
"version": 2,
"rewrites": [
{ "source": "/mcp", "destination": "/api/mcp" }
]
}
```
所有 `/mcp` 路径的请求被重写到 `/api/mcp` 处理程序。
资料来源：[vercel.json](https://github.com/exa-labs/exa-mcp-server/blob/main/vercel.json)
### Docker 部署
对于需要自托管的场景，项目提供了 Dockerfile 支持容器化部署：
```dockerfile
# 基础镜像、构建步骤、启动命令
```
Docker 部署特别适合企业内网环境或需要完全控制基础设施的场景。
资料来源：[Dockerfile](https://github.com/exa-labs/exa-mcp-server/blob/main/Dockerfile)
## 工具启用与传输关系
不同的传输层对工具可用性有不同影响：
| 工具 | Stdio 默认 | HTTP 默认 | 说明 |
|------|-----------|----------|------|
| web_search_exa | ✅ | ✅ | 基础网页搜索 |
| web_fetch_exa | ✅ | ✅ | 内容抓取 |
| web_search_advanced_exa | ❌ | ❌ | 高级搜索（需显式启用） |
Stdio 传输默认启用基础工具，高级工具需通过环境变量配置。HTTP 传输通过 URL 参数 `tools` 控制。
## 工具选择配置问题
社区 Issue #48 反映新版本发布后工具选择配置出现回归（regression）。用户之前可以通过配置文件选择可用工具，但新版本可能改变了这一行为。
**受影响配置**：
```json
{
"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 规范进行消息交换：
**请求消息**：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "web_search_exa",
"arguments": {
"query": "示例搜索"
}
}
}
```
**响应消息**：
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "搜索结果内容"
}
]
}
}
```
### 错误处理
| 错误码 | 含义 | 常见原因 |
|--------|------|---------|
| -32700 | Parse error | JSON 格式无效 |
| -32600 | Invalid Request | 缺少必需字段 |
| -32601 | Method not found | 工具名称错误 |
| -32603 | Internal error | 服务器内部异常 |
## 最佳实践
### Stdio 传输
1. **环境变量配置**：将 `EXA_API_KEY` 设置在环境变量中，避免硬编码
2. **版本锁定**：使用 `exa-mcp-server@x.x.x` 锁定版本，防止意外更新
3. **错误日志**：监控 stderr 输出以获取调试信息
### HTTP 传输
1. **安全密钥管理**：不要在 URL 中明文传递 API 密钥（考虑使用服务端代理）
2. **连接复用**：SSE 连接应保持长连接以获得最佳性能
3. **错误重试**：实现指数退避重试机制应对临时性故障
### 传输选择指南
| 场景 | 推荐传输 |
|------|---------|
| Claude Code 集成 | Stdio |
| 自定义 CLI 工具 | Stdio |
| 远程 API 集成 | HTTP + SSE |
| 浏览器扩展 | HTTP + SSE |
| 企业内网部署 | Docker (Stdio) |
## 相关文档
- [完整文档](https://docs.exa.ai/reference/exa-mcp)
- [npm 包](https://www.npmjs.com/package/exa-mcp-server)
- [API 密钥获取](https://dashboard.exa.ai/api-keys)
---
## 工具概览
### 相关页面
相关主题：[基础搜索工具](#page-web-search), [高级搜索工具](#page-advanced-search)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/webFetch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webFetch.ts)
- [src/tools/webSearchAdvanced.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearchAdvanced.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# 工具概览
Exa MCP Server 提供了一套完整的 Web 搜索和内容抓取工具，使 AI 助手能够通过 Model Context Protocol (MCP) 与 Exa 搜索 API 进行交互。本文档详细介绍所有可用工具的功能、参数配置及使用方式。
## 工具体系架构
Exa MCP Server 的工具系统遵循模块化设计原则，核心工具与高级工具分离，支持灵活的启用/禁用控制。
```mermaid
graph TD
A[Exa MCP Server] --> B[核心工具
默认启用]
A --> C[高级工具
按需启用]
A --> D[已废弃工具
向后兼容]
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]
```
## 工具分类与状态
根据工具配置文档，工具分为三类状态：
| 工具类型 | 状态 | 说明 |
|---------|------|------|
| 核心工具 | 默认启用 | `web_search_exa`、`web_fetch_exa` |
| 高级工具 | 默认关闭 | `web_search_advanced_exa` |
| 已废弃工具 | 可用但不推荐 | 提供向后兼容，建议使用替代方案 |
资料来源：[src/mcp-handler.ts:1-15]()
## 核心工具
### 1. web_search_exa（网页搜索）
基础网页搜索工具，提供语义化的自然语言搜索能力。
```typescript
// 工具定义（src/tools/webSearch.ts）
async ({ query, numResults }) => {
const toolId = toolName || 'web_search_exa';
// 从查询字符串提取 category:
const categoryMatch = query.match(/\bcategory:(company|research\s*paper|news|personal\s*site|people)\b/i);
}
```
资料来源：[src/tools/webSearch.ts:30-45]()
#### 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | 是 | - | 自然语言搜索查询，应描述理想页面而非关键词 |
| `numResults` | number | 否 | 10 | 返回的搜索结果数量 |
#### 查询修饰符
可在查询中嵌入以下修饰符：
| 修饰符 | 示例 | 说明 |
|--------|------|------|
| `category:company` | `category:company AI startups` | 搜索公司主页，启用丰富元数据 |
| `category:people` | `category:people John Doe` | 搜索 LinkedIn 公开个人资料 |
| `category:research paper` | `category:research paper LLM` | 搜索学术论文 |
| `category:news` | `category:news Apple announcement` | 搜索新闻报道 |
| `category:personal site` | `category:personal site tutorial` | 搜索个人博客和网站 |
#### 使用示例
```json
// 基础搜索
{
"query": "best practices for React hooks",
"numResults": 5
}
// 公司搜索
{
"query": "category:company Anthropic funding rounds",
"numResults": 10
}
```
### 2. web_fetch_exa（网页抓取）
从指定 URL 提取完整网页内容，支持动态页面和子页面爬取。
```typescript
// 工具定义签名（src/tools/webFetch.ts）
async ({ url, query, contents, subpages, subpageTarget }) => {
// contents 配置内容提取选项
// subpages 配置子页面爬取
}
```
资料来源：[src/tools/webFetch.ts:1-30]()
#### 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `url` | string | 是 | - | 要抓取的网页 URL |
| `query` | string | 否 | - | 提取内容时使用的查询描述 |
| `contents` | object | 否 | 见下方 | 内容提取配置对象 |
| `subpages` | number | 否 | 0 | 要爬取的子页面数量 |
| `subpageTarget` | string[] | 否 | - | 子页面匹配模式 |
#### contents 配置子对象
| 子参数 | 类型 | 说明 |
|--------|------|------|
| `text.maxCharacters` | number | 提取文本的最大字符数 |
| `highlights.maxCharacters` | number | 高亮片段的最大字符数 |
| `highlights.numSentences` | number | 每个 URL 的高亮句子数 |
| `livecrawl` | string | 实时爬取模式：`never`、`fallback`、`always`、`preferred` |
| `maxAgeHours` | number | 缓存内容的最大有效期（小时） |
| `livecrawlTimeout` | number | 实时爬取超时时间（秒） |
## 高级工具
### 3. web_search_advanced_exa（高级搜索）
提供完整的搜索过滤功能，包括域名限制、日期范围、内容过滤和子页面爬取。
```typescript
// 工具定义（src/tools/webSearchAdvanced.ts）
// 支持完整的参数配置
```
资料来源：[src/tools/webSearchAdvanced.ts:1-50]()
#### 搜索类型
| type | 说明 | 典型响应时间 |
|------|------|-------------|
| `auto` | 自动选择最佳搜索策略 | 快速 |
| `fast` | 快速搜索，返回基础结果 | < 1s |
| `deep` | 深度搜索，提取丰富内容 | 4-12s |
| `instant` | 即时搜索，仅返回元数据 | < 500ms |
#### 类别过滤
| category | 说明 | 特殊限制 |
|-----------|------|----------|
| `company` | 公司主页，启用 headcount、location、funding 等丰富元数据 | 不支持 `includeDomains`、`excludeDomains`、`startPublishedDate`、`endPublishedDate` |
| `research paper` | 学术论文和预印本 | 无特殊限制 |
| `news` | 新闻报道和公告 | 支持域名和日期过滤 |
| `people` | LinkedIn 公开个人资料 | 无其他过滤选项 |
| `personal site` | 个人博客和作品集 | 支持完整过滤 |
| `pdf` | PDF 文档 | 支持内容提取 |
| `github` | GitHub 代码仓库 | 支持代码相关内容 |
| `financial report` | 财务报告和 SEC 文件 | 支持日期过滤 |
#### 重要限制
> ⚠️ **已知问题**：`includeText` 和 `excludeText` 参数仅支持**单元素数组**。多元素数组会导致 400 错误。如需匹配多个术语，请将它们放在 `query` 字符串中或运行单独搜索。
资料来源：[src/types.ts:15-25]()
#### 参数说明
| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | string | 自然语言搜索查询（必填） |
| `category` | string | 搜索类别 |
| `numResults` | number | 返回结果数量（默认：10） |
| `type` | string | 搜索深度类型 |
| `includeDomains` | string[] | 要包含的域名列表 |
| `excludeDomains` | string[] | 要排除的域名列表 |
| `startPublishedDate` | string | 最早发布日期（ISO 8601） |
| `endPublishedDate` | string | 最晚发布日期（ISO 8601） |
| `includeText` | string[] | 必须包含所有指定文本 |
| `excludeText` | string[] | 排除包含任一指定文本的结果 |
| `userLocation` | string | 用户地理位置（影响本地化结果） |
| `enableHighlights` | boolean | 启用内容高亮 |
| `enableSummary` | boolean | 启用内容摘要 |
| `textMaxCharacters` | number | 提取文本的最大字符数 |
| `subpages` | number | 子页面爬取数量 |
| `additionalQueries` | string[] | 扩展查询列表（最多5个） |
## 已废弃工具（向后兼容）
以下工具仍可用，但建议迁移到新工具：
| 已废弃工具 | 替代工具 | 说明 |
|-----------|----------|------|
| `get_code_context_exa` | `web_search_exa` | 代码片段搜索 |
| `company_research_exa` | `web_search_advanced_exa` | 公司研究 |
| `crawling_exa` | `web_fetch_exa` | 网页抓取 |
| `people_search_exa` | `web_search_advanced_exa` | 人物搜索 |
| `linkedin_search_exa` | `web_search_advanced_exa` | LinkedIn 搜索 |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) | 深度研究任务 |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) | 研究任务状态 |
| `deep_search_exa` | `web_search_advanced_exa` | 深度搜索 |
资料来源：[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
```
| 参数 | 说明 |
|------|------|
| `exaApiKey` | Exa API 密钥（可选，服务器有备用密钥） |
| `tools` | 逗号分隔的启用工具列表 |
资料来源：[api/well-known-mcp-config.ts:15-30]()
### 可用工具列表
| 工具名称 | 可用值 |
|----------|--------|
| `web_search_exa` | ✓ |
| `web_search_advanced_exa` | ✓ |
| `web_fetch_exa` | ✓ |
### Claude Code 配置示例
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
## 工具响应格式
### 搜索响应结构
```typescript
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[];
extras?: {
links?: string[];
imageLinks?: string[];
};
subpages?: ExaSearchResult[];
}
```
资料来源：[src/types.ts:50-75]()
### 响应字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `requestId` | string | 请求唯一标识符 |
| `results` | array | 搜索结果数组 |
| `results[].title` | string | 结果标题 |
| `results[].url` | string | 结果 URL |
| `results[].text` | string | 提取的完整文本内容 |
| `results[].highlights` | string[] | 内容高亮片段 |
| `results[].publishedDate` | string | 发布日期 |
| `results[].author` | string | 作者 |
| `results[].image` | string | 相关图片 URL |
| `results[].score` | number | 相关性分数 |
| `searchTime` | number | 搜索耗时（毫秒） |
| `costDollars` | object | API 成本信息 |
## 常见问题与已知问题
### 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 失败。
**临时解决方案**：自行从源码构建，避免使用预编译包：
```bash
npm run build:stdio
```
## 工作流程图
```mermaid
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` 控制工具启用状态，以获得最佳性能和功能体验。
---
## 基础搜索工具
### 相关页面
相关主题：[工具概览](#page-tools-overview), [高级搜索工具](#page-advanced-search)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/webFetch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webFetch.ts)
- [src/tools/validation.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/validation.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/utils/exaResponseSanitizer.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/exaResponseSanitizer.ts)
# 基础搜索工具
## 概述
基础搜索工具是 Exa MCP Server 提供的一组核心功能模块，包括 `web_search_exa`（基础网页搜索）和 `web_fetch_exa`（网页内容抓取）。这两个工具默认启用，为 AI 助手提供实时网页搜索和内容提取能力。
在 MCP 工具生态中，基础搜索工具扮演着**默认入口**的角色。用户无需额外配置即可使用，满足日常网页搜索和简单内容抓取需求。对于更复杂的高级搜索场景（如精确的域名过滤、日期范围控制等），则需要启用 `web_search_advanced_exa` 高级搜索工具。资料来源：[src/mcp-handler.ts:1-15]()
## 工具架构
```mermaid
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` 是最常用的搜索工具，设计目标是快速获取与查询相关的网页内容。
#### 功能特点
| 特性 | 描述 |
|------|------|
| 查询方式 | 自然语言语义搜索，支持语义描述而非关键词堆砌 |
| 默认结果数 | 10 条 |
| 内容提取 | 自动返回网页摘要和高亮片段 |
| 分类支持 | 可在查询中指定 `category:<类型>` 进行定向搜索 |
#### 支持的分类类型
| 分类值 | 说明 | 典型用途 |
|--------|------|----------|
| `company` | 公司信息 | 企业研究、竞品分析 |
| `people` | 人物资料 | 查找 LinkedIn 公开个人资料 |
| `research paper` | 学术论文 | 学术搜索、论文发现 |
| `news` | 新闻报道 | 媒体报道、新闻事件 |
| `personal site` | 个人网站 | 博主文章、独立博客 |
资料来源：[src/tools/webSearch.ts:1-30]()
#### 使用示例
```javascript
// 基础网页搜索
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 客户端优化调用行为：
| 标记 | 值 | 说明 |
|------|-----|------|
| `readOnlyHint` | true | 表明这是只读操作 |
| `destructiveHint` | false | 不会产生副作用 |
| `openWorldHint` | false | 不访问外部开放网络 |
| `idempotentHint` | true | 幂等操作，可安全重试 |
资料来源：[src/tools/webSearch.ts:55-60]()
### web_fetch_exa（网页内容抓取）
`web_fetch_exa` 用于获取特定 URL 的完整网页内容，作为搜索结果的深度补充。
#### 功能定位
当 `web_search_exa` 返回的高亮片段（highlights）不足以满足需求时，可使用此工具获取目标网页的完整内容。
#### 使用场景
1. **深入阅读**：搜索结果摘要不完整，需要全文内容
2. **结构化提取**：提取网页中的特定信息（如联系方式、价格表等）
3. **动态页面**：需要执行 JavaScript 才能渲染的页面
## 搜索结果数据结构
### ExaSearchResult 类型定义
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 结果唯一标识符 |
| `title` | string \| null | 网页标题 |
| `url` | string | 网页完整 URL |
| `publishedDate` | string | 发布日期（ISO 8601） |
| `author` | string | 作者/来源 |
| `text` | string | 文本内容摘要 |
| `summary` | string | AI 生成的内容摘要 |
| `highlights` | string[] | 高亮匹配片段 |
| `highlightScores` | number[] | 高亮片段相关度分数 |
| `image` | string | 文章/页面主图 URL |
| `favicon` | string | 网站 favicon |
| `score` | number | 综合相关度得分 |
| `entities` | Record[] | 提取的实体信息 |
| `extras.links` | string[] | 页面内链接列表 |
| `extras.imageLinks` | string[] | 页面内图片链接 |
| `subpages` | ExaSearchResult[] | 子页面抓取结果 |
资料来源：[src/types.ts:1-40]()
## 查询解析机制
### category 字段提取
`web_search_exa` 支持在查询字符串中嵌入分类指令。解析逻辑如下：
```mermaid
graph LR
A[原始查询字符串] --> B{正则匹配
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，用于日志追踪：
```typescript
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]()
## 配置与部署
### 默认启用状态
| 工具 | 默认状态 | 说明 |
|------|----------|------|
| `web_search_exa` | ✅ 启用 | 基础搜索默认开启 |
| `web_fetch_exa` | ✅ 启用 | 内容抓取默认开启 |
| `web_search_advanced_exa` | ❌ 关闭 | 需要显式启用 |
### 远程 MCP 配置
```javascript
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
### 使用托管端点
推荐使用 Exa 托管的远程 MCP 服务器：
```
https://mcp.exa.ai/mcp
```
此端点默认启用基础搜索工具，无需本地安装。
## 与高级搜索工具对比
| 对比维度 | 基础搜索 (web_search_exa) | 高级搜索 (web_search_advanced_exa) |
|----------|---------------------------|-----------------------------------|
| 域名过滤 | ❌ 不支持 | ✅ 支持 includeDomains/excludeDomains |
| 日期范围 | ❌ 不支持 | ✅ 支持 startPublishedDate/endPublishedDate |
| 文本过滤 | 基础支持 | ✅ 支持 includeText/excludeText |
| 内容提取 | 固定摘要 | ✅ 可配置 textMaxCharacters/contextMaxCharacters |
| 子页面抓取 | ❌ 不支持 | ✅ 支持 subpages/subpageTarget |
| 实时爬取 | ❌ 不支持 | ✅ 支持 livecrawl 参数 |
资料来源：[README.md:1-50]()
## 最佳实践
### 1. 查询优化
**推荐做法**：描述理想页面而非罗列关键词
```javascript
// ✅ 推荐：语义化描述
"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`
---
## 高级搜索工具
### 相关页面
相关主题：[工具概览](#page-tools-overview), [基础搜索工具](#page-web-search)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
# 高级搜索工具
## 概述
高级搜索工具（`web_search_advanced_exa`）是 Exa MCP Server 提供的增强型搜索功能，相较于基础搜索工具，提供了更细粒度的控制能力。该工具默认情况下处于**禁用状态**，需要通过配置参数显式启用。资料来源：[src/mcp-handler.ts:14]()
高级搜索工具的核心能力包括：
- **完整过滤器支持**：支持域名过滤、日期范围、文本匹配等所有高级参数
- **内容类别搜索**：针对特定内容类型（公司、研究论文、新闻等）优化的搜索模式
- **内容提取控制**：可自定义摘要生成、高亮提取和子页面爬取
- **结构化输出**：支持自定义 JSON 输出格式
```mermaid
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]()
### 默认工具列表
| 工具名称 | 默认状态 | 功能说明 |
|---------|---------|----------|
| `web_search_exa` | 启用 | 基础网页搜索 |
| `web_fetch_exa` | 启用 | 网页内容抓取 |
| `web_search_advanced_exa` | 禁用 | 高级搜索（需显式启用）|
资料来源：[api/well-known-mcp-config.ts:3-5]()
## API 参数详解
### 核心参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|-------|------|
| `query` | string | 是 | - | 自然语言搜索查询，描述理想页面而非简单关键词 |
| `category` | string | 否 | auto | 内容类别：company, research paper, news, pdf, github, personal site, people, financial report |
| `numResults` | number | 否 | 10 | 返回结果数量 |
| `type` | string | 否 | auto | 搜索深度：auto, fast, deep, instant |
资料来源：[src/types.ts:1-15]()
### 域名过滤参数
| 参数名 | 类型 | 说明 |
|-------|------|------|
| `includeDomains` | string[] | 限定结果来源的域名列表 |
| `excludeDomains` | string[] | 排除的域名列表 |
### 日期过滤参数（ISO 8601 格式）
| 参数名 | 类型 | 说明 |
|-------|------|------|
| `startPublishedDate` | string | 内容发布日期下限 |
| `endPublishedDate` | string | 内容发布日期上限 |
| `startCrawlDate` | string | 爬取日期下限 |
| `endCrawlDate` | string | 爬取日期上限 |
### 文本过滤参数
| 参数名 | 类型 | 说明 |
|-------|------|------|
| `includeText` | string[] | 结果必须包含的文本（所有项都匹配） |
| `excludeText` | string[] | 结果必须排除的文本（任一项匹配则排除） |
**重要限制**：`includeText` 和 `excludeText` 仅支持**单元素数组**。多元素数组会导致 400 错误。
资料来源：[src/types.ts:12-13]()
## 内容类别系统
### 支持的类别
```mermaid
graph LR
A[高级搜索] --> B[company
公司主页]
A --> C[research paper
研究论文]
A --> D[news
新闻报道]
A --> E[pdf
PDF文档]
A --> F[github
代码仓库]
A --> G[personal site
个人网站]
A --> H[people
人物搜索]
A --> I[financial report
财务报告]
```
### 类别说明
| 类别 | 用途 | 过滤器限制 |
|------|------|-----------|
| `company` | 公司主页，丰富的元数据（员工数、位置、融资、收入） | 不支持 includeDomains/excludeDomains、日期过滤 |
| `research paper` | 学术论文，支持完整的日期和域名过滤 | 无限制 |
| `news` | 新闻报道和公告 | 支持所有过滤器 |
| `people` | LinkedIn 公开个人资料 | 无其他过滤器 |
| `personal site` | 个人博客和作品集 | 支持所有过滤器 |
| `financial report` | 年报、投资者演示、财务报表 | 支持所有过滤器 |
资料来源：[src/types.ts:2]()
### company 类别的特殊限制
当使用 `category: "company"` 时，以下参数会导致 400 错误：
- `includeDomains` / `excludeDomains`
- `startPublishedDate` / `endPublishedDate`
- `startCrawlDate` / `endCrawlDate`
## 内容提取配置
### 内容块配置
```typescript
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]()
### 配置项说明
| 配置项 | 类型 | 说明 |
|-------|------|------|
| `text.maxCharacters` | number | 提取文本的最大字符数 |
| `context.maxCharacters` | number | 上下文的最大字符数 |
| `summary` | boolean/object | 启用摘要生成，可指定查询 |
| `highlights` | object | 高亮配置：字符数、句子数、每 URL 数量 |
| `livecrawl` | enum | 实时爬取模式：never/fallback/always/preferred |
| `subpages` | number | 爬取的子页面数量 |
| `subpageTarget` | string[] | 子页面目标 URL 模式 |
## 搜索结果模型
### ExaSearchResult 结构
```typescript
interface ExaSearchResult {
id?: string;
title?: string | null;
url?: string;
publishedDate?: string;
author?: string;
text?: string;
summary?: string;
highlights?: string[];
highlightScores?: number[];
image?: string;
favicon?: string;
score?: number;
entities?: Record[];
extras?: {
links?: string[];
imageLinks?: string[];
};
subpages?: ExaSearchResult[];
}
```
资料来源：[src/types.ts:37-54]()
## 深度搜索模式
深度搜索（`deepSearch`）是高级搜索的扩展模式，提供更深入的分析能力：
| 参数 | 类型 | 说明 |
|------|------|------|
| `objective` | string | 搜索目标的自然语言描述 |
| `search_queries` | string[] | 最多 5 个相关关键词查询（每个最多 5 词） |
| `type` | deep/deep-reasoning | 搜索深度：deep (4-12s)，deep-reasoning (12-50s) |
| `numResults` | number | 返回结果数量 |
| `outputSchema` | object | JSON Schema 用于结构化输出 |
| `systemPrompt` | string | 代理处理指令（最多 32000 字符） |
资料来源：[src/tools/deepSearch.ts:8-25]()
### 深度搜索输出格式
深度搜索会自动格式化响应，包含：
1. **摘要部分**：基于 `objective` 的分析摘要
2. **引用部分**：所有引用的 Markdown 链接格式
3. **结果部分**：逐条呈现的搜索结果，包含标题、URL、日期、图片和高亮
资料来源：[src/tools/deepSearch.ts:55-80]()
## 使用示例
### 基础公司研究
```json
{
"query": "AI infrastructure startups San Francisco",
"category": "company",
"numResults": 20,
"type": "auto"
}
```
### 研究论文搜索
```json
{
"query": "LLM reasoning capabilities",
"includeDomains": ["arxiv.org", "openreview.net"],
"includeText": ["transformer"],
"numResults": 20,
"type": "deep"
}
```
### 带内容提取的深度搜索
```json
{
"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 方法可以正常连接。
## 相关资源
- [完整文档](https://docs.exa.ai/reference/exa-mcp)
- [API Key 获取](https://dashboard.exa.ai/api-keys)
- [npm 包](https://www.npmjs.com/package/exa-mcp-server)
---
## 部署配置
### 相关页面
相关主题：[认证与授权](#page-authentication), [安装指南](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
# 部署配置
Exa MCP Server 提供多种部署方式，支持本地运行（stdio 传输）、远程服务器部署（HTTP/SSE 传输）以及通过 Vercel 等平台托管。合理的部署配置能够满足不同客户端和环境的需求。
## 部署方式概览
| 部署方式 | 传输协议 | 适用场景 | API Key 要求 |
|----------|----------|----------|--------------|
| 本地 stdio | stdio | Claude Code Desktop、Smithery | 必需（本地环境变量） |
| 远程 HTTP | HTTP/SSE | Web 应用、API 网关 | 可选（URL 参数传递） |
| Docker 容器 | stdio/HTTP | 生产环境隔离部署 | 可配置 |
| Vercel 托管 | HTTP | Serverless 无服务器部署 | 环境变量配置 |
## 环境变量配置
### 必需参数
| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `EXA_API_KEY` | Exa API 密钥，用于认证搜索请求 | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
### 获取 API Key
访问 [Exa Dashboard API Keys](https://dashboard.exa.ai/api-keys) 页面创建新的 API 密钥。
### 环境变量配置示例
```bash
# Linux/macOS
export EXA_API_KEY="your_api_key_here"
# Windows (PowerShell)
$env:EXA_API_KEY="your_api_key_here"
```
### 构建时环境变量
根据 `package.json` 中的构建配置：
```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 等桌面集成场景。
### 安装方式
```bash
# 通过 npx 直接运行
npx -y exa-mcp-server
# 全局安装
npm install -g exa-mcp-server
```
### Claude Code 配置
在 Claude Code 中配置 MCP 服务器，需要修改 Claude Code 的 MCP 配置文件：
```json
{
"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：
```json
{
"scripts": {
"build:stdio": "esbuild ... --banner:js=\"#!/usr/bin/env node\" && chmod +x dist/stdio.cjs"
}
}
```
**临时解决方案**：手动修复 `.smithery/index.cjs` 文件，删除重复的 shebang 行。
## 远程 HTTP/SSE 部署
远程部署允许客户端通过 HTTP 连接访问 MCP 服务器，无需本地安装。
### 基础端点配置
| 参数 | 说明 | 默认值 |
|------|------|--------|
| 端点 URL | MCP 服务器地址 | `https://mcp.exa.ai/mcp` |
| 传输协议 | Server-Sent Events | HTTP POST |
| 认证方式 | API Key（可选） | URL 参数传递 |
### 启用工具选择
通过 `tools` 查询参数指定启用的工具集：
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa
```
资料来源：[README.md:1-200]()
### 可用工具列表
**默认启用的工具**：
| 工具名称 | 功能描述 |
|----------|----------|
| `web_search_exa` | 通用网页搜索，返回清洗后的内容 |
| `web_fetch_exa` | 从指定 URL 获取完整网页内容 |
**默认禁用的工具**（需要显式启用）：
| 工具名称 | 功能描述 |
|----------|----------|
| `web_search_advanced_exa` | 高级搜索，支持完整过滤参数 |
### 已废弃工具（保持向后兼容）
| 废弃工具 | 替代工具 |
|----------|----------|
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `deep_researcher_start` | [Research API](https://docs.exa.ai/reference/research/create-a-task) |
| `deep_researcher_check` | [Research API](https://docs.exa.ai/reference/research/get-a-task) |
| `deep_search_exa` | `web_search_advanced_exa` |
资料来源：[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 客户端。
## 部署架构流程
```mermaid
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
# 示例 Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["node", "dist/stdio.cjs"]
```
### 运行容器
```bash
# 构建镜像
docker build -t exa-mcp-server .
# 运行容器
docker run -e EXA_API_KEY="your_api_key" exa-mcp-server
```
## Vercel 部署配置
### vercel.json 配置
```json
{
"builds": [
{
"src": "src/vercel-server.ts",
"use": "@vercel/node"
}
],
"routes": [
{
"src": "/mcp",
"dest": "src/vercel-server.ts"
}
]
}
```
### 构建脚本
根据 `package.json` 中的 Vercel 构建配置：
```json
{
"scripts": {
"build:vercel": "npm install typescript && ./node_modules/.bin/tsc"
}
}
```
资料来源：[package.json:1-45]()
## 工具配置参考
### 高级搜索分类配置
当使用 `web_search_advanced_exa` 时，搜索类别决定可用参数：
| 类别 | 说明 | 域过滤 | 日期过滤 |
|------|------|--------|----------|
| `company` | 公司首页、丰富元数据 | ❌ 不支持 | ❌ 不支持 |
| `news` | 新闻报道、公告 | ✅ 支持 | ✅ 支持 |
| `people` | LinkedIn 公开档案 | ✅ 支持 | ✅ 支持 |
| `research paper` | 学术论文 | ✅ 支持 | ✅ 支持 |
| `financial report` | 财务报告 | ✅ 支持 | ✅ 支持 |
| `personal site` | 个人博客 | ✅ 支持 | ✅ 支持 |
资料来源：[README.md:1-200]()
### 通用参数限制
| 参数 | 限制说明 |
|------|----------|
| `includeText` / `excludeText` | 仅支持**单元素数组**，多元素会导致 400 错误 |
| `textMaxCharacters` | 内容提取的最大字符数 |
| `contextMaxCharacters` | 上下文的最大字符数 |
## 常见部署问题
### 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. 考虑使用本地部署作为备选方案
## 快速部署指南
### 方式一：远程（推荐新手）
```bash
# Claude Code 配置
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY"
```
### 方式二：本地 stdio
```bash
# 安装 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
```bash
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 文档](https://docs.exa.ai/reference/exa-mcp) |
| npm 包 | [exa-mcp-server](https://www.npmjs.com/package/exa-mcp-server) |
| API Key | [Exa Dashboard](https://dashboard.exa.ai/api-keys) |
| 源码仓库 | [GitHub](https://github.com/exa-labs/exa-mcp-server) |
---
## 认证与授权
### 相关页面
相关主题：[部署配置](#page-deployment), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [api/mcp-oauth.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/mcp-oauth.ts)
- [api/well-known-mcp-config.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-mcp-config.ts)
- [api/well-known-oauth-protected-resource.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/api/well-known-oauth-protected-resource.ts)
- [src/utils/auth.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/auth.ts)
- [src/utils/mcpClientMetadata.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/utils/mcpClientMetadata.ts)
# 认证与授权
Exa MCP Server 支持多种认证与授权机制，以确保 API 访问的安全性和可控性。本页详细介绍认证方式、配置参数、安全机制以及最佳实践。
## 概述
Exa MCP Server 的认证与授权系统主要包含以下核心功能：
| 组件 | 描述 |
|------|------|
| **API Key 认证** | 通过 `EXA_API_KEY` 环境变量或 URL 参数传递 API 密钥 |
| **工具级别授权** | 通过 `tools` 参数控制用户可访问的工具范围 |
| **OAuth 2.0 支持** | 支持 OAuth 2.0 授权码流程访问受保护资源 |
| **客户端元数据** | 识别和记录 MCP 客户端信息用于审计 |
资料来源：[api/well-known-mcp-config.ts:1-60]()
## API Key 认证
### 环境变量方式（推荐）
在本地部署或通过 npx 运行 MCP Server 时，推荐使用环境变量配置 API 密钥：
```bash
export EXA_API_KEY="your_api_key_here"
npx exa-mcp-server
```
对于不同的 MCP 客户端配置方式：
```json
// Claude Code 配置示例
{
"mcpServers": {
"exa-mcp-server": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
资料来源：[npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/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
```
这种方式的配置结构如下：
| 参数 | 类型 | 描述 |
|------|------|------|
| `exaApiKey` | string | 您的 Exa AI API 密钥（可选 - 服务器有备用密钥） |
| `tools` | string | 逗号分隔的工具列表，启用特定功能 |
| `debug` | boolean | 启用调试日志（默认: false） |
资料来源：[api/well-known-mcp-config.ts:17-35]()
### API Key 安全配置架构
```mermaid
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 错误]
```
## 工具级别授权
### 默认工具
系统默认启用以下工具：
| 工具 | 描述 | 默认状态 |
|------|------|----------|
| `web_search_exa` | 通用网页搜索 | ✅ 启用 |
| `web_fetch_exa` | 提取特定 URL 的网页内容 | ✅ 启用 |
| `web_search_advanced_exa` | 高级搜索，支持完整过滤选项 | ❌ 禁用 |
资料来源：[npm.readme.md](https://github.com/exa-labs/exa-mcp-server/blob/main/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
```
可用工具完整列表：
| 工具名 | 说明 | 推荐用途 |
|--------|------|----------|
| `web_search_exa` | 标准网页搜索 | 通用搜索需求 |
| `web_search_advanced_exa` | 高级搜索 | 精确筛选、深度研究 |
| `web_fetch_exa` | 内容抓取 | 提取特定页面全文 |
资料来源：[api/well-known-mcp-config.ts:35-45]()
### 已废弃工具（向后兼容）
以下工具已废弃但仍可用：
| 废弃工具 | 替代方案 |
|----------|----------|
| `get_code_context_exa` | `web_search_exa` |
| `company_research_exa` | `web_search_advanced_exa` |
| `crawling_exa` | `web_fetch_exa` |
| `people_search_exa` | `web_search_advanced_exa` |
| `deep_search_exa` | `web_search_advanced_exa` |
## OAuth 2.0 授权
### 受保护资源配置
Exa MCP Server 实现了 OAuth 2.0 受保护资源发现端点，支持标准的授权流程：
```typescript
// 资源配置数据结构
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 认证流程
```mermaid
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: 返回受保护资源
```
### 授权端点元数据
| 字段 | 描述 |
|------|------|
| `resource` | 资源 URI |
| `scopes_supported` | 支持的权限范围列表 |
| `authorization_types_supported` | 支持的授权类型 |
| `token_endpoint_auth_methods_supported` | Token 端点支持的认证方法 |
| `endpoint_aliases` | 端点别名映射 |
## 客户端元数据
### 元数据收集机制
MCP Server 会收集客户端元数据用于审计和安全追踪：
```typescript
interface MCPClientMetadata {
clientId?: string; // 客户端标识符
clientName?: string; // 客户端名称
clientVersion?: string; // 客户端版本
transportType?: string; // 传输类型 (stdio/http)
endpoint?: string; // 连接的端点
}
```
资料来源：[src/utils/mcpClientMetadata.ts]()
### 元数据用途
| 用途 | 说明 |
|------|------|
| 安全审计 | 记录哪些客户端访问了 API |
| 故障排查 | 识别特定客户端的问题 |
| 配额管理 | 按客户端分配和追踪使用限额 |
| 合规报告 | 生成访问日志满足合规要求 |
## 安全最佳实践
### 环境变量 vs URL 参数
| 方式 | 适用场景 | 安全性 |
|------|----------|--------|
| 环境变量 | 本地开发、生产部署 | ⭐⭐⭐ 高 - 不暴露在 URL 中 |
| URL 参数 | 快速测试、临时访问 | ⭐⭐ 中 - 可能记录在日志中 |
### 安全建议
1. **优先使用环境变量** - API 密钥不应出现在 URL、代码仓库或日志中
2. **最小权限原则** - 仅启用必需的 `tools`，减少攻击面
3. **定期轮换密钥** - 定期更换 API 密钥降低泄露风险
4. **监控访问日志** - 关注异常访问模式
5. **使用 HTTPS** - 确保传输层加密
## 故障排除
### 常见认证错误
| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `401 Unauthorized` | API 密钥无效或缺失 | 检查 `EXA_API_KEY` 配置 |
| `403 Forbidden` | 工具未启用 | 在 URL 中添加 `tools` 参数 |
| `405 Method Not Allowed` | HTTP 方法不支持 | 确保客户端使用正确的传输方式 |
### 社区相关问题
**Issue #86: HTTP SSE 端点返回 405 错误**
部分 MCP 客户端（如通用 MCP 客户端）使用标准 Server-Sent Events 的 GET 方法连接，但当前端点配置导致返回 `405 Method Not Allowed`。建议使用支持 POST 方法的客户端或检查[官方文档](https://docs.exa.ai/reference/exa-mcp)获取最新支持的方法。
**Issue #48: 新版本发布后工具选择问题**
有用户反馈新版本发布后，通过配置选择可用工具的方式发生了变化。确保使用正确的 URL 参数格式 `?tools=web_search_exa,web_search_advanced_exa`。
## 相关文件参考
| 文件 | 功能 |
|------|------|
| `api/mcp-oauth.ts` | OAuth 2.0 核心实现 |
| `api/well-known-mcp-config.ts` | 配置发现 JSON Schema |
| `api/well-known-oauth-protected-resource.ts` | 受保护资源元数据 |
| `src/utils/auth.ts` | 认证工具函数 |
| `src/utils/mcpClientMetadata.ts` | 客户端元数据收集 |
## 延伸阅读
- [Exa MCP 完整文档](https://docs.exa.ai/reference/exa-mcp)
- [Exa API 密钥管理](https://dashboard.exa.ai/api-keys)
- [npm 包说明](https://www.npmjs.com/package/exa-mcp-server)
---
## 故障排除指南
### 相关页面
相关主题：[传输层实现](#page-transport)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/webSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/webSearch.ts)
- [src/tools/deepSearch.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/tools/deepSearch.ts)
- [src/types.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/types.ts)
- [src/mcp-handler.ts](https://github.com/exa-labs/exa-mcp-server/blob/main/src/mcp-handler.ts)
- [package.json](https://github.com/exa-labs/exa-mcp-server/blob/main/package.json)
- [README.md](https://github.com/exa-labs/exa-mcp-server/blob/main/README.md)
# 故障排除指南
本指南旨在帮助用户诊断和解决 exa-mcp-server 使用过程中遇到的常见问题。基于社区反馈和源码分析，涵盖连接问题、工具配置、API 调用错误等场景。
## 常见问题概览
| 问题类别 | 症状 | 影响范围 |
|---------|------|---------|
| 连接失败 | 405 Method Not Allowed | HTTP 传输模式 |
| 工具不可用 | 找不到指定工具 | 所有 MCP 客户端 |
| 认证失败 | EXA_API_KEY 相关错误 | 需要认证的功能 |
| 服务不可用 | 端点无响应 | 远程服务器 |
| 构建错误 | shebang 多行问题 | stdio 传输模式 |
## 连接问题
### 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` 时出现超时或连接拒绝。
**排查步骤**：
```mermaid
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
```
**可用工具列表**：
| 工具名称 | 默认状态 | 说明 |
|---------|---------|------|
| `web_search_exa` | 启用 | 通用网页搜索 |
| `web_fetch_exa` | 启用 | 抓取特定 URL 内容 |
| `web_search_advanced_exa` | 关闭 | 高级搜索，支持完整过滤选项 |
**配置示例**（Claude Code）：
```json
{
"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` 仅支持单元素数组
```javascript
// 错误写法
{
"includeText": ["LLM", "transformer"] // 会导致 400 错误
}
// 正确写法
{
"includeText": ["LLM"],
"query": "transformer" // 将第二个词放入查询字符串
}
```
2. **category 特定限制**：当使用 `category: "company"` 时，以下参数会导致 400 错误：
- `includeDomains` / `excludeDomains`
- `startPublishedDate` / `endPublishedDate`
- `startCrawlDate` / `endCrawlDate`
## API 认证问题
### API Key 配置
**方式一：环境变量**
```bash
export EXA_API_KEY=your_api_key_here
```
**方式二：URL 参数**
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY
```
**验证配置**：可访问 [Exa Dashboard](https://dashboard.exa.ai/api-keys) 查看 API Key 状态。
### 认证失败处理
```mermaid
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` 中的构建脚本：
```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` 工具具有内置超时机制：
| 搜索类型 | 预期耗时 | 超时处理 |
|---------|---------|---------|
| `deep` | 4-12 秒 | 自动重试或返回部分结果 |
| `deep-reasoning` | 12-50 秒 | 需要更长等待时间 |
### 错误响应格式
```typescript
interface ExaSearchStatus {
id: string;
status: string;
source: string;
error?: {
tag: string;
httpStatusCode?: number | null;
};
}
```
**常见错误标签**：
| tag | 说明 | 处理建议 |
|-----|------|---------|
| `invalid_api_key` | API Key 无效或过期 | 检查并更新 EXA_API_KEY |
| `rate_limit_exceeded` | 请求频率超限 | 降低请求频率 |
| `internal_error` | 服务器内部错误 | 稍后重试 |
| `timeout` | 请求超时 | 增加超时时间或简化查询 |
## 日志调试
### 启用调试模式
通过 `debug` 参数启用详细日志：
```
https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&debug=true
```
**日志输出示例**：
每个请求会生成唯一请求 ID：
```typescript
const requestId = `${toolId}-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
```
日志包含：
- 请求参数
- API 响应时间 (`searchTime`)
- 成本信息 (`costDollars`)
- 错误详情
### 日志内容结构
```typescript
interface ExaSearchResponse {
requestId: string;
autopromptString?: string;
autoDate?: string;
resolvedSearchType: string;
results: ExaSearchResult[];
searchTime?: number;
costDollars?: ExaCostDollars;
}
interface ExaCostDollars {
total: number;
search?: Record;
contents?: Record;
}
```
## 客户端兼容性
### 支持的传输方式
| 传输方式 | 支持状态 | 配置复杂度 |
|---------|---------|-----------|
| HTTP/SSE | 推荐 | 低 |
| Stdio | 可用 | 中 |
### 客户端配置示例
**Cursor**：
```json
{
"mcpServers": {
"exa": {
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
**VS Code**：
```json
{
"mcpServers": {
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
}
}
}
```
**本地部署**：
```json
{
"mcpServers": {
"exa": {
"command": "npx",
"args": ["-y", "exa-mcp-server"],
"env": {
"EXA_API_KEY": "your_api_key"
}
}
}
}
```
## 获取帮助
如果问题仍未解决：
1. **查看官方文档**：[Exa MCP 文档](https://docs.exa.ai/reference/exa-mcp)
2. **检查 npm 包信息**：[exa-mcp-server](https://www.npmjs.com/package/exa-mcp-server)
3. **提交 Issue**：在 [GitHub 仓库](https://github.com/exa-labs/exa-mcp-server) 报告问题
## 版本信息
当前稳定版本：`3.2.1`
建议始终使用最新版本以获得 bug 修复和性能改进。
---
---
## Doramagic 踩坑日志
项目：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