Connecting AI Agents to the AboveBoardPros Lead Pipeline via MCP

AI Agents Can Now Submit Leads Directly

Home improvement lead generation is changing. AI agents — whether answering inbound calls, running outbound SMS campaigns, or powering chat widgets — are increasingly the first touchpoint between a homeowner and a contractor. Until now, wiring those agents into a lead management system meant building custom webhooks or managing fragile API integrations.

AboveBoardPros now exposes a Model Context Protocol (MCP) endpoint that any AI agent can call natively. The agent declares its intent, our server routes it to the right tool, and the lead enters our verified pipeline — all without the agent needing to know anything about our internal data model.

What Is MCP?

MCP is an open standard developed by Anthropic for connecting AI agents to external systems. It works like a function registry: a server publishes a list of tools with typed schemas, and any MCP-compatible agent can discover and call those tools using a simple JSON-RPC protocol over HTTP.

If you've used tool use / function calling in the OpenAI or Anthropic APIs, MCP is the same concept extended to a client-server transport. An agent running on Vapi, a Claude workflow, a custom LangChain agent — all can call an MCP endpoint the same way.

The Endpoint

POST https://aboveboardpros.com/api/mcp
Authorization: Bearer <your-api-key>
Content-Type: application/json

A GET to the same URL returns the full tool manifest — useful for debugging or discovery without needing an MCP client library.

Authentication uses the same API key system as our REST ingest endpoint. Pass it as a Bearer token in the Authorization header, or as the x-source-api-key header if your agent platform doesn't support custom auth headers.

Available Tools

submit_lead

Submits a home improvement lead. Returns a lead_id on success, or a structured error your agent can act on.

Required fields:

Field	Type	Notes
first_name	string
last_name	string
phone	string	Digits only, min 10
email	string
zip_code	string	5-digit US zip
service	string	Use get_lead_spec for valid slugs

Agent compliance fields (strongly recommended):

Field	Type	Notes
agent_id	string	Your agent's unique identifier
agent_platform	string	e.g. "vapi", "bland", "openai", "custom"
session_id	string	Unique call or session ID from your platform
recording_url	URI	URL to session recording (voice agents)
explicit_consent_captured	boolean	true when consumer confirmed TCPA consent
consent_script_version	string	Version of the disclosure script used
consent_timestamp	datetime	ISO 8601 timestamp of when consent was given

Optional lead enrichment:

address, city, state, project_details, is_owner, external_id

get_lead_spec

Returns the live specification: all valid service slugs, accepted states, required and optional fields, and example payloads. Call this once at agent startup to cache the current service list.

TCPA Compliance for Agent Leads

Agent-generated leads are classified differently from web form leads in our audit trail. Web form leads use TrustedForm certificates and checkbox consent. Agent leads use consent_type: explicit — consent confirmed through the agent interaction itself.

For voice agents, the compliance record should include:

• The recording_url pointing to the full call recording
• explicit_consent_captured: true set only after the consumer verbally confirmed
• The consent_script_version of the disclosure script your agent read
• consent_timestamp matching the moment in the call when consent was given

For chat or workflow agents, the same fields apply — recording_url becomes a transcript URL or is omitted, and consent is confirmed through whatever explicit mechanism your agent uses (button tap, typed confirmation, etc.).

Our system stores all of this in the lead's metadata.tcpa block alongside a metadata.agent block containing your platform and session details. This gives both your compliance team and ours a complete, queryable audit trail.

Calling the Endpoint: JSON-RPC 2.0

MCP uses JSON-RPC 2.0 over HTTP. Here's the full exchange for a voice agent submitting a lead after a successful call:

Step 1 — Initialize (once per session)

POST /api/mcp
Authorization: Bearer sk_live_yourkey

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-voice-agent", "version": "1.0" }
  }
}

Step 2 — Submit the lead

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "submit_lead",
    "arguments": {
      "first_name": "Marcus",
      "last_name": "Webb",
      "phone": "5124019283",
      "email": "marcus@example.com",
      "zip_code": "73301",
      "service": "hvac-replacement",
      "project_details": "AC unit stopped working, house is 2,400 sq ft.",
      "is_owner": true,
      "agent_id": "agent_hvac_outbound_v2",
      "agent_platform": "vapi",
      "session_id": "call_7gHj3kLm9",
      "recording_url": "https://cdn.vapi.ai/recordings/call_7gHj3kLm9.mp3",
      "explicit_consent_captured": true,
      "consent_script_version": "tcpa-v3",
      "consent_timestamp": "2026-04-25T14:32:11Z"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"success\":true,\"lead_id\":\"a1b2c3d4-...\",\"message\":\"Lead received and accepted.\"}"
    }],
    "isError": false
  }
}

The isError: true path returns structured errors your agent can use to decide what to do next — retry, ask the consumer to confirm a field, or gracefully end the session.

Duplicate Handling

The system rejects leads with the same phone + email + service combination submitted within 30 days and returns a 409 mapped to isError: true in the tool response. Your agent should treat this as a non-retryable success — the lead is already in the pipeline.

Getting Started

Contact the AboveBoardPros partner team to receive your API key. Once you have it, send a GET to /api/mcp to confirm access and review the live tool manifest. Then point your agent at POST /api/mcp and start submitting.

AboveBoardPros handles everything after submission — routing to matched contractors, compliance checks, and lead lifecycle management — so your agent can stay focused on the conversation.