LeadMarina on the Model Context Protocol

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external systems. Anthropic open-sourced it in November 2024; OpenAI adopted it across its products in March 2025; and in December 2025 the protocol moved to the Agentic AI Foundation, a directed fund under the Linux Foundation co-founded by Anthropic, Block, and OpenAI. It now has first-class support in Claude, ChatGPT, Cursor, VS Code, and other major AI clients.

An MCP server exposes typed tools over JSON-RPC 2.0. The client — your AI application — discovers them with tools/list, reads each tool's JSON Schema, and lets the model invoke them with tools/call. LeadMarina implements the server side of that contract: tools that search, verify, query, export and schedule local-business leads, so an agent can run your prospecting pipeline instead of you clicking through a UI.

Connecting

The server runs at https://leadmarina.com/api/mcp over streamable HTTP, the spec's remote transport: a single endpoint, one HTTP POST per JSON-RPC message. LeadMarina answers each message with plain JSON — there is no event stream to open and no session to keep. There is nothing to install locally — add the URL wherever your client configures MCP servers (a connector in Claude or ChatGPT, an entry in Cursor's mcp.json, an MCP server in VS Code).

Authentication works two ways:

• OAuth 2.1. initialize and tools/list answer without credentials, so a client can show what LeadMarina does before you connect. Every other request — every tools/call — needs one: without a valid credential the server returns 401 with a WWW-Authenticate header pointing at its protected resource metadata (RFC 9728). Clients that support dynamic client registration (RFC 7591) then register themselves, open a browser window for consent, and complete the PKCE flow automatically. From your side this is: paste the URL, click Authorize.
• API-key headers. For headless agents or clients without OAuth support, pass a LeadMarina API key — the same bearer keys the REST API uses, available on every plan including free.

If a key or token can't be checked because of a problem on our side, the answer is a JSON-RPC error that says so — never a 401, so your client stays signed in. Retry in a few seconds.

The tools

• search_leads — start a search with one niche and one city per call. It returns a search_id and, usually, the first batch of leads at once (in results, with their contacts still being verified); more are found and verified in the background. If the data provider is slow, the whole search is queued instead and its leads arrive through get_search_results. When your balance covers fewer leads than were found, the reply says so (capped). For multiple cities, the agent simply makes one call per city.
• get_search_results — read a search's leads, up to 1,000 per call (offset and next_offset page through the rest); poll it until enrichment reports complete to collect everything the background pipeline delivers.
• query_leads — filter, sort and read leads you already own: the whole library, or one search by its search_id. Up to 1,000 per call; send next_cursor back as cursor for the next page — it carries the filters and sort. A field, operator or value it can't use comes back as an error that names it and lists what works; the Export page lists every field and operator. Free: it never draws on your lead balance.
• enrich_domains — submit up to 10 domains you already hold per call and get back the same fully verified profile, one lead per distinct domain; it returns a search_id to poll with get_search_results.
• export_leads — push leads to Close, GoHighLevel, Google Sheets, or a CSV/Excel/JSON file. Pass a search_id to export one search, or all=true to export from your whole library; either can be narrowed with the same filter rows query_leads uses. Leads go out best-ranked first, up to 50,000 per call for CSV/XLSX, 25,000 JSON, 5,000 Google Sheets and 1,000 Close/GoHighLevel (CRMs take one API call per lead). When more match, the response says the export was partial and returns next_cursor: the same call with cursor set to it sends the next batch. A library export (all=true) continued that way reads the library live, so a lead that a search running between calls finds again can be skipped or sent twice; for one consistent copy, export the library as one file in a single call while no search is running. File exports return a download link, and email you the file too when it is small enough to attach.
• list_searches — list your recent searches with their ids, lead counts, and dates.
• get_balance — check remaining leads before committing to a large search.
• list_views — read the saved views you built on the leads table, as filter rows query_leads and export_leads accept.
• list_integrations — check which export destinations are connected and ready to receive leads.
• list_automations — see your scheduled searches: niche, cities, cadence, destination, next run and last result.
• create_automation — schedule a search to re-run on a cadence and export itself. Every city must be found, or nothing is created; every run spends leads.
• update_automation — pause or resume one.
• delete_automation — remove one for good.

