Exa Mcp Rotate

A local stdio MCP server for the Exa Web Search API. It mirrors the common Exa MCP tool names and adds support for multiple Exa API keys through round-robin rotation.

This is useful when you use OpenCode locally and want one MCP server entry that can rotate across several Exa keys instead of configuring multiple Exa MCP servers manually.

Features

• Local stdio MCP server for OpenCode and other MCP clients
• Multiple API keys via EXA_API_KEYS
• Single-key fallback via EXA_API_KEY
• Round-robin key selection per Exa API request
• Tool names compatible with Exa-style MCP usage
• TypeScript source with compiled JavaScript output generated by npm run build

Tools

This server exposes three read-only tools:

Tool	Purpose
web_search_exa	Simple semantic web search with highlights
web_fetch_exa	Fetch clean markdown content from one or more URLs
web_search_advanced_exa	Advanced search with categories, domains, dates, search type, and content modes

Requirements

• Node.js 18 or newer
• npm
• One or more Exa API keys
• OpenCode, or another MCP client that supports local stdio servers

Installation

Clone the repository and build it:

git clone https://github.com/YOUR_USERNAME/exa-mcp-server.git
cd exa-mcp-server
npm install
npm run build

The build creates dist/index.js, which is the file OpenCode should run.

Environment Variables

Use EXA_API_KEYS for multiple keys:

EXA_API_KEYS=exa_key_1,exa_key_2,exa_key_3

Or use EXA_API_KEY for a single key:

EXA_API_KEY=exa_key_1

EXA_API_KEYS takes precedence over EXA_API_KEY when both are set.

When multiple keys are provided, every Exa request uses the next key in sequence. After the last key, the server starts again from the first key.

OpenCode Setup

Build the project first:

npm install
npm run build

Then add a local MCP entry to your OpenCode config.

Use an absolute path for dist/index.js:

{
  "mcp": {
    "exa": {
      "type": "local",
      "command": ["node", "/absolute/path/to/exa-mcp-server/dist/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "EXA_API_KEYS": "exa_key_1,exa_key_2,exa_key_3"
      }
    }
  }
}

For a single key:

{
  "mcp": {
    "exa": {
      "type": "local",
      "command": ["node", "/absolute/path/to/exa-mcp-server/dist/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "EXA_API_KEY": "exa_key_1"
      }
    }
  }
}

Restart OpenCode after changing the config.

Example OpenCode Prompt

After the MCP server is enabled, you can ask OpenCode things like:

Search the web for recent MCP server best practices using Exa.

or:

Fetch the full content of https://example.com and summarize it.

Local Development

Install dependencies:

npm install

Run in watch mode:

npm run dev

Build:

npm run build

Run the compiled server directly:

EXA_API_KEYS=exa_key_1,exa_key_2 node dist/index.js

Because this is a stdio MCP server, direct terminal execution will wait for MCP protocol input. For normal use, run it through OpenCode or another MCP client.

Repository Contents

Commit these files:

src/
package.json
package-lock.json
tsconfig.json
README.md
.gitignore
.env.example
LICENSE

Do not commit these files or folders:

node_modules/
dist/
.env

Security Notes

• Never commit real Exa API keys.
• Keep keys in your OpenCode MCP environment config or another local secret source.
• If you accidentally commit a key, revoke it from Exa and create a new one.

How Key Rotation Works

At startup, the server loads keys from EXA_API_KEYS or EXA_API_KEY.

Each request calls the key pool once and receives the next key:

request 1 -> key 1
request 2 -> key 2
request 3 -> key 3
request 4 -> key 1

This does not retry a failed request with another key. It simply rotates the key used for each new request.

License

MIT