Introduction

When developing agents in DeepSeek Harness (DSH), web search and web scraping are common requirements. MicroHEROX/dsh-exa-mcp is a third-party plugin for DSH. It mounts the Exa remote MCP endpoint https://mcp.exa.ai/mcp via the built-in @deepseek-ai/dsh-mcp-client bridge in the DSH CLI and registers the tools provided by Exa as local agent tools under the exa namespace.

Below is an introduction to what it does, how to install it, how to configure the API key, and the limitations to be aware of.

Plugin Positioning

  • Repository: MicroHEROX/dsh-exa-mcp
  • License: MIT
  • Version: 0.1.0
  • Form: Pure configuration patch layer, no build steps, no extra runtime APIs
  • Install Impact: Adds only one line to the composed cordis.yml after installation
  • Upstream: Connects to Exa-hosted MCP endpoint https://mcp.exa.ai/mcp via Streamable HTTP

Core Capabilities

Tool Registration

The plugin connects to the Exa MCP endpoint via @deepseek-ai/dsh-mcp-client and registers Exa’s provided tools as local tools in the form mcp__exa__*.

Common tools include:

mcp__exa__web_search_exa
mcp__exa__web_fetch_exa
mcp__exa__web_search_advanced_exa
mcp__exa__agent_run

Note that mcp__exa__agent_run requires an Exa API key.

Anonymous and API Key

  • When EXA_API_KEY is not set, the plugin uses Exa’s free quota anonymously, usually with rate limiting and only basic tools available.
  • After setting EXA_API_KEY, the plugin automatically appends x-api-key during loading to unlock advanced search and Exa Agent capabilities.
  • If EXA_API_KEY does not exist, the plugin falls back to anonymous mode and will not send exception headers like undefined.

API keys should only be placed in environment variables; writing them into patch files is prohibited.

Automatic Re-sync

When Exa issues a tools/list_changed notification, the plugin re-syncs the tool list.

Search Task Timeout

The plugin is configured with:

toolCallTimeoutMs: 180000

to support longer search and research tasks.

URL Parameter Configuration

You can use URL parameters to configure tool whitelists or default search types by overriding the url of the mcp-exa line, for example:

?tools=web_search_exa,web_fetch_exa,agent_run
?defaultSearchType=fast

Such configurations take effect after modifying the mcp-exa line in the patch layer. After modification, they can take effect via HMR reconnection without needing to restart the entire dsh process.

Installation and Enabling

Install as a Plugin Bundle

The installation command provided by the repository is:

npm install -g pnpm
dsh plugin --profile web add github:MicroHEROX/dsh-exa-mcp
dsh web

Here, pnpm is used to install git dependencies. Dependencies are handled via the files field during installation; docs/ is not installed to the runtime, and the core file actually installed is cordis.patch.yml.

After installation, you can first check if the bundle layer appears:

dsh --profile web --dump-config | grep -A2 '== dsh-exa-mcp'

If installation via github: is unstable, silent failure may occur, or dsh.profile.bundles may not sync. In this case, check and fix the bundle configuration in the profile according to the README.

Using Patch Override

If you don’t want to install a bundle, you can also temporarily use a patch override:

dsh web --patch /path/to/dsh-exa-mcp/cordis.patch.yml

Note: Do not use bundle installation and --patch override simultaneously, otherwise it will trigger:

duplicate loader entry id: mcp-exa

Choose one of the two activation methods.

Configuring Exa API Key

Anonymous mode can be used for basic search and scraping, but it is rate-limited and tools are restricted. Create an Exa API key and set the environment variable when you need a higher quota or advanced capabilities.

macOS / Linux:

export EXA_API_KEY="your-key"

Windows PowerShell:

$env:EXA_API_KEY = "your-key"

The plugin automatically detects during loading:

  • EXA_API_KEY is set: Sends x-api-key
  • EXA_API_KEY is not set: Falls back to anonymous

Do not write the API key into a patch file. The key should only be stored in environment variables.

Typical Usage

After the installation or patch takes effect, start:

dsh web

Then send a request similar to the agent:

Use Exa to find the latest release notes of the DeepSeek Harness project on GitHub and summarize them.

During execution, you can confirm if the model calls Exa-related tools, for example:

mcp__exa__web_search_exa
mcp__exa__web_fetch_exa

If the task requires advanced search or the Exa Agent, you need to set EXA_API_KEY first.

Suitable Scenarios and Notes

Who is this suitable for

Suitable for developers who want to add Exa search and web scraping capabilities to agents in DSH. Especially for scenarios where you already have a dsh profile and want to quickly connect to a remote MCP endpoint through the configuration layer.

Runtime Permissions

The plugin runs with the permissions of the current dsh process after loading. It is recommended to check the source code, patch content, and the MIT license before installing.

Unsupported Capabilities

  • OAuth login flow is not supported. DSH’s MCP bridge does not have an OAuth flow, so the Exa API key must be used.
  • Only MCP tools are bridged, not Exa’s MCP resources or prompts.
  • Switching authentication methods per request is not supported. The judgment of EXA_API_KEY occurs during configuration loading or HMR reconnection, not during every call.

Common Failure Points

  1. Installation via github: may fail silently due to network instability, or dsh.profile.bundles may not sync.
  2. Using bundle installation and --patch simultaneously will report duplicate loader entry id: mcp-exa.
  3. Accidentally writing the API key into a patch file leads to key leakage risk.
  4. After uninstalling, dsh-exa-mcp may remain abnormally, and you may need to clean up the bundle configuration in the profile.

Uninstall

If installed via the bundle method, use:

dsh plugin --profile <name> remove dsh-exa-mcp

If you previously used --patch, simply remove the --patch parameter from the startup command; no persistent configuration will be left behind.

If dsh-exa-mcp remains abnormally, you can remove the corresponding entry from dsh.profile.bundles in the profile’s package.json.

Links

  • GitHub: https://github.com/MicroHEROX/dsh-exa-mcp