Skip to main content

Set up the lemlist MCP server in your LLM client (OAuth or API key)

Connect the lemlist MCP server to Claude, Claude Code, Cursor, ChatGPT, or Codex using OAuth (recommended) or an API key, and verify the connection works.

The lemlist MCP server lets AI clients (like Claude, Claude Code, Cursor, ChatGPT, or Codex) securely interact with your lemlist workspace through MCP (JSON-RPC over HTTP). You can authenticate either with OAuth (recommended, no API key) or with an API key, depending on your environment and security preferences.

Learning Objective

By the end of this tutorial, you'll know how to connect the lemlist MCP server to Claude, Claude Code, Cursor, ChatGPT, or Codex using either OAuth (recommended when available) or an API key, and verify that the connection works.

Why This Matters

Once the lemlist MCP server is connected, your AI client can help you audit campaigns, create or update sequences, and manage leads—without switching between tools. OAuth reduces secret management overhead, while API keys provide a straightforward option for environments that don't support OAuth flows.

Prerequisites

  • You have a lemlist account and access to the team/workspace you want to connect.

  • You have one of the supported clients: Claude (web, desktop, or Cowork), Claude Code, Cursor, ChatGPT web, or the ChatGPT desktop app / Codex.

  • On a Team or Enterprise plan in Claude, or on ChatGPT web, an admin may need to approve the connector before you can use it. See the per-client steps below.

  • If using API key auth, you can generate an API key in lemlist.

Phase 1: Pick your connection method

Most clients now support remote MCP servers natively, so OAuth is the fastest path in almost every case. Find your client below.

Client

Recommended method

Where you set it up

Claude (web, desktop, Cowork)

OAuth

In-app: Customize > Connectors

Claude Code

OAuth

Terminal: claude mcp add

Cursor

OAuth (API key also works)

~/.cursor/mcp.json

ChatGPT web

OAuth

In-app: Settings > Apps (developer mode)

ChatGPT desktop app, Codex CLI, Codex IDE extension

OAuth (API key also works)

~/.codex/config.toml

Important: ChatGPT has two separate MCP surfaces. ChatGPT web adds custom MCP servers as apps in developer mode. The ChatGPT desktop app shares its MCP configuration with Codex CLI and the Codex IDE extension—you configure it once in ~/.codex/config.toml and all three see the same servers. The two paths are not interchangeable: instructions for one will not work on the other.

Option A (Recommended): OAuth (no API key needed)

With OAuth, you don't need to create or store an API key. Your LLM client completes authentication through your browser, including consent, token exchange (PKCE), and token refresh.

  • First use behavior: the first time you connect (or call a lemlist tool), your browser opens a consent page where you select your team and authorize access.

  • Token handling: managed automatically (access token ~1 hour, refresh token ~30 days).

Option B: API key

If your environment requires it, you can authenticate using an API key via an HTTP header (X-API-Key). Use this when your client can't complete an OAuth flow, or when you need a fixed credential for a shared/automated setup.

Phase 2: Set up lemlist MCP with OAuth

In every case, the MCP server URL you'll enter is:

https://app.lemlist.com/mcp

Claude (web, desktop, and Cowork)

Claude supports remote MCP servers natively. You do not need Node.js, npx, mcp-remote, or any config file.

If you're on Free, Pro, or Max:

  1. Go to Customize > Connectors.

  2. Click +, then Add custom connector.

  3. Enter the remote MCP server URL: https://app.lemlist.com/mcp

  4. Click Add. Leave the Advanced settings (OAuth client ID/secret) empty—lemlist registers your client automatically.

  5. Click Connect and complete the browser consent flow: select your lemlist team/workspace and approve access.

If you're on Team or Enterprise:

  1. An Owner goes to Organization settings > Connectors, clicks Add, hovers Custom, and selects Web.

  2. The Owner enters https://app.lemlist.com/mcp and clicks Add.

  3. Each member then goes to Customize > Connectors, finds lemlist in the list, and clicks Connect to authenticate with their own lemlist account.

Note: On the Free plan you can add only one custom connector. On Team and Enterprise, only Owners can add custom connectors—members can connect to them but not create them.

