How to set up the Exa MCP server in Claude Code, Cursor, VS Code and Codex

Quick answer

• Server URL: https://mcp.exa.ai/mcp. It works without an API key at a free rate limit, for search and fetch.
• Claude Code: claude plugin install exa@claude-plugins-official. Codex: codex mcp add exa --url https://mcp.exa.ai/mcp, or the Exa plugin in OpenAI's plugin directory.
• Higher limits and Exa Agent: sign in with OAuth by connecting to https://mcp.exa.ai/mcp?login, or send an API key in an x-api-key header.
• Default tools: web_search_exa and web_fetch_exa. Add others with a tools parameter on the URL, which replaces the defaults.

What the Exa MCP server gives you

• web_search_exa (on by default): search the web and get back clean, ready-to-use content from the results.
• web_fetch_exa (on by default): read the full content of one or more known URLs as clean markdown.
• web_search_advanced_exa (opt-in): search with filters such as domains, date ranges, categories, highlights, summaries and subpage crawling. It doesn't need authentication.
• agent_run (needs OAuth or an API key): run Exa Agent for research that takes more than one search, such as building a list and checking each item, with optional structured JSON output. Once you are authenticated, Exa's docs say it is on by default.

For a shorter overview, see the Exa MCP Server listing.

Keyless, OAuth or API key?

• Keyless: connect to https://mcp.exa.ai/mcp with nothing else. Good for trying search and fetch. agent_run isn't available, and keyless access only works over a direct IPv4 connection.
• OAuth: connect to https://mcp.exa.ai/mcp?login (or https://mcp.exa.ai/mcp/oauth) and sign in to Exa in the browser when your client asks. Usage then counts against your Exa team. Exa's docs list this for interactive clients and production use.
• API key: create a key in the Exa dashboard (dashboard.exa.ai/api-keys) and send it as an x-api-key header, or as Authorization: Bearer <key>. Use this for clients without MCP OAuth. Keep the key out of files you commit.

The README also allows the key on the URL as ?exaApiKey=.... A header is the better choice, because URLs end up in logs and config files that are easy to share by accident. New Exa accounts start with free credits; check Exa's pricing page for current rates.

Claude Code

The official plugin installs the MCP server together with Exa's search and exa-agent skills:

claude plugin install exa@claude-plugins-official

You can also type /plugin in Claude Code and search for Exa. Start a new session afterwards. To add only the MCP server by hand:

# keyless
claude mcp add --transport http exa https://mcp.exa.ai/mcp

# sign in with OAuth (then run /mcp in Claude Code and choose Authenticate)
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?login"

# API key
claude mcp add --transport http exa https://mcp.exa.ai/mcp --header "x-api-key: YOUR_EXA_API_KEY"

Pick one of these, not all three: a second claude mcp add with the same name at the same scope fails because the server already exists. Quote URLs that contain ?, so your shell doesn't try to expand them. Use the plugin or a manual entry, not both. If Claude Code says the server needs authentication, see fix Claude Code MCP "needs authentication".

Claude Desktop and Claude.ai

Use Exa's official connector instead of a config file: select + in a new chat, choose Add connector, search for Exa and connect it.

Codex

Exa is in OpenAI's plugin directory (the same directory for ChatGPT and Codex), and the plugin includes the MCP server plus Exa's skills. To add only the server:

codex mcp add exa --url https://mcp.exa.ai/mcp

If you use the ?login URL instead, run codex mcp login exa to start the sign-in.

To use an API key without writing it into the file, read the header from an environment variable in ~/.codex/config.toml:

[mcp_servers.exa]
url = "https://mcp.exa.ai/mcp"
env_http_headers = { "x-api-key" = "EXA_API_KEY" }

More on Codex config: how to add an MCP server to Codex.

Cursor

Install Exa from the Cursor Marketplace, or add it to ~/.cursor/mcp.json and restart Cursor:

{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

To send an API key, add a headers object and read the key from an environment variable, so the file holds no secret:

{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp",
      "headers": {
        "x-api-key": "${env:EXA_API_KEY}"
      }
    }
  }
}

Details on ${env:...} and file locations: how to add an MCP server to Cursor.

VS Code

Use the one-click install link in Exa's docs, or add this to .vscode/mcp.json in your project (Exa's example):

{
  "servers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

For higher limits, switch the URL to https://mcp.exa.ai/mcp?login and complete the sign-in when VS Code prompts you. VS Code's config formats are changing; see how to add an MCP server to VS Code for which file uses servers and which uses mcpServers.

Other clients

Most clients take the standard block with a url. Exa's docs list the key name each one expects: Windsurf uses serverUrl in ~/.codeium/windsurf/mcp_config.json, Gemini CLI uses httpUrl in ~/.gemini/settings.json, OpenCode uses opencode.json under mcp with "type": "remote", and Zed uses context_servers in its settings.json. For a client that only runs local servers, use the mcp-remote bridge:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"]
    }
  }
}

Choose which tools load

Add a tools parameter to the URL. An explicit list replaces the defaults, so include search and fetch if you still want them:

# add advanced search
https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa

# everything (agent_run still needs OAuth or an API key)
https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa,web_search_advanced_exa,agent_run

For ordinary searches, Exa's docs suggest keeping web_search_exa, because it gives the model a smaller tool surface. Restart your client after changing the URL so it fetches the tool list again.

Run Exa MCP locally

The hosted server is the simpler option. To run the open-source npm package on your machine instead, you need an Exa API key and Node.js (the package declares Node 20 or later):

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

On Windows, if the client can't start npx, see fixing spawn npx ENOENT.

Check that it works

Open your client's MCP list and confirm exa is connected with web_search_exa and web_fetch_exa. Then try:

Search the web for this week's Next.js release notes and summarize the main changes, with links.

The assistant should call web_search_exa. If it answers from its own knowledge instead, mention Exa in the prompt ("use Exa to search...").

Troubleshooting

• Rate limit error (429): the connection is on Exa's free keyless limits. Sign in with OAuth or add an API key, then reconnect.
• Forbidden (403) without an API key: keyless access needs a direct IPv4 connection to https://mcp.exa.ai/mcp. From IPv6 or through a proxy, sign in with OAuth or add an API key.
• `agent_run` is missing or asks for authentication: it can't use the free limits, so it only appears once you connect with ?login or an API key. If you set a tools list, include agent_run in it.
• Tools not appearing: a tools parameter replaces the default list. Check that every tool you want is in the URL, then restart the client.
• The OAuth sign-in doesn't open: confirm the client supports MCP OAuth and that the URL ends in ?login. Restart the client after changing the URL. If the client can't do MCP OAuth, use an API key.
• Claude Desktop won't connect with a config entry: use the built-in Exa connector instead.

FAQ

Is Exa MCP free?

You can try search and fetch without an account, at a free rate limit. Signing in or using an API key moves usage to your Exa team's plan; new accounts start with free credits. Exa Agent runs are usage-based. See Exa's pricing page for current rates.

Do I need an API key?

Not to try it. You need OAuth or a key for higher limits and for agent_run. OAuth avoids storing a key at all.

Should I use the hosted server or the npm package?

The hosted server: there's nothing to install, and it supports keyless use and OAuth. Use the npm package only if your setup needs a local process, and give it your API key through EXA_API_KEY.

Exa or another search MCP server?

For other options on PluginStack, see the Brave Search MCP server and how to set up the Firecrawl MCP server, which also turns pages into clean markdown.