# Fix `npm error could not determine executable to run` for exa-mcp-server

## TL;DR
Point your MCP config at the server file with `node` directly instead of `npx`, or switch to the hosted remote server at `https://mcp.exa.ai/mcp`. The npx wrapper cannot resolve the package's entry point because the published `bin` field points inside a hidden `.smithery` directory, which npm refuses to execute.

The exact error:

```text
npm error could not determine executable to run
```

## Steps

### 1. Confirm this is the error
Run the package by hand in a terminal:

```bash
npx -y exa-mcp-server
```

Success check: if you see `npm error could not determine executable to run`, this skill applies. If instead you see a missing API key error, that is a different problem.

### 2. Find where npm installed the package

```bash
npm root -g
```

Success check: it prints a directory. Append `/exa-mcp-server/.smithery/stdio/index.cjs` to it. Verify the file exists:

```bash
ls "$(npm root -g)/exa-mcp-server/.smithery/stdio/index.cjs"
```

### 3. Point the MCP config at node directly
Edit `claude_desktop_config.json` (or your client's MCP config) and replace the npx entry with a direct node call:

```json
{
  "mcpServers": {
    "exa": {
      "command": "node",
      "args": ["[global npm root]/exa-mcp-server/.smithery/stdio/index.cjs"],
      "env": { "EXA_API_KEY": "[your Exa API key]" }
    }
  }
}
```

Success check: save the file, fully restart the client. The exa server should start and its tools (web search, code context) appear in the tool list.

### 4. Alternative: use the hosted remote server instead
If you would rather skip the local install entirely, use the remote endpoint. For Claude Code:

```bash
claude mcp add exa -e EXA_API_KEY [your value] Exa API key] -- npx -y mcp-remote https://mcp.exa.ai/mcp
```

Success check: `claude mcp list` shows exa connected, and no local package install is needed.

## When this applies
- You followed the standard `npx -y exa-mcp-server` setup for Claude Desktop, Cursor, or another MCP client and the server never starts.
- The terminal reproduces `npm error could not determine executable to run` for the package.

## When it does not apply
- You get `EXA_API_KEY environment variable is not set` instead. That is an auth problem: put your key in the `env` block.
- You are using the remote `https://mcp.exa.ai/mcp` URL already. Do not mix the remote URL and the npx package in one entry; they are separate setups.

## Tool compatibility
- exa-mcp-server npm package, versions publishing the `.smithery/stdio/index.cjs` layout
- npx / npm (Node.js 18+)
- Claude Desktop, Claude Code, Cursor, KiloCode

## Why it happens
The published package's `bin` field points at `.smithery/stdio/index.cjs`, a path inside a hidden dot-directory. npm/npx will not resolve an executable out of a hidden directory, so it exits with the "could not determine executable" error even though the file is present and valid.

## Edge cases
- `bunx exa-mcp-server` hits a related startup crash (`SyntaxError` at line 2 of the same file) on some versions; the node-direct workaround avoids that path too.
- If npm installed the package in a user-local prefix (`.npm-global`), the args path must use that prefix, not the system one. `npm root -g` tells you which.
- Some users report success pinning an older package version (e.g. `[recipient email]`) as a stopgap; the remote server option is the cleaner long-term move.