Claude Code (OAuth)

  1. Run the following command:

    claude mcp add --transport http lemlist https://app.lemlist.com/mcp

    No --header flag is needed—OAuth handles authentication automatically.

  2. Start Claude Code and run /mcp.

  3. Select lemlist, then Authenticate. Your browser opens the consent page—select your team and authorize.

Choosing a scope. By default the server is added for the current project only. Add --scope to change that:

Flag

Effect

--scope local (default)

This project only, private to you.

--scope user

All your projects, private to you.

--scope project

Shared with your team via .mcp.json in the repo. Each teammate still authenticates individually.

Cursor (OAuth)

  1. Open ~/.cursor/mcp.json (applies to all projects) or .cursor/mcp.json in your project root (applies to that project only). Create the file if it doesn't exist.

  2. Add a lemlist block:

    {"mcpServers": {"lemlist": {"url": "https://app.lemlist.com/mcp"}}}

  3. Save the file. Cursor detects the server and prompts you to sign in—complete the browser consent flow.

  4. You can enable or disable the server anytime from Customize in Cursor.

Note: If your team is on Cursor's enterprise plan, an admin may need to allowlist the server under Team Settings > MCP Configuration first.

ChatGPT web (Apps in developer mode)

On ChatGPT web, custom MCP servers are added as apps in developer mode—not through the older Connectors screen.

  1. Confirm developer mode is enabled for your account.

  2. Go to Settings > Apps > Create. (Workspace admins use Workspace settings > Apps > Create.)

  3. Give the app a name and set the MCP server endpoint to https://app.lemlist.com/mcp.

  4. Choose OAuth as the authentication method and authorize access from your lemlist account. Nothing to copy or store—you can revoke access anytime.

  5. Click Scan tools, wait for the scan to finish, then click Create.

  6. To verify, ask ChatGPT something read-only, for example: "List my lemlist campaigns." If it returns your campaigns, you're connected.

Plan and platform limits: Apps, full MCP support, and developer mode are available to ChatGPT Business and Enterprise/Edu customers on ChatGPT web only—not in the desktop apps and not on mobile. Pro users can build apps with the Apps SDK, but full MCP is currently Business and Enterprise/Edu only. If you're on Plus or Pro and want to use the lemlist MCP, use the ChatGPT desktop app / Codex route below instead.

Note: ChatGPT will ask for your confirmation before running any action that sends messages, spends credits, or changes campaigns.

ChatGPT desktop app, Codex CLI, and Codex IDE extension

These three share a single MCP configuration through the Codex host, so you only need to set it up once.

Option 1: register it from the terminal (simplest).

  1. Add the server:

    codex mcp add lemlist --url https://app.lemlist.com/mcp

  2. Authenticate:

    codex mcp login lemlist

  3. Select your lemlist team/workspace in the browser and approve access.

Option 2: edit the config file. Open ~/.codex/config.toml (applies everywhere), or .codex/config.toml in a trusted project (applies to that project only), and add:

[mcp_servers.lemlist]
url = "https://app.lemlist.com/mcp"
auth = "oauth"

Then run codex mcp login lemlist to authenticate.

Option 3: use the ChatGPT desktop app UI.

  1. Open Settings > MCP servers.

  2. Click Add server and enter https://app.lemlist.com/mcp.

  3. Complete the browser consent flow.

Tip: If lemlist tools are slow to appear, add startup_timeout_sec = 20 and tool_timeout_sec = 60 to the server block.

Phase 3: Set up lemlist MCP with an API key

Use this path only if OAuth isn't available in your environment.

Step 1: Generate your lemlist API key

  1. Log in to lemlist: https://app.lemlist.com

  2. Go to Settings → Team → Integrations.

  3. Click Generate to create an API key.

  4. Store the key somewhere safe (for example, a vault/password manager). You may not be able to view it again.

Claude Code (API key)

  1. Run the following command (replace the API key value):

    claude mcp add --transport http lemlist https://app.lemlist.com/mcp --header "X-API-Key: PUTYOURAPIKEY"

Cursor (API key)

  1. Open ~/.cursor/mcp.json or .cursor/mcp.json.

  2. Add a lemlist block like the example below (replace the API key):

    {"mcpServers": {"lemlist": {"url": "https://app.lemlist.com/mcp","headers": {"X-API-Key": "... YOUR API KEY ..."}}}}

ChatGPT desktop app / Codex (API key)

In ~/.codex/config.toml, pass the key as a static header:

