Docs

MCP quickstart

Lovelio ships a Model Context Protocol server on each regional app domain at /api/mcp. Connect any MCP-aware client and run your recruiting desk with natural language. MCP is an open standard. Each client must still support Lovelio's HTTP transport, OAuth registration, HTTPS or loopback callbacks, and PKCE. Verify the actual client before a rollout.

Pick your region first

Every Lovelio workspace lives in exactly one region, and your API key and MCP connection only work on that region's domain:

  • https://us.lovelio.ai/api/mcp - Americas and rest of world
  • https://eu.lovelio.ai/api/mcp - UK, Ireland, and Europe
  • https://anz.lovelio.ai/api/mcp - Australia and New Zealand

Your region is the domain you sign in on, and your exact connect URL is shown on the Settings -> API keys page. The examples below use the US domain - swap in yours.

Before you connect

Sign in as a Lovelio workspace admin. Your MCP client opens a consent page where you choose the permissions to grant. REST scripts use API keys; MCP uses OAuth for both reads and writes. Do not paste a REST key into an MCP Authorization header.

For a Connect sandbox, use Open sandbox in the portal first, then connect your MCP client to the sandbox origin shown there with /api/mcp.

Install

Start with the server URL in a compatible OAuth-enabled MCP client:

https://us.lovelio.ai/api/mcp

Clients that take a JSON config block want this. Most use the mcpServers key; a few name the wrapper differently:

{
  "mcpServers": {
    "lovelio": {
      "type": "http",
      "url": "https://us.lovelio.ai/api/mcp"
    }
  }
}

Clients with a settings screen ask for the same URL under a heading like Connectors, Custom connector, or Add MCP server. Clients with a command line have their own add command - pass the URL and the HTTP transport.

The first call opens the Lovelio sign-in and consent page. Approve the permissions you need. Dynamically registered clients are unreviewed; the consent page says so. Your client receives OAuth tokens and refreshes them automatically.

Compatible clients discover the OAuth endpoints through this metadata:

API-key connection when OAuth is incompatible

MCP also accepts an existing Lovelio API key in Authorization: Bearer <key>. Create a dedicated key in your region's Settings > API page. Select only the permissions the agent needs. Put the key in your client's secure header settings, not in a chat message or repository.

{
  "mcpServers": {
    "lovelio": {
      "type": "http",
      "url": "https://us.lovelio.ai/api/mcp",
      "headers": { "Authorization": "Bearer <your-dedicated-Lovelio-key>" }
    }
  }
}

Use your workspace's region URL. An agency API key has agency-level record access; it does not impersonate a consultant. Its explicit scopes still filter tools and gate every V1 call. Key revocation and scope reductions apply on the next request. Unlike OAuth, a static key has no rotating refresh token or separate consent ceiling. Manage its scopes and revoke it in Settings > API. OAuth remains the route for a personal connection with the person's role, record access, agency rules and explicit consent.

This option supports clients that can send headers but cannot complete Lovelio's OAuth callback. It does not prove a particular client has securely stored the key or completed a workflow.

How the OAuth flow works

  1. Your client gets a 401 from the MCP endpoint and reads the discovery metadata above.
  2. It registers itself at POST /api/oauth/register (dynamic client registration, public clients, PKCE S256 required) and gets a client_id.
  3. It opens /api/oauth/authorize in a browser. A workspace admin signs in and approves selected permissions.
  4. The client exchanges the code at POST /api/oauth/token for an access token (1 hour) and a refresh token (30 days). Lovelio stores token hashes and encrypts the internal API credential. The client receives OAuth tokens, limited to the approved scopes.
  5. Every MCP call carries the access token. The client refreshes it in the background. Disconnecting revokes at POST /api/oauth/revoke.

Complete recruiting workflows

The tool catalogue includes form templates, questionnaire drafts and completion, candidate import preparation and status, interview scheduling, candidate matching, record cleanup, and webhook maintenance. A visible tool still needs the agency grant and the caller's role permission. Personal OAuth actions use the connected person's current role and record access. Admins can grant the needed capabilities in Settings > Workspace > Agent access; role permissions remain in Settings > Workspace > Permissions. Existing connections must reconnect and consent to additional scopes.

For native phone references, use create_reference_instance, read get_form_instance, save actual answers with submit_form_instance and draft: true, then complete with draft: false. Use send_form_instance only for an intended email reference. Read the reference recipe for the full sequence.

For CV imports, call create_candidate_import, then add_candidate_import_files. Upload the actual file bytes to each returned signed upload_url; creating upload slots does not upload a CV. Call finalize_candidate_import with the uploaded item IDs and poll get_candidate_import. A processing acknowledgement does not mean parsing has completed.

Persist one idempotency_key per intended write. Reuse it for an identical retry. Read the resulting record to verify completion. Keep returned IDs so later calls address the same record.

A connected chatbot does not provide durable agency orchestration by itself. Use MCP for interactive consultant work. For unattended queues and webhooks, use a Connect integration with persisted jobs, event deduplication, retry receipts, and human approvals for hiring decisions.

Form reads respect team visibility. A form-list page can be empty while meta.has_more is true; continue using meta.next_cursor.

First tool call

Once connected, a test prompt:

List my 5 most recent jobs.

The agent calls list_jobs and returns a table.

Or an action:

