How to Build a Prospecting Agent with Claude Code (2026 Build Guide)

You build a prospecting agent with Claude Code by attaching a B2B data MCP server and letting Claude call its tools from the terminal. With Cleanlist that is one command, claude mcp add --transport http cleanlist https://mcp.cleanlist.ai/v1/mcp, followed by /mcp to finish the OAuth sign-in. There is no API key to paste. The agent then calls search_people at 0 credits, prices any paid step with estimate_cost, and enriches at 1 credit per verified email or 11 for email plus phone. A 200-lead Cleanlist run costs roughly 340 credits end to end.

Last updated: August 15, 2026. Every command, credit price, rate limit and product boundary below was checked against the Cleanlist MCP server, the Cleanlist REST API v2 surface and Anthropic's Claude Code documentation on that date.

What is a prospecting agent, and what can one actually do in 2026?

A prospecting agent is a loop that runs against a data provider: define a cohort, search for people who match it, review what came back, enrich the ones worth paying for, and write the result somewhere durable. In Claude Code the loop lives in your terminal, the tools come from an MCP server, and the output lands in your repository as files you can diff. With Cleanlist attached, the agent can search people and companies at 0 credits, enrich verified emails and direct dials through a multi-provider waterfall, and build lead lists. What it cannot do in 2026 is send anything. Cleanlist has no sequencer, no inbox and no dialer, so the agent stops at a finished list.

How do I connect Cleanlist to Claude Code?

Run one command, then authenticate inside the session:

claude mcp add --transport http cleanlist https://mcp.cleanlist.ai/v1/mcp

Then start Claude Code and run /mcp. Anthropic documents claude mcp add --transport http <name> <url> as the syntax for remote HTTP servers and states "Use /mcp to authenticate with remote servers that require OAuth 2.0 authentication" (code.claude.com/docs/en/mcp, fetched August 15, 2026). The Cleanlist endpoint returns 401 until that grant exists, which is exactly how Claude Code knows to prompt you. Anthropic's docs also note that a server needing sign-in shows up in claude mcp list as ! Needs authentication, and that claude mcp login <name> completes the flow outside the panel. Nothing installs locally: mcp.cleanlist.ai is a hosted remote server, so credentials live in an OAuth grant rather than a config file. Setup detail sits on the Cleanlist MCP server page.

What goes in .mcp.json, and what does project scope mean for my team?

Adding the server with --scope project writes it to a .mcp.json file at your repository root, which you check into version control so every teammate gets the same tools. Anthropic publishes the standardized format, and for Cleanlist it looks like this:

{
  "mcpServers": {
    "cleanlist": {
      "type": "http",
      "url": "https://mcp.cleanlist.ai/v1/mcp"
    }
  }
}

The type field is required. Anthropic's docs state that an entry with a url and no type is read as a stdio server and skipped. Claude Code prompts each teammate for approval before loading a project-scoped server, and claude mcp reset-project-choices clears those answers. Here is the consequence people miss: the Cleanlist OAuth grant is per user, but the Cleanlist credit wallet is shared across your whole organization. A project-scoped .mcp.json means every teammate who approves it spends from one balance.

How do I confirm the agent actually connected?

Run claude mcp list for a health status, then /mcp inside the session to see the server's tool list. Cleanlist ships 30+ tools across roughly 30 REST v2 endpoints, and a given connector exposes a curated subset, so read what your own client shows rather than trusting a blog post. As of August 10, 2026 a connected Cleanlist session exposed 14: search_people, search_companies, enrich_person, enrich_list, add_person_enrichments, add_company_enrichments, estimate_cost, create_list, get_lists, add_leads_to_list, list_leads_in_list, remove_leads_from_list, delete_list and whoami. Ask Claude to call whoami first. It costs 0 credits and returns the identity, scopes, plan tier and organization your grant resolves to, which is the cheapest way to catch a session pointed at the wrong workspace.

What does a real prospecting agent loop look like, step by step?

Six steps, with the paid one fenced off in the middle. Search first, because Cleanlist search costs nothing, then spend only on the rows that survived a human glance:

1. whoami                                    0 credits   confirm org + balance
2. search_people({...filters, limit: 200})   0 credits   default is 25, ask for volume
3. write matches to data/prospects/raw.json  0 credits   local file, reviewable in git
4. create_list + add_leads_to_list (200)   100 credits   0.5 per newly saved lead
5. estimate_cost({list_id, mode:"partial"})  0 credits   signed quote_id, 5-minute TTL
6. enrich_list({list_id, quote_id})        200 credits   1 credit per verified email