Every delivered lead is fully verified: up to three emails SMTP-checked and labeled safe/risky/invalid; up to three phones with line type (mobile, landline, VoIP, toll-free) and carrier; owner name where identifiable; Facebook, Instagram, LinkedIn, X, YouTube, TikTok, and Yelp profiles; ratings, reviews, and the full business profile. Billing is a single meter: one lead = one delivered fully verified business.

Searches are asynchronous

search_leads doesn't block while the pipeline runs. Each call returns a search_id and, usually, the first batch of results; LeadMarina keeps finding and verifying more businesses in the background. Your agent polls get_search_results with that search_id until the enrichment status reads complete — at that point the background run has ended, and stage tells a finished search from a failed or cancelled one. The tool schemas describe this contract, so a capable model works out the poll loop on its own.

A typical session

Say you prompt your agent: "Check my balance, then find plumbers in Austin, Dallas, and Houston with a safe email and a mobile number, and push them into Close."

• get_balance confirms headroom.
• search_leads runs three times — one niche and one city per call — each returning a search_id and, usually, a first batch of leads.
• get_search_results is polled for each search_id until enrichment reads complete, returning the verified businesses.
• query_leads is given each search_id with two filter rows — email_status is safe, phone_line_type is mobile — and narrows each search to the leads that pass.
• export_leads sends the shortlist to Close — the agent passes each search_id along with the same filter rows, so only the safe-email, mobile-number leads go across.

Close needs its field mapping saved first, by one manual export in the LeadMarina web app; list_integrations says whether it is ready. Because each tool's schema describes its fields, the model composes these steps itself — you describe outcomes, not calls.

Update and dedupe semantics

Close and GoHighLevel exports update in place, matched by a stable Google business identifier, and so does a Google Sheets export given the spreadsheet_id of a sheet LeadMarina created before. There, re-exporting never creates duplicates and never touches data you created: notes, activities, custom fields, extra rows, and formatting are left alone; in GoHighLevel, tags are additive-only. A CSV, Excel or JSON file, and a Google Sheets export without a spreadsheet_id, is a fresh copy every call — the response's note says which happened.

• Close: connect via OAuth, then run one manual Export → Close in the LeadMarina web app. It opens the field-mapping dialog and saves the mapping that export_leads and create_automation reuse: native fields map to Close built-ins, everything else to custom fields LeadMarina auto-creates named after its columns. The mapping is tracked by Close field ID, so renaming a field in Close does not break it.
• Google Sheets: export to a new spreadsheet or one LeadMarina created before. All columns export; columns you hide arrive hidden but still update. Row identity lives in a hidden column.

Scheduling

Any search can repeat once, daily, weekly, monthly, or yearly with any export destination. Schedules are created and managed from MCP with list_automations, create_automation, update_automation and delete_automation (or over the REST API at /api/v1/schedules); list_searches surfaces each run as it lands — with its id, lead count, and date — and get_search_results pulls the latest run's leads into your agent's context — useful for a weekly agent that reviews fresh leads before they reach your CRM.

Troubleshooting

• 401 on your first tool call is expected until your client has a credential — it starts OAuth discovery (initialize and tools/list never need one). If your client stalls at registration, it may lack dynamic client registration support; switch to an API key.
• Client can't add the server: it must support remote MCP servers over streamable HTTP. If yours doesn't, the REST API covers searching, enrichment, reading your results, bulk export (POST /api/v1/exports) and automations (/api/v1/schedules) with the same bearer keys on every plan.
• Balance exhausted: the free plan includes 100 leads; paid plans are 15,000, 65,000 or 240,000 leads per month, and Unlimited has no monthly quota at all — up to 210,000 leads a week. query_leads stays free either way, so agents can keep working with leads you already own.