Create a job for a Senior Backend Engineer, remote, GBP 110-140k base.

The agent drafts the job with create_job_from_description, asks which client the job is for, and confirms it with you before publishing.

What the tools can do

The tools call the V1 REST API and the in-app action registry. The generated catalogue and regression tests check that their routes and declared permissions agree. They do not guarantee every agency workflow is available: phone-reference creation and answer submission, form-template authoring and bulk CV import management currently require REST. The connection's scope ceiling and each action's permissions also apply. Human approval remains part of candidate decisions. The full REST surface is documented in the OpenAPI reference.

Both search_candidates and search accept page (starting at 1). Keep query and limit unchanged between pages. Candidate results contain data.results, total_count, page, and has_more; use the returned search notes and verification limits when explaining matches. A bare email address keeps its email filter without model interpretation. CV mentions are a separate tier, not confirmed employment matches. Every candidate returned by either search door counts against the agent access rules.

Every tool below mirrors one V1 route or one registry action. Any write action without a typed tool still runs through batch, which takes write actions only; call list_actions or describe_action first for its payload shape and scope.

<!-- mcp-catalogue:start -->

293 tools, 107 read and 186 write. Generated from the server's tool list; do not edit by hand.

Account and admin (accounts:read, accounts:write)

  • add_quota_adjustment (write): Add a manual credit or debit to a consultant's (or the agency's) recognised billings for a period, with the reason.
  • get_account_overview (read): Get your Lovelio account details including company name, plan, and location.
  • get_account_team (read): Get one team on the account with its lead and members.
  • get_account_user (read): Get one user on the account: name, email, role, team and status.
  • get_company_intelligence (read): Get the synthesised Company Intelligence profile (voice, hiring process, values, business, personal attributes, compensation, flags).
  • get_transcription_usage (read): Get the current calendar month's video-transcription usage for your Lovelio account.
  • get_workflow_rules (read): The agency's workflow rules: AI screening thresholds, chase and escalation days, reference counts and auto-reject settings.
  • invite_team_member (write): Invite a new team member by email.
  • list_account_teams (read): List the teams on the account with their members.
  • list_account_users (read): List the users on the account with name, email, role and team.
  • list_api_keys (read): List the API keys on the account: name, key prefix, scopes, status and last use.
  • list_email_templates (read): List the agency's email templates with their key, subject and body.
  • list_sso_connections (read): List the single sign-on connections configured for the account with provider, domain and status.
  • reassign_record (write): Move ownership of clients, jobs, candidates, applications, placements, specs or BD targets to another consultant.
  • refresh_company_intelligence (write): Queue a fresh deep-enrich + seven-pass synthesis run for the account.
  • resolve_identity_review (write): Decide an identity match Lovelio was not sure about.
  • resolve_occupation_review (write): Decide the occupation behind a job title Lovelio could not place on its own.
  • set_quota_target (write): Set (or clear with null) the billings target for the agency, a team or a consultant in a quota period.
  • update_brand_voice (write): Set the agency's brand voice prompt: the tone and phrasing Lovelio uses in agency-authored copy such as candidate emails and social posts.
  • update_workflow_rules (write): Change the agency's workflow rules in two steps.

Activities (activities:read, activities:write)

  • add_note (write): Add a note to any record (job, job ad, candidate, application, interview, placement).
  • list_activities (read): List recent activity and audit events.
  • log_call (write): Record a phone call with a candidate or a client contact (never a bare company: pass client_contact_id and the client resolves from it).

Analytics (analytics:read)

  • get_analytics_dashboard (read): The agency's headline numbers: open jobs, active candidates, submissions, interviews and placements for the current period, as the in-app dashboard shows them.
  • get_analytics_metrics (read): Recruiting metrics over a trailing window in days: time to submit, time to place, conversion between stages, and volumes.
  • get_analytics_pipeline (read): Pipeline counts by stage over a trailing window in days, for the whole agency or one job.

Applications (applications:read, applications:write)

  • bulk_reject (write): Reject several applications in one go, with one reason for all.
  • complete_assessment (write): Run the AI assessment for a candidate on a job now, instead of waiting for the background pass.
  • confirm_phone_screen_draft (write): Log the phone screen: adds the notes to the timeline, then advance or hold moves an application a human has marked Yes to Screen, reject parks a pre-client candidate at No, and no_show leaves the stage alone.
  • create_application (write): Attach an existing candidate (or several) to a job.
  • get_application (read): Get full details of an application including AI assessment scores, criteria breakdown, and recommendation.
  • get_phone_screen_draft (read): Read a phone screen draft and its remaining gaps.
  • list_applications (read): List job applications.
  • list_review_queue (read): List the review queue: things Lovelio flagged for a human to look at (stalled candidates, reference red flags, unanswered client questions, interviews due an outcome, and so on), with priority and whether each is resolved.
  • log_offer (write): Record that the client has made an offer to the candidate and move the application to the Offer stage.
  • move_stage (write): Move an application to any canonical pipeline stage.
  • prepare_phone_screen (write): Start a phone screen draft for an application.
  • reassess_application (write): Queue a fresh candidate assessment for an application after its candidate, job requirements or Client DNA changed.
  • record_offer_outcome (write): Record what happened to the offer that is out on an application: accepted (stays at Offer - log the placement next), declined (declined_by candidate moves it to Withdrew, client to Rejected; no email goes to the candidate), or countered (the counter salary and start date replace the offer, stays at Offer).
  • reject_candidate (write): Reject an application (moves the application to the rejected stage).
  • resolve_review_item (write): Resolve one review queue item, reopen it, change its priority, or snooze it until a date.
  • send_ai_voice_screen (write): Invite a candidate to a short AI voice screen.
  • update_application (write): Change the source or owner on an application (not the stage: use move_stage; not notes: use add_note).
  • update_phone_screen_draft (write): Set the outcome, notes, call time or duration on a phone screen draft.
  • withdraw_application (write): Mark an application as withdrawn (candidate-initiated drop-out).

