← Help centre

Connect an AI agent (MCP)

Signed in? Ask Lovelio this question inside the app - it answers from this same page.

Lovelio runs a Model Context Protocol (MCP) server on each region's app domain - yours is https://us.lovelio.ai/api/mcp. Connections and API keys are per region: they only work on the domain of the region your workspace lives in (the domain you sign in on). Connect a compatible MCP client and an AI agent can work your recruiting desk in natural language: add clients, create jobs, work candidates, send submissions to clients, and record placements. Every action goes through the same V1 API, permissions, and activity logging as the app, so an agent can never do something a person with that key could not.

MCP is an open standard, so Lovelio is not tied to one AI company. Compatible desktop chat apps, code editors, and command-line agents use the same URL. Client OAuth support can vary, so test the chosen client before a showcase. Lovelio does not require a particular vendor.

What you need first

A signed-in Lovelio workspace admin. The consent page shows the requested permissions. Select the access to grant. You do not paste an API key.

Connect any MCP client

The only thing a client needs is the server URL: https://us.lovelio.ai/api/mcp

  • Clients with a settings screen: add it under Connectors, Custom connector, or Add MCP server.
  • Clients with a JSON config file: add an entry under the mcpServers key with "type": "http" and "url": "https://us.lovelio.ai/api/mcp".
  • Clients with a command line: use that client's own add command, passing the URL and the HTTP transport.

The client needs Streamable HTTP and compatible OAuth support. Lovelio publishes discovery metadata and supports dynamic client registration. A client registration or callback error can prevent authentication before any tools load.

What happens when you connect

An admin signs in on the Lovelio consent page and approves selected permissions. Dynamically registered clients are unreviewed, which the page states clearly. The client receives short-lived OAuth tokens and refreshes them in the background. Access remains limited to the approved scopes even if the underlying key later gains permissions. Revoke the MCP credential in Settings -> API keys. Older connections using coarse read/write grants must reconnect once.

API-key fallback

If the client cannot complete OAuth but supports HTTP headers, use a dedicated Lovelio API key in Authorization: Bearer <key>. Create it in the same region's Settings > API page. Select the needed scopes, then enter it in the client's secure header settings, never chat. The MCP endpoint uses the same V1 checks and filters tools to the key's scopes. Revocation and scope reductions apply on the next request. Company keys have agency-wide record access, not a consultant's desk limits, and no separate OAuth consent ceiling. Personal OAuth remains the choice for a connection bound to a person's role and record access.

What the agent can do

The tool catalogue covers V1 reads and registered actions, grouped by area: clients, jobs, candidates, applications, submissions and specs, interviews and calendar, placements, talent pools, documents, references and forms, comms and templates, analytics and stages, distribution, business development, quotas, marketplace, admin rules, webhooks and integrations, and account admin (users, teams). Every V1 read has a tool; record reads return the full record (candidate pay, availability and work rights; job client and package; application references; placement contract and credits). Business development over the agent is read plus log a touch you made yourself: the agent never drafts or sends outreach. Read tools are named list_ and get_; write tools are named after the action (create_client, create_application, move_stage, create_submission, create_placement, and so on). Since 2026-09-10 the desk writes are all there: full candidate updates with tags, preferences and documents, applications with bulk reject, calls, reminders and scheduled emails, client sites, fee terms and recruiters, client verdicts, specs (floats), and placements with contract terms, timesheet approvers and the tidy-up of the candidate's other applications. The review queue is readable with list_review_queue, and resolve_review_item resolves, reopens, reprioritises or snoozes an item without moving any stage; resolve_identity_review and resolve_occupation_review answer the identity and occupation calls Lovelio could not make alone, and plan_linkedin_sourcing returns a sourcing plan for a consultant to run by hand. Account admins can list API keys and SSO connections; secrets are never returned. Discovery shows only tools covered by the current grant. Conditional permissions appear in tool descriptions: resolving a talent pool by name also needs talent_pools:read; batch checks each action separately. Personal MCP connections can request accounts:write with consent; Connect partner apps cannot. The connected person must also have the required role permission. Personal OAuth and app-install credentials cannot create API keys. Two catalogue tools need no permission at all: list_actions lists every action the batch tool can run, and describe_action explains one action and its payload, so an agent never guesses. Every tool result carries the V1 data in structuredContent.data alongside the readable text. Full catalogue with the scope each needs is in the connect guide at /docs/mcp.

