MCP tools

The Leadveyor MCP server has 23 tools and 3 kinds of resources. Each tool runs one or more REST API operations with your key, so permissions, validation and results are the same as in the API.

Every tool also takes an optional workspaceId (ws_…). It is only needed with an account-wide key or a console session — see Workspaces. It's left out of the tables below.

Permission is the lowest key permission the tool needs. Hint is what the tool tells the client: read-only, changes data, or can't be undone (the client should ask you first).

Leads

evaluate_lead

Score a message right away without storing anything: finds the lead(s) in it, filters junk, extracts the details and scores each lead. No history, no duplicates check, no webhooks. 5–10 seconds. API: POST /v1/evaluate.

Permission read · read-only

ParameterType
textstringThe message as free text: an email body, a chat message, a transcript…
emailobject{ from, subject, text, html } — an email; from is "Jane Doe <jane@example.com>" or { name, email }
fieldsobjectForm fields exactly as received — no mapping needed
channelstringemail, form, chat, … Inferred when omitted
profileIdstringProfile to score with (its active version). Default: the workspace's default profile
profileobjectA whole profile document instead of a stored profile

Give at least one of text, email, fields.

submit_lead

Send a message through the full pipeline and wait up to 30 seconds for the result: junk filter, extraction, duplicate merging, scoring, and webhooks. Returns the message with its leads and a one-line summary per lead. If processing takes longer, the status is processing — check with get_processing_status. API: POST /v1/inbounds?wait=true.

Permission write · changes data

ParameterType
text, email, fields, channelThe message, as in evaluate_lead
sourceIdstringSource to file it under. Default: the workspace's API source
profileIdstringScore with this profile instead of the source's
externalIdstringYour ID for the message; sending it again returns the same message without processing it twice
metadataobjectYour key–values (strings), copied to the leads — e.g. a CRM ID

get_lead

One lead: contact, request summary, location with distance, extracted fields, score and tier, and every criterion's answer with the quoted evidence. API: GET /v1/leads/{id}.

Permission read · read-only

ParameterType
idstringlead_… (required)
historybooleanAlso return earlier evaluations (after reprocessing or a profile change)

search_leads

Leads, newest first, as compact items: ID, tier, score, summary, contact, outcome, state, date. API: GET /v1/leads.

Permission read · read-only

ParameterType
tierstringe.g. hot, warm, cold, disqualified, unscored
min_scorenumber0–100
source_idstringOnly leads from this source
contact_idstringOnly leads of this person
outcomestringwon, lost, no_response, disqualified, other, or none (no outcome yet)
statestringactive or archived
limit, starting_afterPaging

record_outcome

Record what happened to a lead; replaces an earlier outcome. Outcomes are how Leadveyor learns which leads were really good. API: POST /v1/leads/{id}/outcome, or DELETE with clear.

Permission write · changes data, idempotent

ParameterType
idstringlead_… (required)
statusstringwon, lost, no_response, disqualified, other
amountnumberDeal value
currencystringISO 4217, e.g. AUD. Default: the workspace currency
reasonstringWhy — especially for lost
occurredAtstringWhen it happened (ISO 8601). Default: now
clearbooleanRemove the outcome instead (the deal was reopened)

Messages and events

list_inbounds

Messages received, newest first: status, classification (lead / junk / not_lead), junk category and reason, leads found, error. API: GET /v1/inbounds.

Permission read · read-only

ParameterType
statusstringreceived, processing, processed, failed
classificationstringlead, junk, not_lead
sourceIdstringOnly messages from this source
limit, starting_afterPaging

get_processing_status

One message with its normalized content and every processing run: steps, timings, errors and AI cost. Use it after submit_lead or reprocess_inbound. API: GET /v1/inbounds/{id}.

Permission read · read-only — parameter id (inb_…).

reprocess_inbound

Process a message again — for example, it was wrongly marked junk, or you want it scored with another profile. Returns a job; the result appears in get_processing_status. API: POST /v1/inbounds/{id}/reprocess.

Permission write · changes data

ParameterType
idstringinb_… (required)
notJunkbooleanSkip the junk filter
profileIdstringScore with this profile

list_events

What changed in the last 30 days, newest first: lead.created, lead.scored, lead.updated, lead.outcome_recorded, inbound.junk, inbound.failed. The same events webhooks deliver. API: GET /v1/events.

Permission read · read-only

ParameterType
typestringExact type, or a prefix like lead.*
limit, starting_afterPaging

manage_contacts

People who sent leads, matched by email or phone, with their lead count and won / lost totals. API: Contacts.

Permission read for list, get, leads; write for update · changes data