Candidates (candidates:read, candidates:write)

  • add_candidate_import_files (write): Get signed upload slots for original CV files.
  • add_referee (write): Add a referee to an application by hand (name and email, optionally relationship and phone).
  • add_web_candidate (write): Add a person from search_web_candidates to the job.
  • add_web_candidate_to_database (write): Add a person from search_web_candidates to the database.
  • add_web_candidate_to_pool (write): Add a person from search_web_candidates to a talent pool instead of the job.
  • bulk_add_to_talent_pool (write): Add several candidates to a talent pool at once.
  • confirm_candidate_draft (write): Create the candidate from the draft.
  • create_candidate (write): Create a new candidate profile.
  • create_candidate_import (write): Start a bulk CV import.
  • delete_candidate (write): Soft-delete a candidate (not GDPR hard delete).
  • draft_contractor_check_ins (write): Draft one ask for everyone on the check-in list who can be reached (up to 50): "Are you free from <date>?" for contracts finishing soon, a "How is it going?" check-in for the quiet ones.
  • draft_extension_asks (write): Draft the extension asks: "Keep <name> past <end date>?" to the client contact and "Want to stay on?" to the contractor, for every contract on list_extension_asks (up to 50 emails) or the placement_ids given (any contract still waiting on a plan or asked).
  • draft_job_availability_asks (write): Draft "Are you free from <start date>?" emails for everyone on a contract job's free list whose free date no person confirmed in the last 7 days and who can be reached.
  • evaluate_candidate_evidence (write): Check requirements across a selection, talent pool, job applicants, import, full search or the candidate database.
  • extract_candidate_preferences (write): Read the candidate's recent call notes and timeline notes and propose a preferences patch (preview first; { apply: true, patch } writes the confirmed proposal).
  • finalize_candidate_import (write): Confirm uploaded CV files and close the upload phase.
  • find_candidate_duplicates (read): Find candidates that look like the same person (matching email, phone or LinkedIn), grouped so they can be reviewed and merged in the app.
  • find_free_for_job (read): Who is free for a contract job: everyone who meets its requirements and is free by its start date, best fit first, each with who confirmed the free date and when.
  • get_candidate (read): Get full profile of a specific candidate including contact details, skills, and resume data.
  • get_candidate_draft (read): Read a candidate draft: the extracted fields, parse status and remaining gaps.
  • get_candidate_import (read): Get import progress, failures and the final report.
  • get_contractor_page_link (write): A fresh link to a contractor's own page, for a text or a chat.
  • get_evidence_evaluation (read): Read progress and original evidence.
  • get_evidence_pack (read): Read a compact evidence pack for submission, interview or comparison.
  • list_candidate_papers (read): List the documents on file for a candidate: right to work, police checks, licences, insurance, each with the day it stops counting.
  • list_candidates (read): List candidates in your Lovelio account.
  • list_outreach (read): List outreach messages sent to candidates over email, LinkedIn or WhatsApp, with status (draft, sent, replied, no_response).
  • list_referees (read): List the referees on file for a candidate, whether the agency added them or the candidate supplied them.
  • match_candidates_to_job (read): Search the whole candidate database for the best matches to a job, ranked with a short why-them line per candidate.
  • merge_candidates (write): Merge a duplicate candidate into a primary candidate.
  • prepare_candidate_from_cv (write): Parse a CV into a candidate draft.
  • prepare_evidence_pack (write): Prepare reusable source-grounded evidence for a submission, interview or comparison.
  • record_whatsapp_consent (write): Record that a candidate agreed to get WhatsApp messages from the agency (agreed true), or no longer does (agreed false).
  • save_paper (write): Record a document the agency has checked for a candidate: right to work, a police check, a licence, insurance.
  • search (read): Search across jobs, candidates, applications, and interviews using natural language.
  • search_candidates (read): Search candidates by skills, experience, or qualifications using the shared ranked search.
  • send_availability_asks (write): Send availability asks a person has read: each one goes on its channel (email, the default; or "whatsapp", the approved template, only to someone who agreed, 8am to 6pm on a weekday their time, at most one a week) and records the ask, so their reply sets their free date (source candidate_reply).
  • send_extension_asks (write): Send extension asks a person has read, up to 25 at once: to "client" emails the client contact (client_contact_id, else the contract's contact), to "contractor" emails the contractor, or with channel "whatsapp" sends them the approved WhatsApp ask (only to someone who agreed, 8am to 6pm on a weekday their time, at most one a week).
  • update_candidate (write): Update a candidate profile.
  • update_candidate_draft (write): Fill or correct fields on a candidate draft before confirming.
  • update_candidate_preferences (write): Update what a candidate wants next: preferred roles, seniority, work types, relocation, availability, preferred locations, salary expectation, notice period and work rights.
  • update_candidate_tags (write): Add or remove tags on a candidate without touching the rest (pass add and/or remove), or replace the whole list with tags.

Clients (clients:read, clients:write)

  • add_client_contact (write): Add a contact (hiring manager, HR, finance) to a client.
  • add_client_dna_note (write): Add a note to a client's DNA - anything learned from a meeting, call, or feedback (what they value, how they interview, dealbreakers).
  • add_client_recruiter (write): Add a teammate to a client's recruiter list.
  • add_found_client (write): Add a company from find_new_clients as a client, with the people you pick from find_client_people as its contacts.
  • create_client (write): Create a client (a company the agency recruits for).
  • create_client_site (write): Add a work site (an address) to a client, for contract placements and job locations.
  • delete_client (write): Delete a client record.
  • delete_client_contact (write): Remove a contact from a client.
  • find_client_people (write): The people worth calling at a company from find_new_clients, grouped into Leadership, Hiring managers and People and talent, most senior first.
  • find_new_clients (write): Find companies the agency could win as clients, from the company database.
  • get_client (read): Get full detail of one client: website, industry, locations, enrichment and Client DNA status, and notes.
  • get_client_dna (read): A client's hiring DNA: how they hire, what they value, deal breakers and the notes consultants have added.
  • list_client_contacts (read): List a client's contacts: name, title, email, phone, who they report to and which one is primary.
  • list_client_sites (read): List a client's sites: the offices and locations jobs can be based at.
  • list_clients (read): List the clients in your Lovelio account - the companies the agency recruits for.
  • promote_client_contact (write): Turn a "works here" person - someone whose own record says they work at this client - into a contact the agency deals with.
  • remove_client_recruiter (write): Remove a teammate from a client's recruiter list.
  • remove_client_site (write): Remove a work site from a client.
  • set_client_fee_terms (write): Set a client's fee schedule: currency, fee basis (package or base), slab tiers (each band's percent applies to the whole salary), minimum fee, contract margin, guarantee days and remedy, payment terms.
  • update_client (write): Update fields on a client (name, website, company phone, industry, description, locations, address, notes).
  • update_client_contact (write): Update a contact on a client (name, email, phone, title, notes, primary, reports-to).

