LeadReef
Technical reference

LeadReef MCP server

Connection, authorization, limits, errors and every tool the server exposes. To connect a specific app step by step, see the setup guide.

Last updated Server v1.0.0MCP 2025-11-25docs.md

Connection

https://api.leadreef.ai/mcp
TransportStreamable HTTP. Remote server, nothing to install. Stateless: every request is a POST and gets a JSON response; there are no sessions and no server-sent event stream.
ProtocolMCP 2025-11-25. Clients on 2025-06-18, 2025-03-26 and 2024-11-05 are also accepted.
CapabilitiesTools only. No resources, prompts or sampling.
CannotSend messages, delete leads, change billing or publish sites.

Authorization

OAuth 2.1 with PKCE (S256). The user signs in on leadreef.ai and approves the client there; the client never sees the password. Unauthenticated requests get 401 with a WWW-Authenticate header pointing to the resource metadata below.

Resource metadatahttps://api.leadreef.ai/.well-known/oauth-protected-resource/mcp
Server metadatahttps://api.leadreef.ai/.well-known/oauth-authorization-server/api/auth
Client registrationClient ID Metadata Documents (an HTTPS URL as client_id), or Dynamic Client Registration (RFC 7591). No pre-registration needed.
TokensBearer access tokens in the Authorization header (never in the URL), with refresh tokens through offline_access. Access stops at once when the user disconnects the app in Settings → Connected apps.

Scopes

leads:readRead searches, leads, contacts and account. Required by every tool except start_search.
leads:searchRun searches, which spend credits. Required by start_search.

Rate limits

Per user, across all connected apps. Over a tool limit, the call returns RATE_LIMITED with the seconds to wait.

60 / min
All tool calls
10 / min
start_search, and 100 a day
300 / hour
get_lead_contacts
120 / min
HTTP requests to /mcp

Tools

9 tools. Only start_search spends anything; every other tool reads the account and is free. Every tool returns structured content matching its output schema, plus a short text summary.

get_account
Check plan and credits
scope: leads:read
Returns your plan, credit balance and, on the free plan, how many free searches are left today.
Parameters: None
Returns: plan, credits_balance, free_search (limit, used, remaining, resets_at), can_use_extended_search, pricing_url
Cost: Free
list_supported_free_searches
List free-plan searches
scope: leads:read
Lists the business type + city pairs the free plan can search.
Parameters: country (ISO-2, optional), business_type (optional filter)
Returns: combos (business_type, location, country), total
Cost: Free
list_searches
List recent searches
scope: leads:read
Lists your lead searches, newest first.
Parameters: page, per_page (up to 25)
Returns: searches (search_id, business_type, location, status, lead_count, mode, created_at), total, next_page
Cost: Free
list_leads
List leads
scope: leads:read
Lists your saved leads across all searches, or the leads of one search ranked by opportunity.
Parameters: search_id, status, has_email, query, page, per_page (up to 25)
Returns: leads (business, city, website, problem, top issue, opportunity score, rating), total, page, next_page
Cost: Free
get_lead
Get lead details
scope: leads:read
One lead's full card: what is wrong with its website, the issues worth pitching, screenshots and any drafted outreach.
Parameters: lead_id, include_images
Returns: the lead card plus explanation, pitchable_signals, other_signals, screenshots, existing_drafts, has_built_site
Cost: Free
get_lead_contacts
Get lead contacts
scope: leads:read
One lead's phone, email, address and social profiles, as shown in the app.
Parameters: lead_id
Returns: phone, email, address, hours, contact_page_url, socials, website_url, maps_url, app_url
Cost: Free

Errors

Auth and transport failures come back as HTTP status codes. Everything else is a tool result with isError: true and a body with code, message, retryable and request_id, so the AI can explain the problem to the user.

401invalid_tokenMissing, expired or revoked token, or the app was disconnected. The client should start the OAuth flow again.
403insufficient_scopeThe token lacks a scope the call needs, for example leads:search for start_search.
403account_suspendedThe LeadReef account is suspended.
429rate_limitedOver the HTTP request limit. Retry-After gives the seconds to wait.
toolVALIDATION_ERRORA parameter is missing or out of range. The message names the problem.
toolNOT_FOUNDThe search_id or lead_id does not exist or belongs to another account.
toolINSUFFICIENT_CREDITSNot enough credits for this search. Nothing was charged. Check with estimate_search first.
toolFREE_QUOTA_EXHAUSTEDThe free plan's daily search is already used. resets_at says when the next one is available (midnight US Eastern).
toolPLAN_REQUIREDThe free plan only searches the pairs from list_supported_free_searches, and depth: extended needs Pro or Scale. required_plan names the plan.
toolDISPOSABLE_EMAILFree searches are not available on accounts with a disposable email address.
toolRATE_LIMITEDOver a tool rate limit. retry_after_seconds gives the seconds to wait.
toolSEARCH_FAILEDThe search failed. Any credits it charged were returned; starting a new search may work.
toolTEMPORARILY_UNAVAILABLELeadReef is briefly unavailable. Retry in a moment.
toolINTERNALUnexpected error on LeadReef's side. Retry once.

Client setup guides

Step-by-step guides for specific apps. Other clients are covered on the setup page.

ClaudeChatGPTCursor

Changelog

1.0.0 · 6 Nov 2026First public release: 9 tools, OAuth 2.1 with PKCE, Client ID Metadata Documents and dynamic client registration.

How LeadReef handles your data: privacy policy. Machine-readable version of this page: docs.md.