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
| Parameter | Type | |
|---|---|---|
text | string | The message as free text: an email body, a chat message, a transcript… |
email | object | { from, subject, text, html } — an email; from is "Jane Doe <jane@example.com>" or { name, email } |
fields | object | Form fields exactly as received — no mapping needed |
channel | string | email, form, chat, … Inferred when omitted |
profileId | string | Profile to score with (its active version). Default: the workspace's default profile |
profile | object | A 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
| Parameter | Type | |
|---|---|---|
text, email, fields, channel | The message, as in evaluate_lead | |
sourceId | string | Source to file it under. Default: the workspace's API source |
profileId | string | Score with this profile instead of the source's |
externalId | string | Your ID for the message; sending it again returns the same message without processing it twice |
metadata | object | Your 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
| Parameter | Type | |
|---|---|---|
id | string | lead_… (required) |
history | boolean | Also 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
| Parameter | Type | |
|---|---|---|
tier | string | e.g. hot, warm, cold, disqualified, unscored |
min_score | number | 0–100 |
source_id | string | Only leads from this source |
contact_id | string | Only leads of this person |
outcome | string | won, lost, no_response, disqualified, other, or none (no outcome yet) |
state | string | active or archived |
limit, starting_after | Paging |
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
| Parameter | Type | |
|---|---|---|
id | string | lead_… (required) |
status | string | won, lost, no_response, disqualified, other |
amount | number | Deal value |
currency | string | ISO 4217, e.g. AUD. Default: the workspace currency |
reason | string | Why — especially for lost |
occurredAt | string | When it happened (ISO 8601). Default: now |
clear | boolean | Remove 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
| Parameter | Type | |
|---|---|---|
status | string | received, processing, processed, failed |
classification | string | lead, junk, not_lead |
sourceId | string | Only messages from this source |
limit, starting_after | Paging |
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
| Parameter | Type | |
|---|---|---|
id | string | inb_… (required) |
notJunk | boolean | Skip the junk filter |
profileId | string | Score 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
| Parameter | Type | |
|---|---|---|
type | string | Exact type, or a prefix like lead.* |
limit, starting_after | Paging |
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
| Parameter | Type | |
|---|---|---|
action | string | list, get, leads (the person's leads), update (required) |
id | string | ctc_… — for get, leads, update |
email, phone | string | list filters; phone in any format |
vip, blocked | boolean | list filters, or the new values for update |
name, company, metadata | New values for update | |
limit, starting_after | Paging |
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
| Parameter | Type | |
|---|---|---|
id | string | Return one template with its full document |
category | string | trades, 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
| Parameter | Type | |
|---|---|---|
id | string | prof_… (required) |
version | number | Return this published version instead |
versions | boolean | List 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
| Parameter | Type | |
|---|---|---|
templateId | string | Template from list_templates, e.g. plumbing |
variables | object | Template variables, e.g. { "service_radius_km": 25 }; missing ones use the defaults |
name | string | Profile name (with templateId); defaults to the template's |
document | object | Instead of templateId: the whole profile document — format in resource leadveyor://docs/profile-format |
publish | boolean | Publish 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
| Parameter | Type | |
|---|---|---|
brief | string | The business and what a good lead is: services, area, best customers, what you don't do (required) |
name | string | Profile name; by default the AI names it |
templateId | string | Start from this template and adapt it |
variables | object | Template 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
| Parameter | Type | |
|---|---|---|
id | string | prof_… (required) |
document | object | Replace the whole draft |
set | object | Replace top-level parts: name, brief, scoring, tiers, junk, dimensions |
upsertCriteria | array | Add criteria, or replace them by id |
removeCriteria | array | Criterion IDs to remove |
upsertFields | array | Add extract fields, or replace them by key |
removeFields | array | Field keys to remove |
discard | boolean | Throw 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)
| Parameter | Type | |
|---|---|---|
description | string | What to look for, e.g. "Weddings are our best jobs; engagement parties are good; anything else is average" (required) |
kind | string | graded (levels with points, default), escalate (straight to the top tier when met), disqualify (rejected when met) |
profile | object | The 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
| Parameter | Type | |
|---|---|---|
id | string | prof_… |
document | object | A profile document instead of id |
messages | array | 1–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)
| Parameter | Type | |
|---|---|---|
action | string | list, get, create, update, delete (required) |
id | string | src_… — for get, update, delete |
type | string | create: api, email, form |
name | string | Display name |
profileId | string | Profile that scores this source's messages (null = workspace default) |
status | string | update: active or paused |
redirectUrl | string | form: 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)
| Parameter | Type | |
|---|---|---|
action | string | list, get, create, update, delete, test, deliveries, retry (required) |
id | string | dst_… — for everything except list and create |
url | string | Receiver URL (HTTPS) — required for create |
name | string | Display name |
events | array | Event types or prefixes; default lead.scored |
filter | object | Send only matching events, e.g. { "field": "evaluation.tier", "op": "in", "value": ["hot", "warm"] } |
status | string | update: active re-enables a disabled destination, disabled stops it |
deliveryId | string | retry: 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
| Parameter | Type | |
|---|---|---|
action | string | list, get, create, update (required) |
id | string | ws_… — for get, update |
name | string | Required for create |
businessContext | string | What the business does, its services and area. The AI reads it for every message |
location | object | { address, lat, lng } — origin for distance and drive time |
locale | object | { language, timezone, currency } |
businessHours | object | { mon: { open: "08:00", close: "17:00" }, …, sun: null } |
retentionDays | number | 7–365 |
defaultProfileId | string | update: a published profile used when a source doesn't name one |
Resources
Resources are documents the assistant can read for context.
| URI | Content |
|---|---|
leadveyor://docs/profile-format | How a profile is written: extract fields, criteria types, conditions, levels and points, tiers, junk rules (Markdown) |
leadveyor://schema/profile | JSON 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 |