Documents (documents:read, documents:write)

  • delete_document (write): Delete an uploaded document.
  • get_document (read): Get one document record: file name, content type, size, which record it belongs to and who added it.
  • get_document_download_url (read): Get a short-lived signed URL to download one document.
  • list_documents (read): List the documents attached to one record (a candidate, application, client, job or placement): CVs, cover letters, contracts and uploads, with file name, type and when each was added.
  • set_candidate_cv (write): Make one of the candidate's uploaded documents their current CV (the file the profile points at and the one that is parsed).
  • upload_document (write): Attach a file to a record (candidate, client, contact, job, application, placement and so on).

Comms (emails:read, emails:write)

  • bulk_send_email (write): Send the same email to several candidates now.
  • cancel_scheduled_email (write): Cancel a scheduled email before it sends.
  • confirm_email_draft (write): Send the drafted email now, or schedule it if the draft has a schedule_at.
  • email_client_contact (write): Send an email to a contact at a client now.
  • get_email_draft (read): Read the current state of an email draft: subject, body, schedule and any gaps left before it can be sent.
  • get_scheduled_email (read): Get one scheduled email: recipient, subject, body, send time and status.
  • list_scheduled_emails (read): List emails queued to send later, with status, recipient candidate and send time.
  • prepare_compose_email (write): Draft an email to a candidate.
  • revise_email_draft (write): Rewrite an email draft from a plain-English instruction, for example "warmer tone, mention the start date".
  • schedule_email (write): Schedule an email to a candidate for a future time.
  • send_email (write): Send an email to a candidate immediately.
  • update_email_draft (write): Set fields on an email draft directly (subject, body, schedule).

Forms (forms:read, forms:write)

  • add_form_question (write): Add a question to a reusable form template.
  • create_form (write): Create a reusable form template.
  • create_reference_instance (write): Prepare a reference questionnaire for a phone call or later email delivery.
  • delete_form (write): Delete a form template after explicit user approval.
  • delete_form_question (write): Delete a template question after explicit user approval.
  • get_form (read): Get one form template with its questions.
  • get_form_instance (read): One form instance in full: type, status, who it went to and every timestamp from sent to completed.
  • list_form_instances (read): List screening forms, reference questionnaires and interview forms that have been sent or completed, newest first.
  • list_forms (read): List the agency's form templates (screening, reference and interview forms) with their question counts.
  • prepare_screening_form (write): Load or generate the phone screen question set for an application.
  • request_referee_details (write): Email the candidate a link to supply their referees.
  • review_reference (write): Record the consultant's verdict on a completed reference: clear, or concern with a note.
  • send_form (write): Send any form template to a candidate or a client contact, optionally tied to an application, interview or job.
  • send_form_instance (write): Email a prepared reference form instance to its recipient.
  • send_referee_questionnaires (write): Send the reference questionnaire to every referee on an application who has not had it yet, or to the referee ids given.
  • send_reference_request (write): Send one referee the reference questionnaire for an application.
  • send_references_to_client (write): Email completed references for an application to the client contact.
  • send_screening_form (write): Create a screening form for an application and email it to the candidate to fill in.
  • submit_form_instance (write): Save actual respondent answers or complete a phone reference or screening.
  • update_form (write): Update a form template name, description or AI augmentation setting.
  • update_form_question (write): Edit or reorder a form template question.

