[Bug]: EXA_API_KEY environment variable is not applied to Exa MCP URL, causing rate limit errors

[imbytecat]

Prerequisites

• I will write this issue in English (see our Language Policy)
• I have searched existing issues to avoid duplicates
• I am using the latest version of oh-my-opencode
• I have read the documentation or asked an AI coding agent with this project's GitHub URL loaded and couldn't find the answer

Bug Description

I have configured the EXA_API_KEY in my environment variables, but oh-my-opencode seems to ignore it when establishing the connection to the Exa MCP server.

As a result, I am receiving a "free MCP rate limit" error from Exa. According to the error message and the Exa documentation, the API key must be passed via the exaApiKey query parameter in the URL (e.g., ?exaApiKey=YOUR_EXA_API_KEY), but the current implementation in src/mcp/websearch.ts does not seem to append this parameter automatically when the environment variable is present.

Steps to Reproduce

1. Export a valid Exa API Key in the environment: export EXA_API_KEY=your_key_here.
2. Run opencode.
3. Perform a web search action that triggers the Exa MCP.
4. (After sufficient usage) Observe that the request fails with a rate limit error, indicating the key was not used.

Expected Behavior

When EXA_API_KEY is present in the environment, the application should automatically append ?exaApiKey=${process.env.EXA_API_KEY} to the Exa MCP server URL so that the request is authenticated and uses the user's quota.

Actual Behavior

The application connects to the default Exa MCP URL without the API key, resulting in the following error:

Error: Streamable HTTP error: Error POSTing to endpoint: {
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "You've hit Exa's free MCP rate limit. To continue using without limits, create your own Exa API key.\n\nFix: Create API key at https://dashboard.exa.ai/api-keys , and then update Exa MCP URL to this https://mcp.exa.ai/mcp?exaApiKey=YOUR_EXA_API_KEY"
  },
  "id": null
}

Doctor Output

$ bunx oh-my-opencode doctor

 oMoMoMoMo... Doctor


Installation
────────────────────────────────────────
  ✓ OpenCode Installation → 1.1.53
  ✓ Plugin Registration → Registered (pinned: latest)

Configuration
────────────────────────────────────────
  ✓ Configuration Validity → Valid JSONC config
  ✓ Model Resolution → 10 agents, 8 categories (18 overrides), 2449 available

Authentication
────────────────────────────────────────
  ✓ Anthropic (Claude) Auth → Auth plugin available
  ○ OpenAI (ChatGPT) Auth → Auth plugin not installed
  ○ Google (Gemini) Auth → Auth plugin not installed

Dependencies
────────────────────────────────────────
  ✓ AST-Grep CLI → installed
  ✓ AST-Grep NAPI → installed
  ⚠ Comment Checker → Not installed (optional)

Tools & Servers
────────────────────────────────────────
  ✓ GitHub CLI → 2.86.0 - authenticated as imbytecat
  ⚠ LSP Servers → No LSP servers detected
  ✓ Built-in MCP Servers → 2 built-in servers enabled
  ○ User MCP Configuration → No user MCP configuration found
  ○ MCP OAuth Tokens → No OAuth tokens configured

Updates
────────────────────────────────────────
  ⚠ Version Status → Update available: 3.2.3 -> 3.3.0

Summary
────────────────────────────────────────

  9 passed, 0 failed, 3 warnings, 4 skipped
  Total: 16 checks in 2355ms

⚠ All systems operational with warnings.

Error Logs

Configuration

Additional Context

• Relevant Code: src/mcp/websearch.ts
• Reference: Exa MCP API Key Documentation

Operating System

Linux

OpenCode Version

1.1.53

[code-yeongyu]

Triage: NEEDS_MORE_INFO — Possible Exa MCP auth incompatibility

Looking at src/mcp/websearch.ts:32-38, when EXA_API_KEY is set, oh-my-opencode passes it via the x-api-key HTTP header:

headers: process.env.EXA_API_KEY
  ? { "x-api-key": process.env.EXA_API_KEY }
  : undefined,

The Exa error message suggests using ?exaApiKey=YOUR_KEY as a URL query parameter instead. There may be an incompatibility: Exa's MCP server might only accept the API key via the query parameter, not via the x-api-key header.

Questions to resolve:

1. Does Exa's MCP endpoint at mcp.exa.ai/mcp accept the x-api-key header for authentication?
2. Or does it only support the ?exaApiKey= query parameter?

If Exa's MCP only supports query param auth, the fix would be:

url: `https://mcp.exa.ai/mcp?tools=web_search_exa${process.env.EXA_API_KEY ? `&exaApiKey=${process.env.EXA_API_KEY}` : ''}`,

@imbytecat — Could you confirm whether you're hitting the rate limit error even with EXA_API_KEY set? The current code does attempt to pass the key, just via a different mechanism (header vs query param).

[code-yeongyu]

Resolved ✅

This issue has been fixed by PR #1643 (merged as commit 2588f330).

What was fixed:
The EXA_API_KEY environment variable is now properly URL-encoded and appended as a query parameter (exaApiKey) to the Exa MCP URL.

Code evidence (src/mcp/websearch.ts):

url: process.env.EXA_API_KEY
  ? `https://mcp.exa.ai/mcp?tools=web_search_exa&exaApiKey=${encodeURIComponent(process.env.EXA_API_KEY)}`
  : "https://mcp.exa.ai/mcp?tools=web_search_exa",

The fix includes proper URL encoding for API keys containing special characters, and regression tests confirm the behavior.

Available since: v3.3.2+

Closing as resolved. If you still experience this issue on the latest version, please reopen.

[code-yeongyu]

[sisyphus-bot] Triage assessment:

Status: CLOSED (2026-02-08)

Type: Bug (MCP integration)

Assessment: environment variable was not being appended to Exa MCP URL, causing rate limit errors. Fix implemented to pass API key via query parameter.

Action: Issue properly closed with fix implemented.

[TickToTick]

Issue still persist for it is not fixed...