前言¶
在 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
