MCP server

Leadveyor has a built-in Model Context Protocol (MCP) server. Connect it to an AI assistant — Claude, Cursor, VS Code, your own agent — and work with your leads in plain words: "show me this week's hot leads", "why did this one score 35?", "add a criterion for weddings and test it on these three emails".

At a glance

SettingValue
Server URLhttps://core.leadveyor.com/mcp
TransportStreamable HTTP (POST), stateless, JSON responses
AuthenticationAuthorization: Bearer <API key> — the same API keys as the REST API
Tools23 tools for leads, messages, contacts, profiles and templates, sources, webhooks and workspaces
Resourcesleadveyor://docs/profile-format (how a profile is written), leadveyor://schema/profile (its JSON Schema), leadveyor://templates/{id} (built-in templates)

What an assistant can do

  • Review leads — search by tier, score, source, contact or outcome; open a lead and read every criterion's answer with the quoted evidence from the message.
  • Try a message — score any text, email or form without storing it, with a stored profile or a profile document written on the fly.
  • Process messages — send a message through the full pipeline (junk filter, extraction, duplicates, scoring, webhooks) and get the result.
  • Check the queue — see what arrived, what was filtered as junk and why, what failed; process a message again if it was wrongly marked junk.
  • Record outcomes — mark leads won, lost or no response, with the deal value and the reason.
  • Tune scoring — start a profile from a template for your kind of business or from a description in your own words, read a profile, write new criteria from a description, edit the draft, test it on sample messages, publish it, roll back to an earlier version.
  • Set things up — create email and form sources, webhook destinations, workspaces, and see the webhook delivery log.

How it works

The MCP server is part of the Leadveyor API, not a separate service. Each tool call is translated into one or more REST API requests made with your key:

  1. The assistant connects to https://core.leadveyor.com/mcp with your API key. A missing, invalid or revoked key gets 401 Unauthorized before any tool runs.
  2. It lists the tools. Each tool has a description written for the model, a JSON Schema for its input, and hints: read-only, or changes data, or can't be undone.
  3. When the model calls a tool, Leadveyor runs the matching API operation with the same key, the same permission checks and the same validation as a direct API call.
  4. The result comes back as a short summary for the model (for a lead: lead_… — hot, 82/100 · Jane Doe · Kitchen renovation, budget $25k) plus the full JSON object in structuredContent.

Because of this, anything the MCP server does, the key could do through the API — and nothing more. A key with read permission can't change anything through MCP either.

The server keeps no session between calls: every request carries the key, and every tool call stands on its own. There is nothing to configure on the Leadveyor side.

Permissions

Give the assistant a key with the lowest permission it needs (how to create one):

Key permissionWhat the assistant can do
readSearch and read leads, messages, contacts, events, profiles, templates, sources and webhooks; try messages with evaluate_lead and test_profile (nothing is stored).
writeAlso process messages, record outcomes, edit contacts, create and edit profiles, publish them, write criteria with AI, manage sources and webhooks.
adminAlso create and change workspaces.

API keys themselves can't be created or revoked through MCP, and leads can't be deleted.

Test keys (lv_test_…) work too: everything the assistant creates with a test key is kept apart from live data. Use one while you try MCP out.

Workspaces

A workspace key (created for one workspace) needs nothing else — every tool works in that workspace.

An account-wide key reaches every workspace of the account, so the assistant has to say which one. Either:

  • set the Leadveyor-Workspace: ws_… header in the client configuration (the default for every call), or
  • let the assistant pass workspaceId — every tool has this optional parameter. It can find the IDs with manage_workspaces (action: "list").

Confirmations

Every tool carries the standard MCP hints, and clients use them to decide when to ask you first:

HintTools
Read-onlyevaluate_lead, get_lead, search_leads, list_inbounds, get_processing_status, list_events, list_profiles, get_profile, list_templates, generate_criterion, test_profile
Changes datasubmit_lead, record_outcome (idempotent), reprocess_inbound, manage_contacts, create_profile, generate_profile, update_profile_draft, manage_workspaces
Can't be undonepublish_profile, rollback_profile, manage_sources, manage_destinations (they can delete or switch what is live)

Publishing a profile changes how every new lead is scored, so the tool description also tells the model to confirm with you first.

Errors

When a call fails, the tool returns an error result (isError: true) with the HTTP status, the error type, the field at fault and the same message the API gives:

403 permission_error: This action requires the 'write' permission.
404 not_found_error: No lead 'lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr'.
400 invalid_request_error: criteria.2.question: Profile is invalid: criteria.2.question: … (+1 more)
[{"path":"criteria.2.question","message":"…"},{"path":"tiers","message":"…"}]

The model reads the message, fixes its input and tries again — for a profile, the result lists every wrong field at once. See Errors for all error types.

Lists and paging

List tools (search_leads, list_inbounds, list_events, list_profiles, and the list action of the manage_* tools) return compact items — the key fields only — plus has_more and next_cursor. To get the next page, the assistant passes next_cursor as starting_after. Up to 100 items per page (limit), 20 by default. The full object comes from the matching get tool.

Costs and limits

Tools that run the AI pipeline — evaluate_lead, submit_lead, test_profile (once per sample message), generate_criterion and generate_profile — cost the same as the matching API calls. Everything else only reads or writes data.

submit_lead waits up to 30 seconds for the result. If processing takes longer, it returns the message ID and status processing; the assistant checks back with get_processing_status.

Security

  • Treat the key in your MCP client configuration like a password. Prefer a workspace key with the lowest permission, and a separate key per assistant, so you can see when each was last used and revoke one without touching the others.
  • Message content — emails and form fields — is data written by your customers. Assistants read it through the tools; a well-behaved client treats it as data, not instructions. Destructive tools are marked so that the client asks you before running them.
  • Revoking the key in the console cuts the assistant off immediately.

Next steps

Was this page helpful?