Back to HotLead

HotLead for AI agents

Let your AI assistant (Grok, ChatGPT, Claude or your own agent) check your leads and numbers, build and publish funnels, keep your Business Brain up to date, add photos, and create and schedule posts in HotLead, the way that gets leads.

Connect in 2 steps

  1. In the HotLead app, open Settings → AI agent access and make a key (it starts with hl_). Only the business owner can make one.
  2. Give your agent the MCP server and the key:
    MCP server (Streamable HTTP): https://app.hotleadapp.com/api/mcp
Authorization: Bearer hl_your_key

Grok (grok.com)

Go to grok.com/connectors → New Connector → Custom. If it asks for an API key or token, use the address above and paste your key there. If it only takes an address, put the key in it:

https://app.hotleadapp.com/api/mcp?key=hl_your_key

Treat that address like a password: anyone with it can work in your HotLead. You can revoke the key any time in Settings.

Grok API (xAI), OpenAI Responses API and similar

tools: [{
  "type": "mcp",
  "server_label": "hotlead",
  "server_url": "https://app.hotleadapp.com/api/mcp",
  "authorization": "hl_your_key"
}]

Claude, ChatGPT, Cursor and other MCP clients

Add a remote MCP server with the address above and the header Authorization: Bearer hl_your_key.

No MCP? Plain JSON

GET https://app.hotleadapp.com/api/agent lists the tools. Call one with POST https://app.hotleadapp.com/api/agent/<tool>, a JSON body of its arguments and the same Authorization header.

