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, so Lovelio is not tied to one AI company and needs no work on our side for a particular client.

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

You need a Lovelio API key. Two ways to get one:

• You already have a Lovelio account. Go to Settings -> API keys and create a key.
• You are an agent signing up a new agency. Call POST https://us.lovelio.ai/v1/accounts/signup with the agency details - on the regional domain where the agency should live, since signup creates the workspace in that region. The response includes a live trial API key. See Sign up a customer.

Install

The only thing any client needs is the server URL:

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.

However you add it, the first call opens a browser page asking for your Lovelio API key. Paste it once; Lovelio encrypts it and issues OAuth tokens that your client refreshes automatically.

Any client that supports the MCP spec 2025-06-18 or later completes OAuth on its own via the published metadata:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server

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 human pastes the Lovelio API key there, once.
4. The client exchanges the code at POST /api/oauth/token for an access token (1 hour) and a refresh token (30 days). Tokens are stored hashed; the API key is encrypted at rest.
5. Every MCP call carries the access token. The client refreshes it in the background. Disconnecting revokes at POST /api/oauth/revoke.

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 mirror the V1 REST API and the in-app action registry, so an agent runs the whole agency desk. Read tools are named list_* and get_*; write tools are named after the action they perform (create_client, move_stage, and so on). Every write goes through the same V1 route and permissions as the dashboard. The full REST surface is documented in the OpenAPI reference.

Grouped by area, with the scope each needs:

• Clients (clients:read / clients:write) - list_clients, get_client, create_client, update_client, add_client_contact, update_client_contact, add_client_dna_note. Your own agency (the self-client used for internal hiring) is hidden from list_clients.
• Jobs (jobs:read / jobs:write) - list_jobs, get_job, get_job_summary, get_job_ranking, get_job_share_bundle, create_job, create_job_from_description (+ the draft tools), update_job, close_job, reopen_job, and the job-ad / social-draft tools. Every job needs a client_id (get one from list_clients or create_client).
• Candidates (candidates:read / candidates:write) - list_candidates, get_candidate, create_candidate, update_candidate, search_candidates.
• Applications (applications:read / applications:write) - list_applications, get_application, move_stage, reject_candidate, withdraw_application, add_note, log_offer.
• Submissions (submissions:read / submissions:write) - list_submissions, get_submission, create_submission, chase_submission, answer_submission_question.
• Interviews (interviews:read / interviews:write) - list_interviews, get_interview, schedule_interview, reschedule_interview, cancel_interview, update_interview_outcome, submit_scorecard.
• Placements (placements:read / placements:write) - list_placements, get_placement, create_placement, mark_placement_status. In the agency model the client owns the offer document; log_offer (in Applications) is the stage marker.
• Talent pools (talent_pools:write / candidates:write) - create_talent_pool, add_to_talent_pool, remove_from_talent_pool.
• Comms (emails:write) - send_email. Outbound email is off by default (see below).
• Account + admin - get_account_overview, get_transcription_usage, get_company_intelligence, refresh_company_intelligence, invite_team_member, create_webhook, search, list_activities.
• Batch - batch runs up to 100 of any of the above actions in one call, each with its own idempotency key.

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

Every tool call consumes one V1 API 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

• "Invalid API key" on the connect page. Check the key in Settings -> API keys. Trial keys expire; create a fresh one if yours has.
• 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 access token" 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.