Native workflow tools can create reference questionnaires, save draft or completed answers, send reference requests, manage reusable forms and questions, and manage candidate imports. Upload slots still require the client to upload the file bytes. Poll the import report until processing finishes. Matching accepts edited search facets. Webhook tools can update subscriptions, rotate secrets, send test events and replay deliveries. Discovery still respects scopes; action roles and record access apply at execution. Consultant OAuth has stricter scope ceilings, including no form or email scopes. Hiring decisions require a human.

Drafts before writes: the bigger actions run as a draft flow. prepare_compose_email, prepare_candidate_from_cv, prepare_schedule_interview, prepare_reschedule_interview, prepare_cancel_interview, prepare_phone_screen and prepare_submit_scorecard each stage a draft and return a review token plus the gaps still to fill. The agent reads and updates the draft by token, then confirm_ sends, creates, books, logs or submits. Nothing changes in Lovelio until confirm, and confirm refuses while a gap is open. Interview bookings land on the interviewer's connected calendar (Google or Outlook) through the same path the app uses.

Two things worth knowing up front:

  • Every job needs a client. jobs.client_id is required, so the agent gets a client id from list_clients or create_client before it can create a job. For your own internal hiring, your agency's own self-client is selectable.
  • Outbound email is off by default on every account, including agent-created trials. Tools that send email return a clear error until an admin turns outbound on. This is a safety rail, not a bug.

Tool outcomes

Check isError before treating a tool call as successful. Failures preserve stable API codes and retry guidance in structuredContent.error; readable text remains available. Batch retains each operation and marks any failed operation. Save an idempotency_key before writes. Reuse it only for the identical operation when instructed. An uncertain outcome requires checking the resource; never create a new key or blindly repeat the write. Retry receipts also bind to the credential and current permissions. A changed authorization context or an older unbound receipt requires reconciliation before another write. The MCP quickstart documents the complete contract.

Use MCP for interactive desk work. Use a Connect integration for unattended coordination with durable queues, saved operation IDs, retries and webhook deduplication. Rehearse real email delivery, calendar bookings, CV processing and bot hand-offs before running a full agency workflow.

Build an integration

Sign in at /developers/portal. Choose Create integration. Describe your product, its website, what it writes back, and whether it uses money fields. Lovelio works out the proposed access, drafts the listing and creates the integration keys. You can edit the use case from the integration page to recalculate the proposed access. You do not need an agency account to build an integration. Agencies still approve access when they connect.

Troubleshooting

  • If the developer portal cannot load your integrations, use Retry connection. It keeps your sign-in and existing integrations.
  • "Invalid or expired access token": reconnect to review the requested permissions again.
  • The agent stopped after about a month, or you revoked the connection: reconnect and an admin approves a new consent page.
  • Callback registration errors: Lovelio permits HTTPS, HTTP on localhost, and the exact Grok Bot and Cursor desktop callbacks cursor://anysphere.cursor-mcp/oauth/return and cursor://anysphere.cursor-mcp/oauth/callback. For Grok Bot, click Authenticate on the existing connector to open Lovelio's consent page. Other custom callbacks need compatibility review. Never paste an API key into chat to work around sign-in.
  • Connection loops after a successful registration: clear the saved credentials for your region's domain in your MCP client and connect again.
  • "Invalid or expired access token" right after connecting: you probably connected to another region's URL. A connection only works on the region your workspace lives in - reconnect with https://us.lovelio.ai/api/mcp.

Common questions

  • Where do I connect an agent? Settings -> API keys has a "Connect an AI agent" card with the server URL, and the full guide is at /docs/mcp.
  • Which AI client do I need? Choose a client with compatible Streamable HTTP and OAuth support. Test its connection first. Lovelio does not favour one vendor or require a particular vendor's subscription. Your client may charge for its own plan.
  • Where does my hiring data go? Your client fetches data from Lovelio, then puts it into the conversation with its own AI provider, subject to that provider's policies rather than Lovelio's.
  • Does the agent receive an API key? No. It receives OAuth tokens for the permissions you approved.
  • Can I limit what the agent does? Yes. Clear unwanted permissions on the consent page before approving.