[mcp_servers.lemlist]
url = "https://app.lemlist.com/mcp"
http_headers = { "X-API-Key" = "... YOUR API KEY ..." }

To keep the key out of the file, read it from an environment variable instead. Note that env_http_headers takes the name of the variable, not the key itself:

[mcp_servers.lemlist]
url = "https://app.lemlist.com/mcp"
env_http_headers = { "X-API-Key" = "LEMLIST_API_KEY" }

Claude Desktop via mcp-remote (legacy)

Most people should skip this section. Claude now connects to remote MCP servers natively (see Phase 2), which needs no Node.js and no config file. Only use the setup below if you specifically need the server to run locally on your machine.

This approach runs the MCP bridge locally via npx and passes the API key through an environment variable. It requires Node.js installed so that npx works.

  1. Open Claude Desktop settings and navigate to Developer → Edit Config.

  2. In claude_desktop_config.json, add a lemlist MCP server block (replace the API key):

    {"mcpServers": {"lemlist": {"command": "npx","args": ["mcp-remote","https://app.lemlist.com/mcp","--header","X-API-Key: ${API_KEY}"],"env": {"API_KEY": "... YOUR API KEY ..."}}}}

    On Windows, if npx isn't found, point directly to npx.cmd:

    {"lemlist": {"command": "C:\\PROGRA~1\\nodejs\\npx.cmd","args": ["mcp-remote","https://app.lemlist.com/mcp","--header","X-API-Key: ${API_KEY}"],"env": {"API_KEY": "... YOUR API KEY ..."}}}

  3. Restart Claude Desktop. The lemlist MCP server should now appear in settings.

Phase 4: Verify your setup

  1. Open your AI client and start a new chat.

  2. Ask the assistant what lemlist tools are available (tool availability may change over time).

  3. Run a simple "read-only" action first (for example, listing campaigns) before attempting changes.

Tip: If you're using OAuth, connecting (or your first tool call) should trigger a browser consent screen. If you don't see it, jump to the troubleshooting section below.

Practical Application: Create a specialized "lemlist agent" in Claude Code

If you use Claude Code, you can create a custom skill that "loads" a lemlist-focused agent prompt. This is helpful if you frequently use lemlist for campaign audits, lead sourcing, and sequence optimization.

  1. Create a file at .claude/skills/lemlist-agent/SKILL.md.

  2. Add frontmatter with a name and description, then paste your agent instructions below it.

  3. In Claude Code, type /lemlist-agent to activate it—or just describe a lemlist task and Claude will load the skill on its own.

Tip: The older format—a single file at .claude/commands/lemlist-agent.md—still works and produces the same /lemlist-agent command. Skills are preferred because they can hold supporting files (templates, checklists) and can be triggered automatically.

Common agent workflows to include:

  • Campaign audit: list campaigns → pull stats (30/90 days) → identify bottlenecks → propose fixes.

  • New campaign creation: define ICP → draft a 3–4 email sequence → configure timing → guide lead import.

  • Lead sourcing: define ICP filters → search lemleads → validate sample results → enrich cautiously → dedupe and import.

Troubleshooting & Pitfalls

Issue: The lemlist MCP recently stopped working in ChatGPT

  • Root cause: You almost certainly set it up on a surface that has changed. Custom MCP servers on ChatGPT web moved from the old Settings > Connectors screen to apps in developer mode, and full MCP there is now limited to Business and Enterprise/Edu. Separately, the ChatGPT desktop app does not use the web Apps flow at all—it reads Codex's configuration.

  • Fix:

    • Decide which surface you actually use, then follow the matching section in Phase 2. A connector added on the web will not appear in the desktop app, and vice versa.

    • If you're on Plus or Pro, full MCP isn't available on ChatGPT web. Use the ChatGPT desktop app / Codex route instead—there's no plan gate there.

    • If you're on Business, Enterprise, or Edu, re-create lemlist under Settings > Apps > Create with developer mode enabled.

Issue: lemlist appears in Codex but shows no tools

  • Root cause: Authentication didn't complete, the server timed out during startup, or you're on an older Codex build with incomplete streamable-HTTP support.

  • Fix:

    • Run codex mcp login lemlist and confirm the browser flow finishes.

    • Update Codex to the latest version—remote streamable-HTTP handling has been fixed several times.

    • Raise startup_timeout_sec and tool_timeout_sec in the server block.

    • Confirm you edited the right file: ~/.codex/config.toml for global, or .codex/config.toml inside a trusted project.