Integrations (integrations:read)

  • get_slack_integration (read): The Slack connection for this account: whether it is connected, the workspace, and the channel Lovelio posts to.
  • list_chat_integration_users (read): List the people linked to one chat integration and which Lovelio user each maps to.
  • list_chat_integrations (read): List chat integrations (Slack, WhatsApp and similar) connected to the account, with status.

Interviews (interviews:read, interviews:write)

  • cancel_interview (write): Cancel a scheduled interview.
  • cancel_meeting (write): Cancel a previously booked meeting.
  • confirm_interview_action_draft (write): Apply the reschedule or cancel: updates the interview, the calendar event and emails the candidate if asked.
  • confirm_interview_draft (write): Book the interview from the draft and put it on the interviewer's connected calendar.
  • confirm_interview_form_draft (write): Submit the interview form and record the interview outcome from it.
  • confirm_scorecard_draft (write): Submit the scorecard.
  • create_reminder (write): Put a reminder in the diary at a specific time, optionally linked to a candidate, job or application.
  • get_calendar_event (read): Get one calendar event with its time, type, attendees and the record it belongs to.
  • get_interview (read): Get full details of an interview including feedback, notes, and outcome.
  • get_interview_action_draft (read): Read a reschedule or cancel draft and its remaining gaps.
  • get_interview_context (read): Everything an interviewer needs before an interview: the candidate, the job, the interview plan and questions, earlier scorecards and notes.
  • get_interview_draft (read): Read an interview draft: the fields so far, the predicted values and the remaining gaps.
  • get_interview_form_draft (read): Read an interview form: sections with scores and notes, the recommendation, feedback and the remaining gaps.
  • get_scorecard_draft (read): Read a scorecard draft: scores so far, recommendation, feedback and the remaining gaps.
  • list_calendar_events (read): List calendar events (interviews, phone screens, reminders, deadlines, meetings) in a date window.
  • list_interviews (read): List scheduled interviews.
  • prepare_cancel_interview (write): Start a cancel draft for a booked interview.
  • prepare_interview_form (write): Generate the AI interview form for an interview, or return the existing one.
  • prepare_reschedule_interview (write): Start a reschedule draft for a booked interview.
  • prepare_schedule_interview (write): Start an interview draft for an application.
  • prepare_submit_scorecard (write): Start a scorecard draft for an interview.
  • propose_interview_slots (read): Return ~12 candidate day/time options that are free for all of the given interviewers, sourced from the Lovelio calendar (and Google free/busy when connected).
  • request_interview (write): Book an interview, two ways.
  • reschedule_interview (write): Reschedule an interview to a new time.
  • reschedule_meeting (write): Move a previously booked meeting to a new time.
  • schedule_call (write): Book a phone call in the diary (with a candidate, or internal).
  • schedule_interview (write): Schedule an interview for an application.
  • schedule_meeting (write): Schedule a meeting (generic calendar event).
  • send_interview_followup (write): Send a post-interview follow-up: recipient "candidate" for the debrief / news / no-show note, recipient "client" for the next-steps or feedback note to the client contact (client interviews only).
  • start_video_call (write): Create a Lovelio video call room on an interview and email the candidate a join link.
  • submit_scorecard (write): Submit an interview scorecard: per-criterion scores, an overall recommendation, and optional notes.
  • update_interview_action_draft (write): Change the new time, reason or notify flag on a reschedule or cancel draft.
  • update_interview_draft (write): Fill or change fields on an interview draft before confirming.
  • update_interview_form_draft (write): Score one section (section_id plus section_score 1 to 5 and notes), or set the overall recommendation and feedback on an interview form.
  • update_interview_outcome (write): Record the outcome (passed / failed / no_show / cancelled) and optional feedback for an interview.
  • update_scorecard_draft (write): Score criteria on a scorecard draft.