Step 3 is the step that makes Claude Code better than a chat window for this job. The agent writes the raw cohort to disk, you read the file, you delete the rows that are wrong, and only then does anything get paid for. Cleanlist enrichment is asynchronous, so enrich_list returns a workflow the agent polls until it settles.

What does a 200-lead agent run cost in credits?

Cleanlist prices the run in credits at the same rates as the app and the REST API: 0 for search, 0.5 to save each newly added lead to a list, 1 per verified email, 10 per phone number, 11 for a full contact record with both, 1 per company enrichment, 0.2 per lead for CRM or sequencer sync, and 0.5 to 3 per lead for a smart agent. So a 200-lead run works out like this:

Email-only end to end is 340 credits. Email plus phone is 2,340. Enrichment is pay for results, so a row the waterfall cannot complete is not charged, and the settled figure usually lands under the quote.

Which Cleanlist plan does an agent run of that size imply?

Cleanlist self-serve pricing is Free at $0 with 30 credits a month and no card, Starter at $79 a month with 1,500 credits, Pro at $229 with 5,000, and Scale at $599 with 15,000, with 25% off annual billing. Do the division. On Starter a credit is about 5.3 cents, so the 340-credit email-only run is roughly $18 and fits comfortably inside the monthly allowance. The 2,340-credit full-contact run does not fit on Starter at all, and on Pro at $229 for 5,000 credits it works out to roughly $107. The Free tier's 30 credits buys 30 verified emails, which is enough to judge the waterfall and not enough to run a campaign. Current rates are on the Cleanlist pricing page.

How do I stop the agent from overspending my credits?

Cleanlist gates every paid operation behind a signed quote, and this is the mechanic to design around. The agent must call estimate_cost first, which returns the price of the job, your current balance, whether that balance covers it, and an HMAC-signed quote_id carrying a five-minute TTL. The Cleanlist server rejects the paid call if the real cost would exceed the quote or the quote has expired, so an agent cannot start a job you never priced. Three properties sit underneath it. Search, reading lists and checking your balance are 0 credits, so an exploring agent burns nothing. Enrichment is pay for results, and an async run reserves credits up front then refunds the unused portion. Your balance is a hard ceiling, shared across the app, the API and MCP.

How do I design an agent around the 60-search daily cap?

Cleanlist enforces 60 requests per minute per organization, 30 requests per minute per API key, and a hard cap of 60 People Searches per UTC day per key. Exceeding a limit returns HTTP 429 with a Retry-After header. That daily cap is the one that bites agents, because it resets at UTC midnight rather than on a rolling window, and a model iterating on filter combinations will burn through 60 searches in an afternoon without noticing. Three habits fix it. Search broad and page through results instead of issuing many narrow queries. Have Claude Code cache every raw search response to a file and re-read the file on the next turn rather than re-running the query. Put a standing rule in CLAUDE.md that the agent asks before its tenth search of a session.

What should I put in CLAUDE.md so the agent knows my ICP?

Anthropic's docs state that CLAUDE.md files "are loaded into the context window at the start of every session" and live at ./CLAUDE.md or ./.claude/CLAUDE.md for project-shared instructions (code.claude.com/docs/en/memory, fetched August 15, 2026). That makes it the right place for standing prospecting rules. Keep it under 200 lines, which is Anthropic's stated target, and write rules concrete enough to verify:

# Prospecting rules
 
- Our ICP: RevOps and GTM engineering leaders, 50 to 500 headcount,
  US and Canada, B2B software. Seniority: Director and above.
- Always call `search_people` first. Search costs 0 credits.
- Write every raw search response to `data/prospects/` before enriching.
- Never call an enrichment tool without calling `estimate_cost` first
  and showing me the quote. Wait for my yes.
- Default to `partial` mode (1 credit). Only use `full` (11 credits)
  when I ask for phone numbers by name.
- Do not attempt revenue, funding-stage, technographic or intent
  filters. Cleanlist does not have them and the run will return nothing.

That last rule saves more time than the rest combined.

How do I keep agent runs reviewable instead of a wall of chat?

