# How to Connect Claude Code to lemlist, the Operator Guide > Canonical: https://www.yalc.ai/blog/connect-claude-code-to-lemlist/ The MCP setup, the REST endpoints the connector never touches, and the draft state rule that keeps an over eager agent from torching your sender domain. Connect Claude Code to lemlist by running `claude mcp add --transport http lemlist https://app.lemlist.com/mcp` and authorizing through OAuth in your browser. That gives Claude read and write access to campaigns, leads, and stats. For lower level control, hit the REST API at api.lemlist.com with your API key over HTTP Basic auth. Pick the door by the job. Most of the ranking guides stop at the OAuth command. That is the easy half. The interesting half is what the sequencer will and will not let an agent touch, how the object model actually works, and the one rule that keeps an autonomous run from silently frying your sender domain. This is the operator walk through. ## Two ways in, the MCP server and the REST API There are two transports and they solve different problems. The MCP server at `https://app.lemlist.com/mcp` wraps the useful lemlist actions as tool calls a Claude conversation can invoke directly. It is the fastest install and the safest daily driver. The REST API at `https://api.lemlist.com` is the raw HTTP surface. You reach for it when you want a scheduled job, a step MCP has not wrapped, or a call inside a custom script. Both are yours the moment you have a paid lemlist seat. There is no separate MCP charge. What you do pay for is credits inside actions that hit the data provider, which we get to in the gotchas section. If you are still weighing whether lemlist is the right sequencer for the middle mile at all, the [lemlist product page](/tools/lemlist/) is the short version, and the roundup of [the best AI cold email tools in 2026](/blog/best-ai-cold-email-tools-2026/) is the long version. The MCP path fits the way Claude Code already thinks about tools. The REST path is where you go when the tool wrapper stops at the edge of what the vendor decided to expose. Real operator work uses both, and picking one over the other on principle is how you end up rebuilding a workflow twice. The broader map for how MCP servers sit in a GTM stack lives in [MCP servers for GTM](/blog/mcp-servers-for-gtm/). ## Authentication and the first call that proves it works The MCP install is one command in Claude Code. ```bash claude mcp add --transport http lemlist https://app.lemlist.com/mcp ``` Run that, hit `/mcp` inside your session, pick lemlist, click Authenticate. Your browser opens the lemlist consent page. Choose the team you want the agent to act inside. Come back to the terminal. The connection is live. Access tokens hold for an hour and refresh tokens for 30 days, so a running agent does not have to re authenticate mid task. If you want API key auth instead, generate a key inside lemlist under Settings, then Team, then Integrations. Copy it once, because lemlist does not show it again. Then run the same command with a header flag. ```bash claude mcp add --transport http lemlist https://app.lemlist.com/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` The REST API uses a different auth shape and this trips people who assume both transports work the same way. REST expects HTTP Basic auth with the username left empty and the API key as the password, per [the lemlist developer docs](https://developer.lemlist.com/api-reference/getting-started/authentication). One transport uses a header, the other uses a base64 encoded credential. Same key, two shapes. If you get a 401 on the REST side after MCP works fine, this is why. The first call worth running is the cheapest one that proves auth. Ask Claude to fetch your team, or from a shell hit `GET https://api.lemlist.com/api/team` with your Basic auth header. If you get a JSON object with your team id and members back, you are wired up. If you get 401, the API key is wrong. If you get 429 on the first call, another script is already burning your rate window, which is a preview of the gotchas below. > Figure: Four step lemlist agent flow with a human approval gate before the campaign starts ## What the lemlist API exposes and what it does not The object model is smaller than the marketing pages suggest, which is a good thing. There are campaigns, senders, leads, activities, unsubscribes, hooks, and team. Every serious workflow moves data between those seven collections. Campaigns hold the sequence, its steps, its schedule, and its status. Senders are the mailboxes attached to a campaign. Leads are the prospects, and a lead only exists in the context of a campaign. Activities are the event log, the atomic timeline of sends, opens, replies, and bounces. Unsubscribes and hooks are the exhaust that keeps you compliant and integrated. Team is the wrapper. What the API does not give you is more revealing than what it does. There is no endpoint that drafts a reply and posts it into the running conversation, no endpoint that changes the warmup settings, no endpoint that books the meeting on the reply side. The connector reads events, it does not write into the inbox. If a competing article promises an agent that "handles replies automatically" through lemlist, it is either running a separate scheduled process on top of activities, or it is misrepresenting the surface. This is the same last mile gap we cover in the [instantly vs lemlist](/blog/instantly-vs-lemlist/) breakdown, and the take there applies here too. Reply craft stays a human job. ## Pushing leads with personalization variables The workhorse call is a POST that adds a lead to a campaign with custom fields. The endpoint is `POST /api/campaigns/{campaignId}/leads?email=jane@acme.com`, and any additional query parameter beyond the standard fields becomes a custom variable available in your sequence templates. Reference it as `{{fieldName}}` inside the subject line or the body. The trap is naming. lemlist reserves nine default variable names and will refuse to create a custom variable that collides with any of them: `email`, `firstName`, `lastName`, `picture`, `phone`, `linkedinUrl`, `companyName`, `companyDomain`, and `icebreaker`. If your agent tries to add a lead with a custom field called `phone` because your CRM schema calls it that, you get a 400 back and the write does not land. Rename to `mobilePhone` or `phoneVerified` upstream in the agent's data model so the collision never happens. Custom variables also cost you something worth naming. Every variable you add becomes a permanent column on the campaign's lead table. Six well chosen variables that drive real opener personalization beat forty low signal ones the agent will never reference. Draft the variable schema before you push, not after. If you want the reusable pattern for turning an ICP definition into a lemlist campaign the agent runs end to end, the [lemlist campaign from ICP skill](/skills/lemlist-campaign-from-icp/) is the one we ship for this exact loop. ## Creating a sequence without starting it Every campaign the API creates lands in `draft` status. Leave it there. The tempting move is to script the whole flow, create campaign, add steps, push leads, then flip the status to `running`. Do not do the last step from the agent. The reasoning is not paranoia. Since February 2024, Google and Yahoo require any sender above 5,000 messages a day to authenticate with SPF, DKIM, and DMARC and to hold a spam complaint rate under 0.3 percent, per [Google's bulk sender guidelines](https://support.google.com/a/answer/81126). A single mis fired sequence at 3am, wrong subject line, wrong audience, wrong variable resolving to `undefined`, can push a complaint rate over that line in one morning. Once your domain is throttled, no vendor lets you back in for weeks. The cost of a bad automated Start is measured in months of pipeline, not in hours. The pattern that survives production is one line long. Agent drafts the campaign, adds the steps, pushes the leads, sends you a summary link. You open the campaign, review the first three leads and the first two emails, click Start yourself. That single human gate does not slow the loop enough to matter, and it puts a person's name on every domain risking decision. It is the same first mile last mile rule the [Claude Code for SDRs](/blog/claude-code-for-sdrs/) piece works through in more detail. Humans own the decisions. The agent owns the plumbing. ## Reading replies and stats back into the agent Once the campaign is running, the agent stops writing and starts reading. Two endpoints do most of the work. `GET /api/campaigns/{campaignId}/stats` returns the roll up. Opens, replies, bounces, unsubscribes, click through counts, all keyed to the campaign. `GET /api/activities` returns the timeline. Each row is a single event, sent, opened, replied, hard bounced, with the lead id and timestamp. Ask the agent for both at the end of every day and you get the report an SDR manager used to write by hand. The value shows up on the second run, not the first. Feed those events into a persistent memory system and the agent starts learning. Which openers land, which industries never reply, which sender warms up slowest. Which is exactly what a stateless connector cannot do on its own, and it is why the write once memory pattern from [Claude Code agent memory](/blog/claude-code-agent-memory/) is where the compounding actually lives. A run that does not store what happened is a run that will make the same mistake next week. ## Rate limits, reserved variables, and the other gotchas Four things bite operators after week one, and none of them show up in the ranking guides. The first is the rate limit. lemlist caps the REST API at 20 requests per 2 seconds per API key, ceiling of about 10 requests per second, per [the lemlist authentication docs](https://developer.lemlist.com/api-reference/getting-started/authentication). Cross it and you get 429 with a Retry After header telling you how long to wait. If your agent enrichs 500 leads inside a tight loop with no backoff, you will hit the wall on lead 41. Batch the pushes and respect the header. The second is credit consumption. lemlist actions that touch the built in data provider, verified email lookup, phone enrichment, intent signals, spend credits at $0.01 each, verified as of September 2026 on [lemlist's pricing page](https://www.lemlist.com/pricing). A verified email is 5 credits, a phone is 20, and intent signals start at 20 and climb from there. A lightly supervised agent that verifies every lead twice can quietly burn through a month's credit budget in a single evening. Hard cap the enrichment calls in the agent's prompt and require a human confirm before any bulk enrich above a threshold. The third is the auth shape trap noted earlier. MCP takes an `X-API-Key` header. REST takes HTTP Basic auth with an empty user field. If you copy the value from one context into the other verbatim you will get 401s and burn an afternoon on the wrong hypothesis. The fourth is the difference between what the MCP wrapper exposes and what the raw REST API can do. The MCP server ships with the happy path already implemented. The REST API is a larger surface, especially around activities, hooks, and custom variable management. If the MCP toolbox is missing a specific action your workflow needs, drop into the REST layer for that one call rather than waiting for a wrapper update. And if lemlist is the wrong sequencer for the shape of outbound you are running, the [instantly product page](/tools/instantly/) covers the other main choice at this altitude. Pricing worth carrying around, verified this week from the lemlist pricing page. Email plan is $69 per month, or $55 billed annually. Multichannel is $109 per user per month, or $87 annually, and adds LinkedIn, calls, WhatsApp, and SMS. New customer pricing rose $10 per user per month on February 5th, 2026; existing seats are grandfathered unless you change plan. ## Where Yalc sits on top of the connection Connecting Claude Code to lemlist gets you a smart sequencer. It does not get you a system. A system means the same conversation that pushes the campaign also sourced the leads yesterday, scored them last week, and will read the replies tomorrow, with every step stored as a markdown file you can inspect and edit like code. That is what Yalc adds. Not another cold email tool. A folder of skills and MCP wiring that runs on your machine, keeps the tools you already pay for, and holds state across runs so the agent gets sharper on your data instead of starting cold every conversation. lemlist stays in the stack. So does the CRM, the enrichment provider, the LinkedIn tool. What gets replaced is the glue and the graph editor. The middle mile compounds because you can read every prompt and change any of them the moment you notice something drift. The architectural property this pattern leans on is called Compounding, and it is the reason a markdown configured agent beats a hosted AI SDR on the second month even when the demos look similar. A hosted product forgets what it learned when the tab closes. A file on your disk does not. ## Run it from one prompt Set aside 30 minutes this week. Run the MCP install command, complete the OAuth flow, and ask Claude for a JSON summary of your five most recent campaigns. If that call returns clean, you have the wiring done. Then draft one campaign end to end, add three test leads with two custom variables, and stop before Start. Open lemlist, look at the campaign, and verify the variables resolved the way you expected inside the preview. That single dry run tells you more about the connection than any doc page. Once the loop feels natural, add the REST layer for the calls MCP does not cover, and put the stats read in a scheduled morning check. Keep the human on the Start button. Keep the agent on the plumbing. That is the version of this integration that survives past week three. ## Frequently asked questions ### Does Claude Code integrate with lemlist? Yes. lemlist ships an official MCP server at `https://app.lemlist.com/mcp` that Claude Code registers with a single `claude mcp add` command over OAuth. Once authorized, Claude can read your campaigns and activities and can create sequences, push leads, and update campaigns on your behalf. Anything outside that surface, including inbox writes, is available only through the raw REST API. ### Do I need a paid Claude plan to connect Claude Code to lemlist? You need a lemlist seat and a Claude plan that supports custom MCP connectors. Claude Code on Pro and Max both handle the OAuth flow described here, and there is no separate charge from lemlist for MCP access. The only extra spend is on credits inside actions that hit lemlist's data provider, at $0.01 per credit. ### Should I use OAuth or an API key for the connection? Use OAuth for interactive Claude Code sessions and the API key for scheduled or headless runs. OAuth handles token refresh automatically and keeps the browser as the consent surface, which is the safer default when you are exploring. Switch to the `X-API-Key` header for cron jobs, CI runs, and anything that cannot open a browser mid task. ### Can Claude reply to prospects inside lemlist automatically? No. The lemlist API does not expose an endpoint for drafting or sending replies from an inbox thread, and the MCP server inherits that limit. Claude can classify replies from the activities feed and suggest a draft in the conversation, but a human still moves the reply into the sending seat. Reply craft is the last mile, and lemlist keeps it there on purpose. ### What is the lemlist API rate limit? The lemlist REST API allows 20 requests per 2 seconds per API key, roughly 10 requests per second, per the lemlist developer docs. When you cross it the API returns a 429 with a `Retry-After` header telling you how many seconds to back off. Any agent making bulk pushes should batch its calls and respect the header rather than retrying immediately. ### Can Claude Code connect to more than one lemlist team? Yes. Register each team as a separate MCP entry with a unique alias, for example `lemlist-team-a` and `lemlist-team-b`. Each authenticates independently, so switching between them is a matter of naming the right server in the conversation. The keys and OAuth tokens never mix.