> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP setup
> Connect the Lusha MCP server to Claude, ChatGPT, Codex, VS Code, Cursor, Gemini CLI, n8n, or any other MCP-compatible client.
The Lusha MCP server is hosted at `https://mcp.lusha.com`. Connect to it in one of two ways:
For **Claude**, **ChatGPT**, and **Codex**. You authenticate through the client's own connector directory - no API key handling required on your side.
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](https://dashboard.lusha.com/api/manage-api-keys)
* 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
1. Go to `claude.ai/directory/connectors/lusha`
2. Click **Add to Claude**
3. Complete the OAuth authentication flow
4. Confirm the Lusha tools appear in the tools menu of your conversation
**Method:** OAuth
1. Go to `chatgpt.com/apps?q=lusha`
2. Click **Connect**
3. Complete the OAuth authentication flow
4. Verify the Lusha tools appear in the tools menu
**Method:** OAuth
1. Search for "Lusha" in the plugin directory
2. Click **Connect** and complete the OAuth flow
3. Lusha tools become available automatically in conversations
**Method:** API key · Requires VS Code 1.99 or higher
**Settings UI:**
1. Open the Command Palette (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux)
2. Run **MCP: Add Server**
3. Choose **HTTP**, enter `https://mcp.lusha.com`, and name it `lusha`
4. Add a header named `x-api-key` with your Lusha API key
**Or edit `settings.json` directly:**
```json theme={null}
{
"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 key
Edit `~/.cursor/mcp.json` (Mac/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows):
```json theme={null}
{
"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 key
**Extension install (recommended):**
```bash theme={null}
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:
```json theme={null}
{
"mcpServers": {
"lusha": {
"httpUrl": "https://mcp.lusha.com",
"headers": {
"Authorization": "Bearer YOUR_LUSHA_API_KEY"
}
}
}
}
```
**Or via stdio**, using the npx package:
```json theme={null}
{
"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
1. Add an **MCP Client Tool** node
2. Set **Connection Type** to **HTTP Streamable**
3. Set **URL** to `https://mcp.lusha.com`
4. Set **Authentication** to **Header Auth**, with header `x-api-key` set to your Lusha API key
5. Select the Lusha tools you want and connect the node to your AI Agent node
**Method:** API key
For 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](/mcp/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](https://dashboard.lusha.com/api/manage-api-keys) 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.