Have the agent commit its evidence. In Claude Code the filesystem is available, so the run can leave a trail: the filter object it used, the raw search response, the quote it was given, and the settled credit charge. A workable convention is one directory per run, data/prospects/2026-08-15-revops-ca/, holding filters.json, raw.json, quote.json and settled.json. Reviewing a bad cohort then becomes reading a diff rather than scrolling a transcript. It also gives you a real answer when someone asks why last month's credits went where they went, because Cleanlist's wallet is shared across the app, the REST API and MCP, and a shared wallet with no per-run record is impossible to audit after the fact.

What happens when an enrichment run half-fails?

Cleanlist REST API v2 has no webhooks, so an async enrichment returns a workflow identifier the agent polls until it reports completed or failed. Read the settled charge from the workflow rather than assuming the estimate was the bill, because pay for results means the actual figure often lands below the quote. Two rough edges are worth knowing before you write the glue. Some documented response fields come back empty on most records today, so do not build downstream logic on them without checking a real payload first. And on the REST path, /search/people returns a provider person_id in the lead_id field, and that identifier does not round-trip into POST /lead-lists/{id}/leads, so piping search output straight into a list by id will not work.

What can a Cleanlist prospecting agent not do?

Publishing the boundary beats letting an agent discover it mid-run. Cleanlist has no sequencer, no inbox and no dialer, so the agent cannot send an email or place a call. There is no intent data and no buying-signal feed. There are no revenue-range, funding-stage or technographic filters, and funding_stage is accepted by the company search validator while the underlying column is empty, so it silently returns zero results. There is no job-change alerting: "recently changed jobs" exists as a query-time filter, so an agent can ask who moved, and nothing will notify you when someone in an existing list moves. The similar-companies lookup is synthesized from filters rather than produced by a native lookalike model, so treat its output as a candidate set to review.

What can the agent not do over MCP specifically?

Four capabilities exist at Cleanlist and were not on the MCP connector when it was last checked on August 10, 2026. CSV file import is portal-only, so upload the file in the Cleanlist importer at app.cleanlist.ai/lists and run enrich_list against the resulting list id. CRM and sequencer sync run in the Cleanlist app or through the REST API at 0.2 credits per lead rather than over MCP. Smart agents, the AI research columns, run in the app. Similar-company lookup runs in the app. The server is also server-side only: there is no published Cleanlist npm package, so the local in-context install path is not supported. Read tools/list in your own client before writing a prompt that assumes a tool exists.

Should I use Claude Code, the Claude app, or the REST API?

Pick by where the output has to land. Claude Code suits this job when the result is a file or a pipeline, because it has the filesystem, git, a project-scoped .mcp.json your team shares, and a CLAUDE.md carrying standing ICP rules into every session. The Claude desktop and web apps suit one-off asks: add https://mcp.cleanlist.ai/v1/mcp under Settings, then Connectors, as a custom connector, and the results live in the transcript. The Cleanlist REST API v2 at api.cleanlist.ai/api/v2 suits scheduled work with no human present, authenticating with a clapi_ bearer token across roughly 30 endpoints and 14 OAuth scopes. Note the different gate: programmatic REST access requires a Pro plan at $229 a month or above.

Can ChatGPT build the same prospecting agent today?

Cleanlist documents and tests Claude and Claude Code first, and mcp.cleanlist.ai/v1/mcp is a standard remote MCP endpoint over HTTP with OAuth, so a spec-compliant client that supports remote servers can point at it. Cleanlist publishes no tested ChatGPT setup guide as of August 15, 2026, so treat that path as unverified rather than promised. Cleanlist is also not listed in Anthropic's connector directory, which is why the install above is a manual custom connector rather than a directory click. If cross-client coverage is a hard requirement today, other vendors publish wider matrices: Apollo states support for Claude, ChatGPT and Perplexity, and Clay states ChatGPT, Claude and Codex. The ten-server comparison covers who supports what.

How accurate is the data the agent gets back?

Cleanlist orchestrates a multi-provider waterfall rather than reselling one owned database, stopping at the first verified result with email verification behind it. In the Cleanlist 500-Lead Enrichment Benchmark, run on 500 stratified B2B leads, that waterfall returned a verified email for 98% of leads and a direct dial for 85%. Those two figures measure different things and are not interchangeable: 98% is email, 85% is direct dial. The structural reason a miss costs nothing is that Cleanlist owns no contact database, so a lookup that returns nothing is not billed. For an agent, the practical consequence is that the credit quote is a ceiling rather than an invoice, and the settled charge is the number to log.