Issue: The OAuth consent page doesn't open

  • Root cause: The connection didn't trigger an OAuth flow, pop-ups are blocked, or the MCP server URL is wrong.

  • Fix:

    • Claude: go to Customize > Connectors and click Connect next to lemlist.

    • Claude Code: run /mcp, select lemlist, then choose Authenticate.

    • Cursor: save mcp.json again, or toggle the server off and back on from Customize.

    • ChatGPT web: re-open the app under Settings > Apps and re-run authorization.

    • ChatGPT desktop / Codex: run codex mcp login lemlist to start the flow manually.

    • Temporarily allow pop-ups for your AI client/browser.

    • Re-check the MCP endpoint: https://app.lemlist.com/mcp.

Issue: You can't add the connector at all

  • Root cause: A plan limit or an admin restriction is blocking you.

  • Fix:

    • Claude Free: you're limited to one custom connector—remove an existing one first.

    • Claude Team/Enterprise: ask an Owner to add lemlist under Organization settings > Connectors, then connect from Customize > Connectors.

    • Cursor enterprise: ask an admin to allowlist the server under Team Settings > MCP Configuration.

    • ChatGPT web: confirm developer mode is on, that you're on Business/Enterprise/Edu, and that your workspace admin allows custom apps.

Issue: It worked before, but now lemlist tools fail or ask you to reconnect

  • Root cause: Your refresh token expired (~30 days of inactivity), access was revoked, or you were removed from the lemlist team you originally authorized.

  • Fix:

    • Re-authorize rather than re-adding the server. In Claude, click Connect again under Customize > Connectors. In Claude Code, run /mcp and choose Authenticate. In Codex, run codex mcp login lemlist.

    • If you belong to several lemlist teams, check you selected the right one on the consent page.

Issue: Authentication fails with an API key

  • Root cause: Missing/incorrect X-API-Key header or the key is expired/revoked.

  • Fix:

    • Confirm the header name is exactly X-API-Key (case and punctuation matter).

    • Regenerate the API key in lemlist if needed and update your config.

    • In Codex, remember http_headers takes the key itself while env_http_headers takes the name of an environment variable—mixing them up is a common mistake.

    • If you're using the legacy mcp-remote setup, confirm your env variable name matches (API_KEY).

Issue: The lemlist server doesn't appear in your client

  • Root cause: Depends on how you connected—check the path you used.

  • Fix:

    • Claude: there's no config file to check. Confirm lemlist is listed under Customize > Connectors, and on Team/Enterprise that an Owner has added it.

    • Claude Code: run claude mcp list to confirm the server was added. If you used the default --scope local, it only exists in the project where you ran the command.

    • Cursor: validate your JSON (missing braces/commas are common) and confirm the file path: ~/.cursor/mcp.json or .cursor/mcp.json.

    • ChatGPT web: if Scan tools returned nothing, the endpoint or the authorization didn't complete—re-check both, then scan again.

    • ChatGPT desktop / Codex: run codex mcp list, validate your TOML, and confirm the table header is exactly [mcp_servers.lemlist]. Restart the desktop app after editing the file.

    • Legacy mcp-remote setup only: ensure Node.js is installed and npx works (or use the Windows npx.cmd path), then restart Claude Desktop fully.

Issue: You can connect, but tools fail unexpectedly

  • Root cause: Network restrictions, temporary service issues, or incorrect endpoint.

  • Fix:

    • Confirm the MCP server health endpoint is reachable: GET /mcp/health on https://app.lemlist.com.

    • Retry after a short delay.

    • Check whether your environment blocks outbound HTTPS requests.

Technical Reference (for advanced users)

  • Endpoint: https://app.lemlist.com/mcp

  • Stack: Node.js (MeteorJS)

  • Protocol: MCP (JSON-RPC 2.0 over HTTP/POST, streamable HTTP)

  • Auth: OAuth 2.1 with PKCE and dynamic client registration, or API key in X-API-Key header

  • Token lifetime: access token ~1 hour, refresh token ~30 days

  • Validation: Zod schemas for inputs

  • Health check: GET /mcp/health

Related Articles
Did this answer your question?