Jobs (jobs:read, jobs:write)

  • check_talent_pools (write): Check a live job against the talent pools once more.
  • close_job (write): Close a job.
  • confirm_job_draft (write): Promote a staged draft from create_job_from_description into a real job.
  • convert_spec (write): The client wants a specced candidate: create the job at that client and add the candidate at the submitted stage in one step.
  • create_distribution_rule (write): Create a distribution rule: jobs matching the filter post automatically to the named boards when published.
  • create_job (write): Create a new job requisition.
  • create_job_ad (write): Create a new public job ad for a role.
  • create_job_from_description (write): Turn a plain-language description of a role ("senior backend engineer in London, 120k") into a drafted job spec.
  • delete_job (write): Soft-delete a job that has no job ads or applications yet.
  • get_job (read): Get full details of a specific job including description, assessment criteria, interview questions, and pipeline stats.
  • get_job_ad (read): Fetch the most recent published job ad for a job.
  • get_job_ad_by_id (read): Get one job ad by its own id: the copy, status, publish dates and the job it belongs to.
  • get_job_draft (read): Read the current state of an in-progress job draft.
  • get_job_ranking (read): Stack-rank every interviewed candidate on a job by aggregate scorecard score (highest first).
  • get_job_share_bundle (read): Get the ready-to-share content bundle for a job: pre-composed X post, LinkedIn post, careers URL, image URL, and a short email summary.
  • get_job_summary (read): Get an AI-generated recruitment summary for a job - pipeline health, top candidates, and recommended actions.
  • get_social_draft (read): Fetch the auto-generated LinkedIn + X social post drafts for a job, plus the OG image URL used for unfurl previews.
  • list_distribution_boards (read): List the job boards Lovelio can post ads to, with whether each is connected for this account.
  • list_distribution_postings (read): List where job ads are posted: one row per ad per board, with status and the live URL.
  • list_distribution_rules (read): List the job-board distribution rules: which jobs post automatically to which boards.
  • list_job_ads (read): List job advertisements.
  • list_jobs (read): List jobs in your Lovelio account.
  • plan_linkedin_sourcing (write): Build four LinkedIn sourcing searches from a job's full structured requirements, prior placement signals and search feedback: direct, adjacent, feeder-company and hidden-gem lanes.
  • reopen_job (write): Reopen a closed or filled job (sets status=active).
  • revise_job_draft (write): Apply a natural-language instruction ("make it punchier", "move to Sydney and bump salary to AUD 180k", "more formal tone") to a staged draft.
  • rewrite_job_ad (write): AI-rewrite an existing job ad with a natural-language instruction.
  • search_web_candidates (write): Find people on the web who are not in the agency yet.
  • set_ai_screening (write): Turn automatic AI voice screening on or off for a job and set its focus areas.
  • skip_job_draft_gap (write): Record that a job draft gap is deliberately left blank so it stops being reported.
  • update_distribution_rule (write): Change a distribution rule: rename it, change its boards or filter, or pause and resume it with active.
  • update_job (write): Update fields on an existing job (title, location, compensation, status, team, hiring manager).
  • update_job_ad (write): Edit a job ad (title / description / published flag).
  • update_job_draft (write): Fill one or more gaps on an in-progress job draft - including the mandatory client_id (cli_..., from list_clients / create_client).
  • update_social_draft (write): Edit a job's LinkedIn / X post text.

Marketplace (marketplace:read, marketplace:write)

  • get_marketplace_deal (read): One marketplace deal in full: counterpart agency, split, and the linked application and placement once they exist.
  • get_marketplace_intro (read): One marketplace intro in full, including the anonymous candidate profile until the intro is accepted.
  • get_marketplace_listing (read): One marketplace listing in full: pitch, chips, salary, fee split and expiry.
  • list_marketplace_deals (read): List marketplace deals (accepted intros) with their status and your share of the fee.
  • list_marketplace_intros (read): List marketplace intros: submissions of your candidates to other agencies' jobs, requests for other agencies' candidates, and the ones sent to you.
  • list_marketplace_listings (read): Browse marketplace listings: jobs other agencies want candidates for and candidates other agencies will share, on a split fee.
  • request_marketplace_candidate (write): Ask the agency behind a marketplace candidate listing for an intro.
  • respond_to_marketplace_intro (write): Respond to a marketplace intro: check whether you already know the candidate, accept (reveals both sides and opens a deal), decline with a reason, or withdraw one you sent.
  • send_marketplace_listing (write): Email one of your marketplace listings to a recruiter at another agency who is not on Lovelio yet, with a link they can respond from.
  • share_candidate_to_marketplace (write): List one of your candidates on the marketplace, anonymously, so other agencies can request an intro on a split fee.
  • share_job_to_marketplace (write): List one of your jobs on the marketplace so other agencies can submit candidates on a split fee.
  • submit_to_marketplace_job (write): Submit one of your candidates, anonymously, to another agency's marketplace job.
  • update_marketplace_deal (write): Move a marketplace deal along: add the shared candidate to one of your jobs' pipelines, mark your side of the fee paid or received, or close the deal with a reason.
  • update_marketplace_listing (write): Pause, resume, withdraw, renew or mark filled one of your marketplace listings.

Placements (placements:read, placements:write)

  • create_placement (write): Record a placement (the win): a candidate placed with a client for a fee.
  • draft_availability_check (write): Draft an email asking a contractor whose contract ends in the next eight weeks if they are free from the first working day after it ends.
  • get_contractor_report (read): The contract forecast: live contracts with GP week by week for the next 13 weeks on the agency's standard week, less the public holidays where each contractor works, added up for the agency, each team and each consultant, plus the contractors with documents to chase.
  • get_placement (read): Get one placement in full: candidate, client, job, salary, fee, start date, and guarantee.
  • get_placement_papers (read): Check a contract's documents: what it needs (from the job, the pay route and the country's rules) and whether each is current, missing, expired, ending before the contract does, or marked not needed.
  • list_contractor_check_ins (read): The contractors to check in with this week: contracts finishing within 8 weeks with no confirmed free date, and contractors not heard from in 30 days.
  • list_extension_asks (read): Contracts ending within 8 weeks with no plan and nobody asked yet about extending, each with the client contact who would be asked.
  • list_placements (read): List placements - candidates placed with a client for a fee.
  • mark_placement_status (write): Update a placement through its guarantee lifecycle: pending_start, started, fell_off (during guarantee), or completed.
  • send_placement_email (write): Send a placement lifecycle email: recipient "candidate" for the start-day good-luck note, recipient "client" for the guarantee-end check-in.
  • set_candidate_contracting_profile (write): Save a candidate's contracting details for their country so contract placements pick them up.
  • set_placement_credits (write): Replace who gets credit for a placement and how the fee is split between them.
  • set_placement_timesheet_approvers (write): Set the client contacts who approve timesheets on a contract placement.
  • update_placement (write): Change the terms on an existing placement: salary and package, fee, dates, contract rates and end date, the contract plan (what happens on the end date), the next contact date, expected GP, work site (work_site_id, null to clear), timesheet approvers, contractor details, or credits.
  • waive_paper (write): Mark one document not needed for one contract (waived true), or ask for it again (waived false).