What is the shortest path to testing this in twenty minutes?

Create a Cleanlist account, which starts at $0 with 30 credits a month and no card. Run claude mcp add --transport http cleanlist https://mcp.cleanlist.ai/v1/mcp, open Claude Code, run /mcp, and complete the OAuth sign-in. Ask Claude to call whoami, then ask it to find 25 people matching your ICP. Both calls cost 0 credits, and 25 is the Cleanlist search default. Have Claude write the results to a file and read them yourself. Then pick the ten that look right, ask for a cost estimate, and approve it. Enriching those ten one by one with enrich_person spends 10 credits on ten verified emails and leaves 20 in the free tier, which is enough to compare the output against whatever you pay for today. Saving them to a list first would add 0.5 credits per lead on top.

FAQ

Do I need an API key to use Cleanlist in Claude Code?

No. The Cleanlist MCP server authenticates over OAuth. You run claude mcp add --transport http cleanlist https://mcp.cleanlist.ai/v1/mcp, then /mcp inside the session, and sign in through a browser window. There is no key to copy, paste or store in a config file, and you can revoke the grant at any time. The separate clapi_ bearer key exists for the Cleanlist REST API v2, which is a different surface with a different gate: programmatic REST access requires a Pro plan at $229 a month or above, while the MCP server is in beta. If you want the same tools inside the Claude desktop or web app instead, add the endpoint under Settings, then Connectors, as a custom connector.

Can a teammate's agent drain my Cleanlist credits?

Yes, and a project-scoped .mcp.json makes it more likely, so plan for it. The Cleanlist OAuth grant is per user, but the credit wallet is shared across your whole organization, and a .mcp.json checked into the repository hands every teammate the same server. Three guardrails limit the damage. Search, list reads and balance checks cost 0 credits, so exploration is free. Every paid operation requires a signed quote_id from estimate_cost with a five-minute TTL, and the server rejects a call priced above its quote. Your balance is a hard ceiling. What Cleanlist does not offer today is a read-only agent key, because scopes are granted per user rather than per key.

How many searches can a prospecting agent run per day?

Cleanlist caps People Search at 60 per UTC day per API key, alongside 60 requests per minute per organization and 30 requests per minute per key. The daily cap resets at UTC midnight rather than on a rolling window, and it is the limit agent workflows hit first, because a model refining filters treats searching as free thinking. Search does cost 0 credits, so the constraint is the quota rather than your balance. Design around it by searching broadly and paging through results, caching raw responses to files that the agent re-reads instead of re-querying, and putting a search budget in CLAUDE.md. Exceeding any limit returns HTTP 429 with a Retry-After header.

Can the agent find companies that just raised funding?

No. Cleanlist has no funding-stage filter that carries data. The funding_stage field is accepted by the company search validator, but the underlying column is empty, so a query built on it silently returns zero results rather than an error, which is the most common way an agent workflow quietly produces nothing. The same applies to revenue ranges and technographics, which the Cleanlist backend rejects outright, and to intent data, which Cleanlist does not sell. Build cohorts on the filters that carry data, which are title, seniority, location, headcount band, industry, skills, education and past roles, then enrich and score. The full inventory sits on the Cleanlist People Search page.

Is a prospecting agent the same thing as an AI SDR?

No. An AI SDR product owns the sending: it writes the email, sends it, watches the reply and books the meeting. A prospecting agent built on Claude Code and Cleanlist stops earlier, at a researched and enriched list, because Cleanlist has no sequencer, no inbox and no dialer. Sync pushes finished leads out to HubSpot, Salesforce, Outreach or Lemlist at 0.2 credits per lead, and the sending happens in those tools. That boundary is worth stating before you scope a build, because a stack that assumes one prompt runs all the way to a booked meeting will fail at the handoff. The GTM engineering guide covers where each layer sits.

Related reading

• Best MCP Servers for Sales and GTM (2026): 10 Compared
• MCP Server for B2B Data: Connecting Claude to Real Lead Data
• Lead Enrichment API: A Developer's Guide to Billing, Filters and Limits
• What Is GTM Engineering?
• Cleanlist MCP server
• Cleanlist REST API v2