MCP quickstart

Lovelio ships a Model Context Protocol server at https://www.lovelio.ai/api/mcp. Connect Claude Desktop, Claude Code, or any MCP-aware client and run your recruiting desk with natural language.

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://www.lovelio.ai/v1/accounts/signup with the agency details. The response includes a live trial API key. See Sign up a customer.

Install (Claude Code)

claude mcp add --transport http lovelio https://www.lovelio.ai/api/mcp

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.

Confirm it connected:

claude mcp list

Install (Claude Desktop)

Settings -> Connectors -> Add custom connector, with URL https://www.lovelio.ai/api/mcp.

Install (generic MCP client)

Clients that take a JSON config block (Cursor and most others):

{
  "mcpServers": {
    "lovelio": {
      "url": "https://www.lovelio.ai/api/mcp"
    }
  }
}

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.

Claude calls list_jobs and returns a table.

Or an action:

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

Claude will draft the job with create_job_from_description, ask which client the job is for, and confirm 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 lovelio.ai in your MCP client and reconnect. Local dev builds should point at http://localhost:3005/api/mcp.
• Rate limit 429. Back off and retry after the Retry-After interval.