ParameterType
actionstringlist, get, leads (the person's leads), update (required)
idstringctc_… — for get, leads, update
email, phonestringlist filters; phone in any format
vip, blockedbooleanlist filters, or the new values for update
name, company, metadataNew values for update
limit, starting_afterPaging

Profiles

A profile says what to extract and how to score. Changes go into a draft; scoring keeps using the active version until the draft is published. The usual loop is get_profile → update_profile_draft → test_profile → publish_profile. A new profile usually starts from a template (list_templates → create_profile with templateId) or from a description (generate_profile).

list_templates

Built-in profile templates for common businesses — plumbing, electrical, heating and air conditioning, roofing, renovation, cleaning, landscaping, catering and events, professional services, B2B software, any local service — with their variables (service area, minimum budget, guest count…) and criteria. API: GET /v1/templates.

Permission read · read-only

ParameterType
idstringReturn one template with its full document
categorystringtrades, home_services, events, professional_services, b2b or general

list_profiles

Profiles of the workspace: name, default or not, active version, latest version, whether there is a draft. API: GET /v1/profiles.

Permission read · read-only — parameters limit, starting_after.

get_profile

A profile with its active document and its draft. API: GET /v1/profiles/{id} and its versions.

Permission read · read-only

ParameterType
idstringprof_… (required)
versionnumberReturn this published version instead
versionsbooleanList the version history (number, date, name)

create_profile

Create a profile from a template or from a whole document. It is saved as a draft unless publish is true. API: POST /v1/profiles.

Permission write · changes data

ParameterType
templateIdstringTemplate from list_templates, e.g. plumbing
variablesobjectTemplate variables, e.g. { "service_radius_km": 25 }; missing ones use the defaults
namestringProfile name (with templateId); defaults to the template's
documentobjectInstead of templateId: the whole profile document — format in resource leadveyor://docs/profile-format
publishbooleanPublish it as version 1 right away

Pass either templateId or document.

generate_profile

Draft a whole profile from a plain-words description of the business and its best leads, optionally starting from a template. It is saved as the draft of a new profile — not published. The result lists the criteria, the assumptions the AI made and anything left out as invalid. Takes 10–30 seconds and costs about $0.02. API: POST /v1/profiles/generate.

Permission write · changes data

ParameterType
briefstringThe business and what a good lead is: services, area, best customers, what you don't do (required)
namestringProfile name; by default the AI names it
templateIdstringStart from this template and adapt it
variablesobjectTemplate variables, with templateId

update_profile_draft

Edit the draft. If there is none, it starts from the active version. Send a whole document, or change parts. API: PUT, PATCH or DELETE /v1/profiles/{id}/draft.

Permission write · changes data

ParameterType
idstringprof_… (required)
documentobjectReplace the whole draft
setobjectReplace top-level parts: name, brief, scoring, tiers, junk, dimensions
upsertCriteriaarrayAdd criteria, or replace them by id
removeCriteriaarrayCriterion IDs to remove
upsertFieldsarrayAdd extract fields, or replace them by key
removeFieldsarrayField keys to remove
discardbooleanThrow the draft away

The whole result is validated; every wrong field is listed at once.

generate_criterion

Turn a description in plain words into a criterion: question, guidance for the model, levels with points. Returns the criterion only — add it with update_profile_draft (upsertCriteria). Uses AI, about 7 seconds. API: POST /v1/profiles/criteria/generate.

Permission write · read-only (stores nothing)

ParameterType
descriptionstringWhat to look for, e.g. "Weddings are our best jobs; engagement parties are good; anything else is average" (required)
kindstringgraded (levels with points, default), escalate (straight to the top tier when met), disqualify (rejected when met)
profileobjectThe profile being edited — its dimensions, scale and brief are taken into account

test_profile

Dry run: score up to 10 sample messages with a profile and show, for each, the classification, tier, score and every criterion's answer. Uses the profile's draft (or the active version if there is no draft), or a document you pass. Nothing is stored. API: POST /v1/evaluate, once per message.

Permission read · read-only

ParameterType
idstringprof_…
documentobjectA profile document instead of id
messagesarray1–10 items, each { text } (required)

publish_profile

Publish the draft as a new active version. Every new lead is scored with it. The tool asks the model to confirm with you first. API: POST /v1/profiles/{id}/publish.

Permission write · can't be undone — parameter id.

rollback_profile

Make an earlier published version active again. API: POST /v1/profiles/{id}/activate.

Permission write · can't be undone — parameters id, version.

Setup

manage_sources

Where messages come from. An email source gives an address to forward mail to; a form source gives a URL to post forms to; an api source is for your own programs. API: Sources.

Permission read for list, get; write for the rest · can't be undone (delete)

ParameterType
actionstringlist, get, create, update, delete (required)
idstringsrc_… — for get, update, delete
typestringcreate: api, email, form
namestringDisplay name
profileIdstringProfile that scores this source's messages (null = workspace default)
statusstringupdate: active or paused
redirectUrlstringform: page to send people to after a classic HTML form submit

manage_destinations

Webhook destinations: where Leadveyor delivers signed events. API: Destinations.

Permission read for list, get, deliveries; write for the rest · can't be undone (delete)

ParameterType
actionstringlist, get, create, update, delete, test, deliveries, retry (required)
idstringdst_… — for everything except list and create
urlstringReceiver URL (HTTPS) — required for create
namestringDisplay name
eventsarrayEvent types or prefixes; default lead.scored
filterobjectSend only matching events, e.g. { "field": "evaluation.tier", "op": "in", "value": ["hot", "warm"] }
statusstringupdate: active re-enables a disabled destination, disabled stops it
deliveryIdstringretry: the delivery to send again

create returns the signing secret once. test sends a destination.test event; deliveries shows the delivery log with status, attempts and the receiver's response.

manage_workspaces

Workspaces — one per business. API: Workspaces.

Permission read for list, get; admin for create, update · changes data

ParameterType
actionstringlist, get, create, update (required)
idstringws_… — for get, update
namestringRequired for create
businessContextstringWhat the business does, its services and area. The AI reads it for every message
locationobject{ address, lat, lng } — origin for distance and drive time
localeobject{ language, timezone, currency }
businessHoursobject{ mon: { open: "08:00", close: "17:00" }, …, sun: null }
retentionDaysnumber7–365
defaultProfileIdstringupdate: a published profile used when a source doesn't name one

Resources

Resources are documents the assistant can read for context.

URIContent
leadveyor://docs/profile-formatHow a profile is written: extract fields, criteria types, conditions, levels and points, tiers, junk rules (Markdown)
leadveyor://schema/profileJSON Schema of a profile document, with field descriptions — the exact rules create_profile and update_profile_draft validate against
leadveyor://templates/{id}One built-in template with its variables and document (JSON); the list of templates is in the client's resource list

Was this page helpful?