Quotas (quotas:read)

  • get_quota_board (read): A quota period's board: recognised billings, placement counts and targets for the agency, each team and each consultant, plus any adjustments.
  • get_quota_plan (read): The agency's quota plan: cadence, currency, when a placement counts, which placement types count, and whether closed periods are locked.
  • list_quota_periods (read): List quota periods (the quarters, months or years the agency measures billings in), newest first.

Submissions (submissions:read, submissions:write)

  • answer_spec_question (write): Reply to a question the client asked from a spec profile page.
  • answer_submission_question (write): Answer a question a client asked about a submitted candidate, or send them any message on that submission.
  • chase_spec (write): Nudge the client contact about a spec they have not responded to.
  • chase_submission (write): Nudge a client contact about a submission they have not responded to.
  • create_submission (write): Send a submission of candidates on a job to the job's client contact for review.
  • get_spec (read): Get one spec send: the candidate, the client, the message sent and how the client responded.
  • get_submission (read): Get one submission in full: the client review link, each candidate, and the client verdict, rating, and note per candidate.
  • list_specs (read): List spec sends: candidates floated to a client without a live job, with status (sent, viewed, interested, passed, converted).
  • list_submissions (read): List submissions - packs of candidates sent to a client contact for review.
  • record_client_verdict (write): Record what the client said about a submitted candidate when they told you directly instead of using their review link: interview_requested, or rejected with an optional reason, their words, and whether they want more candidates.
  • send_spec (write): Send a spec (a float): pitch one candidate, or up to five in candidates, to a client contact with no open job.
  • withdraw_spec (write): Take back a spec the client still has open (sent, viewed or interested, not yet turned into a job).

Talent pools (talent_pools:read, talent_pools:write)

  • add_to_talent_pool (write): Add a candidate to a talent pool.
  • approve_join_request (write): Approve a pending talent pool join request.
  • ask_pool_member_if_looking (write): Email a talent pool member the pool's "still looking?" check-in now, as you.
  • create_talent_pool (write): Create a talent pool - a named group for candidates who are a good agency fit.
  • decline_join_request (write): Decline a pending talent pool join request.
  • delete_talent_pool (write): Permanently delete a talent pool.
  • get_talent_pool (read): Get one talent pool: name, description, eligibility rule and publish state.
  • list_talent_pool_join_requests (read): List requests to join one talent pool from its public page, with status (pending, approved, declined).
  • list_talent_pool_members (read): List the candidates in one talent pool, with when and how each joined.
  • list_talent_pools (read): List talent pools with name, slug, eligibility and whether each is published.
  • remove_from_talent_pool (write): Remove a candidate from a talent pool.
  • set_pool_member_interest (write): Record whether a talent pool member is still looking, when they told you some other way (a call, a text).

Webhooks (webhooks:read, webhooks:write)

  • create_webhook (write): Create a webhook subscription.
  • delete_webhook (write): Delete a webhook subscription.
  • get_webhook (read): Get one webhook endpoint: URL, events, status and recent delivery health.
  • list_webhook_deliveries (read): Delivery log for one webhook, newest first: event, status, attempts, last response code and error.
  • list_webhook_events (read): List every event type a webhook can subscribe to, with what each one means.
  • list_webhooks (read): List the webhook subscriptions on this account with their URLs, events and status.
  • replay_webhook_delivery (write): Queue a repeat delivery of an existing event.
  • rotate_webhook_secret (write): Replace a webhook signing secret after operator approval.
  • test_webhook (write): Send a signed test event.
  • update_webhook (write): Change a webhook destination, events or active/paused status.

Open to every grant

  • batch (write): Execute up to 100 canonical actions in a single round-trip.
  • describe_action (read): Describe one batch action: what it does, the payload shape and the scope it needs.
  • get_job_creation_status (read): Poll the post-confirm create_job task runner for per-step progress (description, criteria, questions, ad, social).
  • get_task (read): Check an async task started by another call (an enrichment, an import, a bulk job): its status, progress and result when done.
  • list_actions (read): List Lovelio actions with the payload shape and the scope each needs.
  • list_stages (read): List the pipeline stages in order, with the key and label of each.
  • resolve_command (read): Resolve an everyday request to a Lovelio page, record or existing process.
<!-- mcp-catalogue:end -->

Draft flows

