免 key 先跑通：把 Exa 托管 MCP 接进 Claude Code / Cursor

你将得到什么

• 一个已连上 Exa 的 Claude Code（或 Cursor / VS Code），能搜网页、读网页
• 一个 exa-mcp-check.sh 自检脚本：不依赖任何客户端，直接验证 MCP 服务器是否可用
• 分清 Exa MCP 的三种认证方式：免 key、OAuth 登录、API key
• 知道默认只开放哪两个工具，以及怎么用 tools 参数打开更多

一、先认识这个地址

Exa 官方提供一个托管 MCP 服务器，任何支持远程 MCP 的客户端都能连：

https://mcp.exa.ai/mcp

官方文档写明：起步不需要 API key。免 key 连接使用免费的限速额度；登录或填 key 之后，用量计入你自己的 Exa 团队。

二、接进 Claude Code

先确认已装好 Claude Code（claude --version 能打印版本号）。在项目目录里运行官方文档给出的命令：

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

对照结果（实测，路径会是你自己的）：

Added HTTP MCP server exa with URL: https://mcp.exa.ai/mcp to local config
File modified: /home/you/.claude.json [project: /home/you/proj]

默认作用域是 local，只对当前项目生效。想在所有项目里都能用，加 --scope user：

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

确认连接状态：

claude mcp list

对照结果（实测）：

Checking MCP server health…

exa: https://mcp.exa.ai/mcp (HTTP) - ✔ Connected

官方还提供插件方式：claude plugin install exa@claude-plugins-official，或在 Claude Code 里输入 /plugin 搜索 Exa。插件会顺带装上 Exa 的技能，不用手改 MCP 配置。两种方式选一种即可，不要重复装。

装好后新开一个 Claude Code 会话，用官方文档里的说法试一下：

Find the latest release notes for this dependency and summarize the breaking changes.

中文同样可以，例如「用 Exa 搜一下 Exa 3.0 的官方发布说明，总结三点并给出原文链接」。Claude 会调用 web_search_exa，需要读全文时再调用 web_fetch_exa。

三、接进 Cursor 或 VS Code

Cursor：从 Cursor 插件市场的 Exa 页面安装，或把下面内容写进 ~/.cursor/mcp.json：

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

VS Code：在项目根目录建 .vscode/mcp.json。注意键名是 servers，并且要写 "type": "http"：

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

改完配置后重启客户端，让它重新拉取工具列表。

四、不靠客户端，用 curl 亲手验证

客户端显示「已连接」只代表握手成功。想确认服务器开放了哪些工具、搜索能不能返回结果，可以直接用 MCP 的 JSON-RPC 协议跟它对话。

把下面的内容保存为 exa-mcp-check.sh（macOS / Linux 直接用，Windows 请在 WSL 里运行；需要 curl 和 python3）：

#!/usr/bin/env bash
# 用 curl 和 Exa 托管 MCP 握手：initialize → tools/list → tools/call
set -euo pipefail
URL="${1:-https://mcp.exa.ai/mcp}"
H=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")
# 设置了 EXA_API_KEY 就带上 key（API key 模式），否则走免 key 模式
[ -n "${EXA_API_KEY:-}" ] && H+=(-H "x-api-key: $EXA_API_KEY")
INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
  "protocolVersion":"2025-06-18","capabilities":{},
  "clientInfo":{"name":"kun-demo","version":"0.1"}}}'

# 1) initialize：会话 ID 在响应头 Mcp-Session-Id 里
SID=$(curl -s -D - -o /dev/null -X POST "$URL" "${H[@]}" -d "$INIT" \
  | tr -d '\r' | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}')
echo "session: $SID"
H+=(-H "Mcp-Session-Id: $SID" -H "MCP-Protocol-Version: 2025-06-18")
curl -s -o /dev/null -X POST "$URL" "${H[@]}" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 2) tools/list：服务器开放了哪些工具
curl -s -X POST "$URL" "${H[@]}" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | sed -n 's/^data: //p' \
  | python3 -c 'import json,sys
for t in json.load(sys.stdin)["result"]["tools"]: print("tool:", t["name"])'

# 3) tools/call：用 web_search_exa 搜一次，只打印标题和链接
CALL='{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"web_search_exa",
  "arguments":{"query":"Exa 官方文档：托管 MCP 服务器怎么接入","numResults":3}}}'
curl -s -X POST "$URL" "${H[@]}" -d "$CALL" \
  | sed -n 's/^data: //p' \
  | python3 -c 'import json,sys,re
r = json.load(sys.stdin)["result"]; t = r["content"][0]["text"]
if r.get("isError"): sys.exit("ERROR: " + t.splitlines()[0])
for k, v in re.findall(r"^(Title|URL): (.*)$", t, re.M): print(k + ":", v)'

运行：

chmod +x exa-mcp-check.sh
./exa-mcp-check.sh

对照结果（实测；会话 ID 每次不同，搜索结果会随索引更新变化）：

session: 4ff99000-592c-4d71-bb38-293d42df0dd6
tool: web_search_exa
tool: web_fetch_exa
Title: Exa MCP - Exa
URL: https://exa.ai/docs/get-started/exa-mcp
Title: N/A
URL: https://exa.ai/docs/reference/exa-mcp
Title: exa-labs/exa-mcp-server
URL: https://github.com/exa-labs/exa-mcp-server/

这段输出说明三件事：

• session 非空，initialize 成功
• 免 key 模式下只有 web_search_exa（搜网页）和 web_fetch_exa（读已知网址）两个工具，与官方「默认启用」的说明一致
• 用中文提问也能搜到英文官方文档；工具返回的是带 Title / URL / Highlights 的纯文本，模型可以直接引用

五、用 tools 参数打开高级搜索

web_search_advanced_exa 默认不开放，它支持按域名、发布日期、类别等条件过滤。官方说明：显式写 tools 会替换默认列表，所以要把想用的工具全部写上：

./exa-mcp-check.sh "https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa"

对照结果（实测，前四行）：

session: f9a3b83c-d6cb-44d1-98b9-ceb390dc4343
tool: web_search_exa
tool: web_search_advanced_exa
tool: web_fetch_exa

在 Claude Code 里同理：把这个带参数的地址整个加上双引号，传给 claude mcp add。

六、什么时候需要登录或 API key

• 遇到 429 限速：免费额度用满了，按官方建议改用 OAuth 登录或填自己的 API key
• 想用 agent_run（多步调研、列名单）：它按用量计费，免 key 模式下不会出现

用 API key 时，Claude Code 可以这样加请求头（$EXA_API_KEY 是你自己的环境变量，第 2 课教你创建）：

claude mcp add --transport http exa https://mcp.exa.ai/mcp -H "x-api-key: $EXA_API_KEY"

注意：claude mcp list 只检查能不能连上，不校验 key。我们用假 key 实测，状态照样显示 ✔ Connected，直到真正调用工具才报错。最稳妥的办法是用上面的脚本带 key 跑一遍：

EXA_API_KEY=not-a-real-key ./exa-mcp-check.sh

对照结果（实测，故意用错 key，脚本退出码为 1）：

tool: web_search_exa
tool: web_fetch_exa
tool: agent_run
ERROR: web_search_exa error (401): Invalid API key. Provide a valid key using ...

带上 key 后工具列表多了 agent_run；换成真实 key 再跑，最后一段就会打印搜索结果。

常见问题对照

下一课：创建 API key，用 curl 和 Python / JavaScript SDK 直接调用 Search API。