MCP setup

The Lusha MCP server is hosted at https://mcp.lusha.com. Connect to it in one of two ways:

OAuth

For Claude, ChatGPT, and Codex. You authenticate through the client’s own connector directory - no API key handling required on your side.

API key

For VS Code (GitHub Copilot), Cursor, Gemini CLI, n8n, and any other MCP client. You pass your Lusha API key as an x-api-key header (or via an environment variable, depending on the client).

Starter prompt included. Every new Lusha MCP connection ships with a ready-to-use starter prompt on the client’s consent screen - copy it in one click to run a real first query (find a person, verify they still work there, and pull their title and verified contact details) as soon as you connect. This applies across every MCP client listed below, not just Claude.

Prerequisites

A Lusha API key for the API-key connection method - generate one in the Lusha dashboard under API → Manage API Keys, or go directly to the API keys page
Any plan that includes API access can use the MCP server - it draws from the same credit pool as the REST API

Connect your client

Pick your client below for the exact steps.

Method: OAuth

Go to claude.ai/directory/connectors/lusha
Click Add to Claude
Complete the OAuth authentication flow
Confirm the Lusha tools appear in the tools menu of your conversation

Method: OAuth

Go to chatgpt.com/apps?q=lusha
Click Connect
Complete the OAuth authentication flow
Verify the Lusha tools appear in the tools menu

Method: API key · Requires VS Code 1.99 or higherSettings UI:

Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux)
Run MCP: Add Server
Choose HTTP, enter https://mcp.lusha.com, and name it lusha
Add a header named x-api-key with your Lusha API key

Or edit settings.json directly:

{
  "mcp": {
    "servers": {
      "lusha": {
        "type": "http",
        "url": "https://mcp.lusha.com",
        "headers": {
          "x-api-key": "YOUR_LUSHA_API_KEY"
        }
      }
    }
  }
}

Enable Agent mode in GitHub Copilot Chat, then turn on the Lusha tools from the Tools menu.

Method: API keyEdit ~/.cursor/mcp.json (Mac/Linux) or %APPDATA%\Cursor\mcp.json (Windows):

{
  "mcpServers": {
    "lusha": {
      "url": "https://mcp.lusha.com",
      "headers": {
        "x-api-key": "YOUR_LUSHA_API_KEY"
      }
    }
  }
}

Restart Cursor - the Lusha tools become available automatically.

Method: API keyExtension install (recommended):

gemini extensions install lusha-oss/lusha-gemini-extension
export LUSHA_API_KEY=YOUR_LUSHA_API_KEY

Or configure manually in settings.json, using Streamable HTTP:

{
  "mcpServers": {
    "lusha": {
      "httpUrl": "https://mcp.lusha.com",
      "headers": {
        "Authorization": "Bearer YOUR_LUSHA_API_KEY"
      }
    }
  }
}

Or via stdio, using the npx package:

{
  "mcpServers": {
    "lusha": {
      "command": "npx",
      "args": ["@lusha-org/mcp@latest"],
      "env": {
        "LUSHA_API_KEY": "YOUR_LUSHA_API_KEY"
      }
    }
  }
}

If you installed via the extension, you also get slash commands:

/lusha:prospect - run a prospecting search
/lusha:enrich - enrich a contact or company

Method: API key · Requires n8n 1.88.0 or later

Add an MCP Client Tool node
Set Connection Type to HTTP Streamable
Set URL to https://mcp.lusha.com
Set Authentication to Header Auth, with header x-api-key set to your Lusha API key
Select the Lusha tools you want and connect the node to your AI Agent node

Method: API keyFor any other MCP-compatible client, connect with:

URL: https://mcp.lusha.com
Header: x-api-key: YOUR_LUSHA_API_KEY

Some Lusha MCP tools - the recommendations tools - are only available over an OAuth connection (Claude, ChatGPT, Codex). API-key sessions receive a 403 if they call those tools. See available tools for details.

Troubleshooting

Issue	Resolution
Tools not showing in Claude	Confirm the connector is added and you have permission to use tools. Restart the app.
Tools not showing in ChatGPT	Confirm the connector is connected and enabled in the tools menu. Restart the app.
Tools not showing in Codex	Confirm the Lusha plugin is connected in the plugin directory. Restart the app.
Tools not showing in VS Code	Make sure you’re in Agent mode in Copilot Chat. Verify `mcp.servers` is correctly formatted in `settings.json`.
Tools not showing in Cursor	Verify `mcp.json` is in the correct path and is valid JSON. Restart Cursor fully.
Tools not showing in n8n	Confirm the MCP Client Tool node is connected to your AI Agent node and the workflow is active. Check the URL and header format.
Tools not showing in Gemini CLI	Verify `settings.json` is correctly formatted. Run `/mcp reload` to refresh. Restart Gemini CLI.
Auth errors - wrong header	For custom MCP clients, the header must be `x-api-key` (lowercase). Using `Authorization: Bearer` or any other casing will fail.
Auth errors - expired key	API keys can be revoked or expired. Verify your key is active in the API dashboard and generate a new one if needed.
Partial or no results	Credits follow the same rules as the REST API - failed lookups are not charged. Check your credit balance in the Lusha dashboard or via `account_usage`.
OAuth not completing	If the OAuth flow stalls or errors, try disconnecting and reconnecting the connector from the directory listing. Make sure you are signed in to Lusha before starting the flow.

Security

Store API keys in secure credentials (OS keychain, password manager, or your editor’s secrets manager) - avoid hardcoding them in shared config files.
In n8n, use the built-in Credentials system rather than pasting keys directly into node fields.
Use environment variables for team setups instead of committing keys to version control.
Rotate API keys periodically and remove unused connectors.
Limit tool permissions to the minimum needed for your use case.

Overview

Reference

OAuth

API key

Prerequisites

Connect your client

Troubleshooting

Security

OAuth

API key

​Prerequisites

​Connect your client

​Troubleshooting

​Security

Prerequisites

Connect your client

Troubleshooting

Security