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
| Setting | Value |
|---|---|
| Server URL | https://core.leadveyor.com/mcp |
| Transport | Streamable HTTP (POST), stateless, JSON responses |
| Authentication | Authorization: Bearer <API key> — the same API keys as the REST API |
| Tools | 23 tools for leads, messages, contacts, profiles and templates, sources, webhooks and workspaces |
| Resources | leadveyor://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:
- The assistant connects to
https://core.leadveyor.com/mcpwith your API key. A missing, invalid or revoked key gets401 Unauthorizedbefore any tool runs. - 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.
- 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.
- 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 instructuredContent.
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 permission | What the assistant can do |
|---|---|
read | Search and read leads, messages, contacts, events, profiles, templates, sources and webhooks; try messages with evaluate_lead and test_profile (nothing is stored). |
write | Also process messages, record outcomes, edit contacts, create and edit profiles, publish them, write criteria with AI, manage sources and webhooks. |
admin | Also 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 withmanage_workspaces(action: "list").
Confirmations
Every tool carries the standard MCP hints, and clients use them to decide when to ask you first:
| Hint | Tools |
|---|---|
| Read-only | evaluate_lead, get_lead, search_leads, list_inbounds, get_processing_status, list_events, list_profiles, get_profile, list_templates, generate_criterion, test_profile |
| Changes data | submit_lead, record_outcome (idempotent), reprocess_inbound, manage_contacts, create_profile, generate_profile, update_profile_draft, manage_workspaces |
| Can't be undone | publish_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
- Connect a client — Claude Code, Claude Desktop, Cursor, VS Code, the Claude API and your own agents.
- Tool reference — every tool and its parameters.
- Example workflows — what to ask, and which tools the assistant uses.