前言¶
在 DeepSeek Harness（DSH）中做智能体开发时，联网搜索和网页抓取是常见需求。MicroHEROX/dsh-exa-mcp 是一个面向 DSH 的第三方插件，它通过 DSH CLI 自带的 @deepseek-ai/dsh-mcp-client 桥接器，把 Exa 的远程 MCP endpoint https://mcp.exa.ai/mcp 挂载进来，并将 Exa 提供的工具注册为 exa 命名空间下的本地 agent 工具。
下面介绍它做了什么、如何安装、如何配置 API key，以及需要注意的限制。
插件定位¶
- 仓库：
MicroHEROX/dsh-exa-mcp - 许可证：MIT
- 版本：
0.1.0 - 形态：纯配置补丁层，无构建步骤，不引入额外的运行时 API
- 安装影响：安装后仅向 composed
cordis.yml添加一行 - 上游：连接 Exa 托管的 MCP endpoint
https://mcp.exa.ai/mcp，传输方式为 Streamable HTTP
核心能力¶
工具注册¶
插件通过 @deepseek-ai/dsh-mcp-client 连接 Exa MCP endpoint，并把 Exa 提供的工具注册为 mcp__exa__* 形式的本地工具。
常见工具包括：
mcp__exa__web_search_exa
mcp__exa__web_fetch_exa
mcp__exa__web_search_advanced_exa
mcp__exa__agent_run
其中 mcp__exa__agent_run 需要 Exa API key。
匿名与 API key¶
- 未设置
EXA_API_KEY时，插件以匿名方式使用 Exa 免费额度，通常是限流且仅提供基础工具。 - 设置
EXA_API_KEY后，插件会在加载时自动附加x-api-key，用于解锁高级搜索和 Exa Agent 等能力。 - 如果
EXA_API_KEY不存在，插件会回退到匿名模式，不会发送undefined这类异常 header。
API key 只应放在环境变量中，禁止写入 patch 文件。
自动重同步¶
当 Exa 侧发出 tools/list_changed 通知后，插件会重新同步工具列表。
搜索任务超时¶
插件会配置：
toolCallTimeoutMs: 180000
用于支持较长的搜索和研究任务。
URL 参数配置¶
可以通过覆盖 mcp-exa 行的 url，使用 URL 参数配置工具白名单或默认搜索类型，例如：
?tools=web_search_exa,web_fetch_exa,agent_run
?defaultSearchType=fast
这类配置适合在 patch 层中修改 mcp-exa 行后生效，修改后可通过 HMR 重连，而不需要重启整个 dsh 进程。
安装与启用¶
作为插件 bundle 安装¶
仓库提供的安装命令如下：
npm install -g pnpm
dsh plugin --profile web add github:MicroHEROX/dsh-exa-mcp
dsh web
这里的 pnpm 用于安装 git 依赖。安装时通过 files 字段处理依赖，docs/ 不会安装到运行时，实际安装的核心文件是 cordis.patch.yml。
安装后可以先检查 bundle 层是否出现：
dsh --profile web --dump-config | grep -A2 '== dsh-exa-mcp'
如果通过 github: 安装时网络不稳定，可能出现静默失败，或 dsh.profile.bundles 未同步的情况。此时需要按 README 检查并修复 profile 中的 bundle 配置。
使用 patch 覆盖¶
如果不想安装 bundle，也可以临时使用 patch 覆盖：
dsh web --patch /path/to/dsh-exa-mcp/cordis.patch.yml
注意：bundle 安装和 --patch 覆盖不要同时使用，否则会触发：
duplicate loader entry id: mcp-exa
两种启用方式选择其中一种即可。
配置 Exa API key¶
匿名方式可以用于基础搜索和抓取，但限流且工具受限。需要更高限额或高级能力时，创建 Exa API key，并设置环境变量。
macOS / Linux：
export EXA_API_KEY="your-key"
Windows PowerShell：
$env:EXA_API_KEY = "your-key"
插件在加载时会自动检测：
EXA_API_KEY已设置：发送x-api-keyEXA_API_KEY未设置：匿名回退
不要把 API key 写入 patch 文件。key 应只保存在环境变量中。
典型用法¶
安装或 patch 生效后，启动：
dsh web
然后向 agent 发送类似请求：
Use Exa to find the latest release notes of the DeepSeek Harness project on GitHub and summarize them.
执行时，可以确认模型是否调用了 Exa 相关工具，例如：
mcp__exa__web_search_exa
mcp__exa__web_fetch_exa
如果任务需要高级搜索或 Exa Agent，需要先设置 EXA_API_KEY。
适用场景与注意¶
适合谁使用¶
适合在 DSH 中希望给 agent 增加 Exa 搜索和网页抓取能力的开发者。尤其是已有 dsh profile、想通过配置层快速接入远程 MCP endpoint 的场景。
运行权限¶
插件加载后会以当前 dsh 进程权限运行。安装前建议先检查源码、配置补丁内容和 MIT 许可证。
不支持的能力¶
- 不支持 OAuth 登录流。DSH 的 MCP bridge 没有 OAuth 流程，需要使用 Exa API key。
- 只桥接 MCP tools，不桥接 Exa 的 MCP resources 或 prompts。
- 不支持每次请求切换认证方式。
EXA_API_KEY的判断发生在配置加载或 HMR 重连阶段，而不是每次调用阶段。
常见失败点¶
github:安装可能因网络不稳定而静默失败，或dsh.profile.bundles未同步。- bundle 安装和
--patch同时使用会报duplicate loader entry id: mcp-exa。 - API key 误写入 patch 文件，会导致 key 泄露风险。
- 卸载后异常残留
dsh-exa-mcp，可能需要清理 profile 的 bundle 配置。
卸载¶
如果通过 bundle 方式安装，使用：
dsh plugin --profile <name> remove dsh-exa-mcp
如果之前使用 --patch，只需移除启动命令中的 --patch 参数，不会留下持久化配置。
如果异常残留 dsh-exa-mcp，可以从 profile package.json 的 dsh.profile.bundles 中移除对应条目。
链接¶
- GitHub：https://github.com/MicroHEROX/dsh-exa-mcp
