`leads.add`

Add one company/contact. Pass analysis with research you already did and the message is written from it instead of a fresh crawl.


Endpoint	`POST /mcp/mutate`
Scope	`write`
Sandbox key	allowed
Extra entitlement	none
MCP tools	`selda_add_lead`
Convex function	`mcpQueries:addLead`

A free sandbox key may call it.

Arguments

Argument	Type	Required	Notes
`projectId`	`string`	required
`firstName`	`string`	optional
`lastName`	`string`	optional
`email`	`string`	optional
`company`	`string`	optional
`companyDomain`	`string`	optional
`jobTitle`	`string`	optional
`linkedinUrl`	`string`	optional
`phone`	`string`	optional
`notes`	`string`	optional
`analysis`	`string`	optional
`outreachAngle`	`string`	optional	The opening the operator already chose, and why they chose the company. Both are read by the engine (`operatorAngle` governs the opening, `whyGoodLead` feeds research and the fit call). They were wired into the engine on 17.8.2026 and had no door on this mutation for an hour, which is the same shape of gap the analysis had for a week: read by a writer, unreachable by the caller.
`whyGoodLead`	`string`	optional
`externalUrl`	`string`	optional
`source`	`string`	optional
`tags`	`string[]`	optional
`city`	`string`	optional
`country`	`string`	optional
`location`	`string`	optional
`customFields`	`any`	optional

What Selda fills in

You never send these. The HTTP layer overwrites them from the API key, which is what keeps one organisation’s data out of another’s reach.

Argument	Filled in from
`orgId`	your organisation, resolved from the API key

Example request

Required arguments only. Values in angle brackets are yours to fill in; the optional ones are in the table above.

curl -X POST https://api.selda.ai/mcp/mutate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "fn": "leads.add", "args": { "projectId": "<projectId>" } }'

{
  "fn": "leads.add",
  "args": {
    "projectId": "<projectId>"
  }
}

Example response

Every endpoint answers in the same envelope.

{
  "value": <the function's return value>,
  "request_id": "req_..."
}

The shape of value is not documented here. mcpQueries:addLead declares no returns validator, so there is nothing to derive it from, and a shape written out by hand here is a shape that goes stale without anything noticing. Call it once against a test key and read what comes back.

On failure the body is { "error": { "type", "code", "message", "request_id" }, "request_id" } and request_id is echoed in the X-Request-Id header.

Generated from convex/lib/mcpRegistry.ts. Nothing in this reference sends: launchRun is in no registry and never will be, so a script can prepare a campaign completely and a person still presses send in the app.

mutateknowledge.set mutateleads.addAlias