Every prepare_* tool stages a draft and returns a review_token, the draft so far, and gaps, the fields still missing. get_*_draft reads it back, update_*_draft sets fields (the email flow also has revise_email_draft for a plain-English change), and confirm_*_draft performs the real write: sends the email, creates the candidate, books the interview, logs the call, submits the scorecard. Confirm refuses with a 409 draft_has_gaps error that lists the gaps until every one is filled, so an agent can loop on the error text. Booking an interview can also refuse with SCHEDULING_CONFLICT, carrying the clashes and suggested slots; retry with a new scheduled_at or ignore_conflicts: true. Nothing changes in Lovelio until confirm, and none of these flows moves a stage on the AI's own verdict: a phone screen moves the application only on the outcome the caller sets.

Sending email

Outbound email is off by default on every new account, including agent-created trials. Tools that send email return a clear error until Lovelio enables outbound for your account. This is a safety rail, not a bug; contact hello@lovelio.ai to enable it.

Rate limits

Each underlying V1 request consumes one request against your key's rate limit (60 per minute on trial, 600 per minute on paid). The OAuth endpoints are rate limited per IP. See error handling for retry rules.

Troubleshooting

  • Cannot approve access. Sign in as an admin of the intended workspace. Older connections using coarse read/write grants need one reconnect.
  • 401 "Invalid or expired access token". Your refresh token has expired (30 days) or the connection was revoked. Reconnect: your client will open the authorize page again.
  • OAuth loops. Clear the cached credentials for your region's domain in your MCP client and reconnect. Local dev builds should point at http://localhost:3005/api/mcp.
  • "Invalid or expired credential" right after connecting. You are probably connected to the wrong region's URL - a connection made on one region's domain never works on another. Reconnect using the URL from Settings -> API keys.
  • Rate limit 429. Back off and retry after the Retry-After interval.

Tool results and safe retries

Check isError before treating a tool call as successful. Successful results set isError: false and structuredContent.success: true. Their existing human-readable content[].text stays unchanged. Asynchronous success means the task was accepted; poll its task ID for completion.

Failures set isError: true and structuredContent.success: false. Read structuredContent.error.code, not the wording of the text:

{
  "isError": true,
  "content": [{ "type": "text", "text": "This call needs Write clients (clients:write). Add it to the key or the app's scopes.\nINSUFFICIENT_SCOPE: Resolve the reported problem before trying again." }],
  "structuredContent": {
    "success": false,
    "error": {
      "code": "INSUFFICIENT_SCOPE",
      "message": "This call needs Write clients (clients:write). Add it to the key or the app's scopes.",
      "status": 403,
      "category": "permission",
      "retry": "none",
      "guidance": "Resolve the reported problem before trying again."
    }
  }
}

The API code and message survive unchanged. Failure details retain field, docs, request_id, error data, retry_after, operation_id and idempotency_key when available. status: 0 means no HTTP response arrived. Categories include permission, authentication, invalid_input, not_found, conflict, rate_limit, transient, in_progress, uncertain_outcome and failure. Unknown codes remain errors.

error.retryAgent action
noneResolve the permission, input or resource problem first.
retryWait for retry_after, or use bounded backoff.
same_keyRepeat only the identical operation with the original idempotency_key. This asks R1 for the saved result or current claim state.
reconcileRead the resource to establish the outcome. Do not repeat the write, use a new key, or wait for expiry.

Before a write, save a unique idempotency_key in the tool arguments. If omitted, the server creates one for POST requests and includes it in the success or error details. If the MCP response itself disappears and you did not save a key, reconcile first. The server does not retry automatically. PATCH requests and draft streaming do not gain retry protection from this argument.

IDEMPOTENCY_IN_PROGRESS and IDEMPOTENCY_UNAVAILABLE allow only same_key. IDEMPOTENCY_RESULT_STORAGE_FAILED also allows only same_key; the outcome remains uncertain. IDEMPOTENCY_OUTCOME_UNKNOWN requires reconciliation. A key mismatch (IDEMPOTENCY_KEY_REUSED) never means the changed operation succeeded. Inspect the original operation before choosing the next action. Completed responses last 24 hours; uncertain executions remain reserved beyond expiry.

batch retains every operation in structuredContent.operations, including each result or typed error and its original correlation ID. Any failed operation sets the whole result to isError: true (BATCH_PARTIAL_FAILURE or BATCH_FAILED). The text still starts with the succeeded/failed counts and per-operation lines. Follow each failed operation's retry guidance and retain its own key. Never replay successful operations with new keys.

Permissions in discovery

tools/list returns tools whose required permissions fit the current OAuth grant and enabled modules. V1 still enforces each call, including record access and conditional requirements. Discovery cannot grant authorization. An old narrow grant remains narrow if its underlying key gains permissions; reducing or revoking access also affects subsequent calls.

Tool descriptions state required permissions. add_to_talent_pool requires talent_pools:write; omitting pool_id also requires talent_pools:read for lookup. Supplying an ID avoids that lookup. Batch descriptions derive each action's scope from the existing V1 action declarations; each operation receives its own permission check. A visible batch tool does not authorize every action.

Account actions that first resolve the account need accounts:read as well as accounts:write. Personal MCP OAuth can request accounts:write; Connect partner apps cannot. The connected person must also have the required role permission. Person-bound and app-install credentials cannot mint API keys, even with accounts:write. Financial fields retain the V1 field-level permission checks. Search currently requires candidates:read for every supported entity type, matching the existing API declaration.