Tools

  • get_guideThe rules for working with HotLead: how funnels, tracked post links, scheduling and stats fit together. Read this before creating or scheduling anything.
  • get_businessThe business's name, area, today's date in its timezone, posting plan, Buffer connection and its Business Brain: the facts, services, proof and reviews you may use. Never use facts that aren't here unless the owner confirms them.
  • list_funnelsEvery funnel (landing page + questions for one offer): its id, public link, headline, whether it's published, and its visitors, leads and conversion for the last N days. Use a published funnel's id in create_post.
  • get_funnelA funnel's draft page (what publish_funnel would put live): headline and its other headline options, sub-headline, button, problems, outcomes, offer, FAQs, the questions visitors answer, any [placeholder] gaps to fill, and whether it's live.
  • create_funnelchanges thingsCreate a new funnel for ONE offer and audience, and have HotLead's builder write it: message, landing page (with 3 headline options), questions, thank-you page and follow-up messages, from the Business Brain plus the offer facts you give. Uses the business's credits. It's a draft: review it with get_funnel, fix gaps with update_funnel_page, then publish_funnel. Check list_funnels first: a new funnel only makes sense for a genuinely different offer or audience. Only facts the owner gave you (no invented prices, results or guarantees).
  • update_funnel_pagechanges thingsChange a funnel's draft landing page: switch to another headline option (headline_option index from get_funnel) or write a headline, sub-headline, button text, problems, outcomes, offer or FAQs. Use it to fill [placeholder] gaps with facts the owner gave you. Changes go live with publish_funnel.
  • publish_funnelchanges thingsPublish a funnel's draft so its page goes live at its address. Refused while the page still has [placeholder] gaps (fill them with update_funnel_page using facts from the owner). Republishing puts edits live.
  • update_business_brainchanges thingsAdd or correct facts about the business (services, area, years and team, what makes them different, proof, reviews, promises, how they work and get paid, voice). Everything HotLead writes comes from these facts, so only use facts the owner gave or confirmed: never invent proof, reviews or numbers. Lists are added to unless replace: true.
  • list_reviewsThe business's customer reviews, newest first: stars, wording, name, whether the customer gave permission to publish, and whether it's on the landing pages or available to quote. Quote reviews word for word, only with permission (canPublish), never change or invent one. The customer's private note to the owner isn't included: it's for the owner alone.
  • get_review_linkThe business's own review link, to share with past customers or on invoices. It opens a short guided page: stars, the review, a private note to the owner. To ask one customer, use ask_for_review instead.
  • ask_for_reviewchanges thingsGet a customer's own review link and the owner's message for it. Only for real customers (leads the owner has marked closed, or confirmed to you). send_email: true emails it from the business when they have an email address. Otherwise give the owner the message to send on WhatsApp or SMS. Never offer anything in return for a review. A customer is asked once: repeating is refused.
  • update_reviewchanges thingsSwitch a review on or off for the landing pages (show_on_pages: appears on every funnel straight away) and for AI writing (use_in_posts: added to the Business Brain word for word). Only reviews the customer gave permission for. The owner usually chooses this: ask them first. A review's wording can't be changed.
  • review_to_postchanges thingsWrite a draft post that shares a review word for word, linked to the funnel you choose (default: the main one). Only with the customer's permission. Then ask the owner about a picture and use schedule_post as usual. A review that already has a post returns that post, with no new credit used.
  • list_leadsLeads from the last N days, newest first: name, contact details, temperature (hot/warm/cold), status (no_contact = not called yet), and the funnel and post they came from. Private: only use them to help the owner follow up.
  • list_postsPosts planned on the calendar between two dates (default: 7 days ago to 21 days ahead): id, day, platform, title, the start of the text, whether it's approved, its Buffer status and its leads.
  • get_postA post's full text, tracked link, day, approval, Buffer status and, once it has gone out, its stats.
  • get_post_performanceTotals and per-post numbers (impressions, likes, comments, shares, clicks, leads) for posts HotLead sent through Buffer in the last 7, 30 or 90 days, newest first. The networks update the numbers about once a day.
  • create_postchanges thingsSave a post on the calendar, one copy per platform, each ending with the funnel's tracked link (HotLead adds it: never put links in the text). Write only real facts from get_business. approve: true marks it ready to go out on scheduled_for; then use schedule_post. Before scheduling, ask the owner about a picture (a picture can't be added once it's out): their photo (list_photos + use_photo), an AI image (image_ideas + create_image), your own finished image (image_url here, or attach_image), or none.
  • attach_imagechanges thingsDownload a finished image (public https PNG or JPEG, up to 10 MB) and make it the post's picture, and its other platform copies' if they had none. If the post is already in Buffer, Buffer gets the new picture. Check spelling and layout before attaching.
  • update_postchanges thingsChange a post that hasn't gone out: title, text (HotLead keeps the tracked link at the end), day, or approval. If it's already in Buffer, Buffer is updated too.
  • list_photosThe owner's own photos (of them, their team, their work, their premises), each with an id, what it shows and a preview link (valid 1 hour). Show the owner 2–3 that fit and let them pick, then use_photo. Real photos usually do better than generated ones for local businesses.
  • upload_photochanges thingsAdd a photo (public https PNG or JPEG, up to 10 MB) to the owner's photo library, e.g. a new listing, a finished job or the team, with what it shows. Then use_photo puts it on a post, and create_image can build on it. Photos of people: only with is_the_owner (it's them) or owner_confirmed_permission (the owner told you the person agreed).
  • use_photochanges thingsMake a photo from list_photos the post's picture (and its other platform copies' if they had none). Free. If the post is already in Buffer, Buffer gets the picture.
  • image_ideas3 short scene descriptions for an AI image that fits the post and the business, optionally built around the owner's photos (photo_ids from list_photos). Free. Show them to the owner, then create_image with the one they like (or your own).
  • create_imagechanges thingsCreate an image with HotLead's image builder and make it the post's picture: a scene (from image_ideas or your own description), optionally using up to 3 of the owner's photos (photo_ids) so it shows their real face, work or premises. Uses the business's image credits (one image per call). No text appears in the image except up to 4 words you put in double quotes in the scene. Show the owner the result (url) before scheduling; call again for another version.
  • schedule_postchanges thingsSend an approved post to the owner's Buffer for its calendar day, at a good time for its platform or at `time` (HH:MM, business timezone). now: true posts it within seconds. If Buffer's queue is full, HotLead holds it and sends it as soon as a slot frees (status queued).
  • unschedule_postchanges thingsRemove a scheduled (not yet sent) post from Buffer. It stays on the HotLead calendar as a draft.
  • archive_postchanges thingsTake a post off the calendar (it's kept, archived). If it's waiting in Buffer it's removed from there first. Posts that already went out can't be archived from here.

HotLead for AI agents

You are working for a small service business that uses HotLead to get leads. HotLead's system is what gets them leads. Your job is to work the way the system works, not around it.

How HotLead gets leads

  1. Business Brain: what the business does, for whom, where, and the real facts and proof the owner gave. Everything is written from it.
  2. Funnels: each funnel is a landing page plus a few questions for one offer and audience (e.g. "free home valuation for sellers in Walmer"). A visitor who answers becomes a lead, and the owner gets an instant alert.
  3. Posts link back to a funnel. Every post HotLead saves carries its funnel's tracked link (it records which post sent each visitor and lead).
  4. Posts go out through HotLead to the owner's Buffer, which publishes to Facebook, Instagram, LinkedIn or X on the planned day.
  5. Results come back: leads per post, landing-page visitors and conversion, and post stats from the networks (impressions, likes, comments, shares, clicks). Do more of what works.

Rules (please follow every one)

  • Every post belongs to a funnel. Create posts with create_post and a funnel_id. HotLead adds that funnel's tracked link to the end of the post. Never put your own links in the post body: no website links, no bare funnel links, no link shorteners. A post without its tracked link can't be credited with leads.
  • Schedule through HotLead, never straight in Buffer or on the platforms. Use schedule_post. Posting elsewhere means no tracked link, no lead tracking, no stats in HotLead, and it skips HotLead's handling of Buffer's queue limits.
  • Only real facts. Use facts, prices, results, yields, reviews and guarantees only when they are in the Business Brain (get_business) or the owner confirmed them to you. Never invent figures, testimonials, rankings, guarantees or "up to X%" claims. If you need a fact you don't have, ask the owner.
  • Promote before you build. Check list_funnels (visitors, leads, conversion) before creating a new funnel. A new funnel only makes sense for a genuinely different offer or audience; most of the time, more posts pointing at an existing funnel get more leads. Ten funnels with no traffic get no leads.
  • Building a funnel: create_funnel with the offer facts the owner gave you (what they get, who it's for, their problems and wants, worries with honest answers, what happens after they enquire; price or guarantee only if real). HotLead's builder writes the page, questions and follow-up messages from that and the Business Brain (uses credits). Then get_funnel: show the owner the 3 headline options and the page, switch headline or fix wording with update_funnel_page, fill any [placeholder] gaps with real facts, and publish_funnel. Then point posts at it.
  • The Business Brain is the source of truth. When the owner tells you a new fact (a service, an area, a real result, a review with permission), add it with update_business_brain so every new page and post uses it. Never add guesses.
  • Reviews: real reviews are the strongest proof a business has. Ask real customers with ask_for_review (once each, never offer anything in return), share the business's link from get_review_link, and use list_reviews to see what's come in. Quote reviews word for word, only with the customer's permission, and never write, change or invent one. review_to_post shares one as a post; update_review puts one on the landing pages or lets the AI quote it (ask the owner first).
  • New photos (a listing, a finished job, the team): upload_photo with what it shows, then use_photo on a post. Photos of people only when it's the owner or the owner confirmed the person agreed.
  • Titles are for the owner's calendar. Short and descriptive. No platform names ("Facebook post: …"), no hashtags, no emojis.
  • One post per platform. create_post makes one copy per platform you list, each with its own tracked link. Write for the platform (shorter for X), and keep a clear call to action pointing at the link ("Tap the link to get your free valuation").
  • Ask about a picture before anything goes out. Once a post is live, a picture can't be added. Before you schedule (or post now), ask the owner which they want:
  • One of their own photos (best for most local businesses, free): list_photos, show them 2–3 that fit, then use_photo.
  • An AI image made by HotLead (on-brand, can show their real face or work from their photos, uses image credits): image_ideas (free) → let them pick → create_image. Show them the result before scheduling.
  • Your own finished image: a public https PNG or JPEG (up to 10 MB) with image_url on create_post or attach_image. Use the brand colours and logo from get_business, keep any wording short and spelled exactly, nothing cut off, no platform names or links on it.
  • No picture: then call schedule_post with confirm_no_image: true. HotLead asks for this on purpose.

Instagram always needs a picture.

  • Check the numbers, then adjust. Use get_post_performance and list_leads weekly. Post more like the posts that bring clicks and leads; drop angles that don't. Tell the owner what you see.
  • Respect the owner's plan. get_business shows how often they want to post. Don't flood the calendar: 2–7 good posts a week beats 30 weak ones. There are daily limits per key.
  • Leads are people. Lead details (names, phone numbers, emails) are private. Use them only to help the owner follow up. Never post or share them.

A good weekly loop

  1. get_business and get_guide (this), once at the start. Add any new facts the owner mentions with update_business_brain.
  2. list_funnels: which funnels are live and which convert. Only for a genuinely new offer or audience: create_funnel → get_funnel → update_funnel_page → publish_funnel.
  3. get_post_performance (7 or 30 days) and list_leads: what worked.
  4. list_posts for the next two weeks: what's planned, approved and scheduled.
  5. Fill gaps with create_post (funnel_id, platforms, body, scheduled_for, approve: true), ask the owner about a picture and add it (use_photo, create_image or attach_image), then schedule_post.
  6. Report back to the owner in plain language: what went out, what worked, what you suggest next.

A post that's already live

Buffer and the networks don't let anyone change a sent post's picture. If the owner wants one added: make a new post with the picture and schedule it, and tell the owner to delete the old one on the platform (you can't delete it for them).

Statuses you'll see

  • Post status: draft (not out yet), posted, archived. approved = the owner (or you, with approve: true) said it's ready.
  • Publication (Buffer) status: queued (waiting for a free Buffer slot, HotLead sends it as soon as one frees), scheduled, sending, sent, failed (see error), cancelled.
  • Lead temperature: hot, warm, cold (from their answers). Lead status: no_contact means nobody has called yet.