MCP Server

Connect Claude Code, Claude Desktop, Cursor, Codex, or any MCP client directly to Leonar using the Model Context Protocol.

Leonar exposes a native Model Context Protocol (MCP) server that lets AI assistants call Leonar tools and read contextual resources directly.

AI Assistant  →  MCP Protocol  →  Leonar MCP Server  →  Leonar CRM data

Quick start

1. Choose your setup

• Claude Desktop / Claude.ai / Claude remote connector (recommended): use the hosted MCP endpoint directly. No Leonar API key is required; Claude redirects you to Leonar and you authorize one workspace via OAuth.
• Claude Code / Codex / Cursor / generic MCP clients that do not support OAuth remote connectors: use either Direct HTTP with a Bearer API key, or the local @leonar/mcp NPX bridge.

2. Configure your MCP client

For Claude Desktop, prefer the remote connector tab below. The NPX package is only for local/API-key clients that need a stdio command.

Claude remote connector (recommended)

In Claude Desktop or Claude.ai, go to Settings / Customize > Connectors, choose Add custom connector, and enter the Leonar MCP endpoint:

https://app.leonar.app/api/mcp

When Claude connects without a token, Leonar advertises its OAuth metadata automatically. Claude opens Leonar’s sign-in page, you choose the workspace to share, and Leonar returns an OAuth access token scoped to that workspace.

For Claude Desktop and Claude.ai, enter exactly https://app.leonar.app/api/mcp. Do not use another host, path, or any API key query parameter; Claude handles authorization through OAuth.

For Team and Enterprise Claude plans, an organization owner may need to add the custom connector first. Members can then connect and enable it individually.

NPX package (local/API-key fallback)

Use this only for MCP clients that need a local stdio command and cannot use Claude’s remote OAuth connector. Create a leo_... API key first in Settings > API.

Claude Code (.mcp.json)

{
  "mcpServers": {
    "leonar": {
      "command": "npx",
      "args": ["-y", "@leonar/mcp"],
      "env": {
        "LEONAR_API_KEY": "leo_your_api_key"
      }
    }
  }
}

Requires Node.js 18+. The package (@leonar/mcp) is a lightweight bridge that forwards MCP messages to the Leonar server over Streamable HTTP while preserving stdio request order. It authenticates with a Leonar API key, unlike the Claude remote connector OAuth flow.

Direct HTTP

If your MCP client supports the url transport type, you can connect directly without any package:

https://app.leonar.app/api/mcp

Claude Code (.mcp.json)

{
  "mcpServers": {
    "leonar": {
      "type": "url",
      "url": "https://app.leonar.app/api/mcp",
      "headers": {
        "Authorization": "Bearer leo_your_api_key"
      }
    }
  }
}

3. Start using tools

Once connected, your AI assistant has access to the same safe workflow tools used by Leonar’s integrated AI agent, plus 4 contextual resources. Ask it things like:

• “Search for backend engineers in Paris”
• “Show me the context for the Senior PM project”
• “Find sourcing candidates for this project”
• “Find companies hiring Account Executives and identify their sales leaders”
• “Find recent LinkedIn posts about hiring in France”

Sourcing with LinkedIn locations

For LinkedIn Sales Navigator or Recruiter location filters, first ask Leonar for selectable location options, then pass the selected option into search_candidates:

{
  "tool": "sourcing_search_location_options",
  "input": { "query": "Paris", "apiType": "auto" }
}

Then use the selected LinkedIn location ID:

{
  "tool": "search_candidates",
  "input": {
    "projectName": "VP Sales France",
    "filters": {
      "titles": { "include": ["VP Sales", "Head of Sales"], "scope": "current" },
      "locations": {
        "include": [{
          "label": "Paris, Île-de-France, France",
          "country": "France",
          "linkedin": {
            "id": "90009633",
            "label": "Paris, Île-de-France, France",
            "apiType": "sales_navigator",
            "accountId": "connected-account-id-from-options"
          }
        }]
      },
      "keywordBoolean": { "query": "(SaaS OR B2B) AND \"Enterprise Sales\"" },
      "crm": { "excludeAlreadyInProject": true, "hideAlreadyTreated": true }
    }
  }
}

If a LinkedIn candidate search includes a plain-text location without a selected LinkedIn option, search_candidates returns status: "needs_location_selection" instead of silently running a degraded LinkedIn search.

Business-development prospecting

The MCP server exposes generic LinkedIn signal tools. Tool names describe the resource being searched rather than one fixed use case:

{
  "tool": "search_linkedin_jobs",
  "input": {
    "keywords": "Account Executive",
    "location": "Paris",
    "limit": 10
  }
}

{
  "tool": "search_linkedin_posts",
  "input": {
    "keywords": "\"we're hiring\" OR \"nous recrutons\"",
    "date_posted": "past_week",
    "author_location": "France",
    "limit": 10
  }
}

search_linkedin_posts resolves author profiles with bounded concurrency when author_location is provided. Results from both tools use stable normalized objects instead of provider-specific payloads.

To find the relevant people after detecting a company signal, call find_company_decision_makers with the target project, company, and roles.

Safe project and sequence enrollment

Prospecting writes use a two-step flow:

1. preview_prospecting_enrollment checks CRM duplicates, existing project entries, and existing sequence enrollments. It performs no contact, pipeline, or enrollment mutation.
2. commit_prospecting_enrollment accepts the preview ID, an explicit confirm: true, and a UUID idempotency_key. It creates or reuses contacts, adds them to the project, and enrolls them in the active sequence.

Previews expire after 30 minutes. Repeating a successful commit with the same idempotency key returns the stored receipt instead of duplicating work.

Authentication

Leonar supports two authentication modes for MCP:

• OAuth for Claude remote connectors. This is the recommended path for Claude Desktop and Claude.ai. Claude discovers Leonar’s OAuth metadata automatically from the MCP endpoint, redirects you to Leonar, and receives an access token scoped to one workspace.
• Bearer API keys for local/API-key clients such as Claude Code, Codex, Cursor, and generic MCP clients that do not use the OAuth connector flow.

For API-key clients, the MCP server uses the same leo_ API keys as the REST API. Pass your key as a Bearer token in the Authorization header.

Authorization: Bearer leo_your_api_key

Each tool requires specific scopes. If the API key lacks a required scope, the tool returns an error. See the scopes reference for the full list.

Use the minimum scopes your assistant needs. For read-only exploration, start with contacts:read, projects:read, and companies:read.

High-impact mutations should be handled carefully by MCP clients. For business-development prospecting, always show the result of preview_prospecting_enrollment and ask for confirmation before calling commit_prospecting_enrollment.

Transport

The MCP server uses Streamable HTTP transport over a single endpoint (POST /api/mcp). It is stateless — no session management is required. All MCP clients that support the url transport type can connect directly.

For custom HTTP clients or manual tests, include both accepted response types:

Accept: application/json, text/event-stream
Authorization: Bearer leo_your_api_key
Content-Type: application/json

The NPX bridge sets these headers automatically.

Available resources

The server also exposes these read-only resources:

Resource URI	Description
leonar://workspace/context	Workspace metadata, billing state, and lightweight counters
leonar://accounts/connected	Active connected accounts available for sending and sourcing
leonar://team/members	Workspace members and roles
leonar://pipeline/templates	Pipeline templates with their stages

Available tools

The MCP server exposes the main CRM API resources as explicit tools. The recommended sourcing workflow is exposed through agent-friendly tools that mirror the unified UI flow without exposing Leonar’s internal filter model. Assistant memory tools are not exposed over external MCP.

Object	Tools	Scopes

| Recommended candidate sourcing | get_project_sourcing_context, search_candidates, continue_candidate_search, sourcing_search_location_options, sourcing_search_school_options, sourcing_reject_profiles | projects:read, sourcing:read, sourcing:write | | LinkedIn prospecting signals | search_linkedin_jobs, search_linkedin_posts, find_company_decision_makers | sourcing:read, plus projects:read/sourcing:write for decision-maker searches | | Prospecting enrollment | preview_prospecting_enrollment, commit_prospecting_enrollment | Read scopes for preview; contacts:write, pipeline:write, sequences:write for commit | | Contacts | search_contacts, get_contact, create_contact, update_contact, delete_contact | contacts:read, contacts:write, contacts:delete | | Companies | search_companies, get_company, create_company, update_company, delete_company | companies:read, companies:write, companies:delete | | Projects | search_projects, get_project, create_project, update_project, delete_project, add_contact_to_project | projects:read, projects:write, pipeline:write | | Sequences | search_sequences, get_sequence, get_sequence_steps, update_sequence_steps, list_sequence_enrollments, enroll_contacts_in_sequence, unenroll_contacts_from_sequence | sequences:read, sequences:write | | Deals | search_deals, get_deal, create_deal, update_deal, delete_deal | deals:read, deals:write, deals:delete | | Notes | search_notes, create_note, update_note, delete_note | notes:read, notes:write |

Delete tools archive records when the API resource supports soft deletion. Notes are deleted from their note table.

Tool parameters reference

Common read parameters

// get_* and delete_* tools
{
  id: string
}

// search_* tools
{
  search?: string
  limit?: number // max 100
  offset?: number
}

Contacts

// search_contacts also accepts:
{
  company_id?: string
  location?: string
}

// create_contact / update_contact
{
  first_name: string
  last_name?: string
  title?: string
  current_company?: string
  location?: string
  linkedin_profile?: string
  emails?: { email: string; type?: "work" | "personal" }[]
  phones?: { phone: string; type?: "work" | "personal" }[]
  contact_type?: string[]
  tags?: string[]
  source?: string
  summary?: string
  company_id?: string
  custom_data?: Record<string, unknown>
}

Companies

// search_companies also accepts:
{
  industry?: string
  owner_id?: string
}

// create_company / update_company
{
  name: string
  domain?: string
  industry?: string
  company_size?: string
  description?: string
  location?: string
  phone?: string
  linkedin_url?: string
  owner_id?: string
  custom_data?: Record<string, unknown>
}

Projects

// search_projects also accepts:
{
  status?: "active" | "archived" | "all"
}

// create_project / update_project
{
  name: string
  client_name?: string
  client_company_id?: string
  owner_ids?: string[]
  template_id?: string
  location?: string
  description?: string
}

// add_contact_to_project
{
  project_id: string
  contact_id: string
  stage_id?: string // defaults to the first stage
}

Sequences

// search_sequences also accepts:
{
  status?: "active" | "paused" | "draft" | "archived" | "all"
}

// list_sequence_enrollments
{
  sequence_id: string
  status?: "active" | "paused" | "pending" | "finished" | "replied" | "bounced" | "all"
  search?: string
  limit?: number
  offset?: number
}

// enroll_contacts_in_sequence
{
  sequence_id: string
  contact_ids?: string[]
  contacts?: {
    contact_id: string
    custom_variables?: {
      custom_variable_1?: string | null
      custom_variable_2?: string | null
      custom_variable_3?: string | null
      custom_variable_4?: string | null
      custom_variable_5?: string | null
    }
  }[]
}

// unenroll_contacts_from_sequence
{
  sequence_id: string
  contact_ids: string[]
  reason?: string
}

Deals

// search_deals also accepts:
{
  status?: "open" | "won" | "lost" | "unqualified" | "all"
  company_id?: string
  owner_id?: string
}

// create_deal / update_deal
{
  title: string
  company_id: string
  pipeline_id?: string
  stage_id?: string
  contact_id?: string
  project_id?: string
  owner_id?: string
  primary_source_id?: string | null
  amount?: number
  currency?: string
  expected_amount?: number
  expected_close_date?: string
  probability?: number
  custom_data?: Record<string, unknown>
}

Notes

// search_notes
{
  entity_type?: "contact" | "company" | "deal" | "project"
  entity_id?: string
  search?: string
  limit?: number
  offset?: number
}

// create_note
{
  entity_type: "contact" | "company" | "deal" | "project"
  entity_id: string
  content: string
  is_pinned?: boolean
  project_id?: string
}

// update_note
{
  id: string
  entity_type: "contact" | "company" | "deal" | "project"
  content?: string
  is_pinned?: boolean
}

Example use cases

CRM lookup

“Find contacts at Acme and summarize their current roles.”

The assistant calls search_contacts and reads the returned contact records.

Pipeline preparation

“Create a project for our new backend role and attach Acme as the client company.”

The assistant can use search_companies then create_project.

Deal update

“Update this deal amount and expected close date.”

Uses update_deal with the same API key scopes as the REST API.

Meeting note

“Add this call summary to the company record.”

Uses create_note with entity_type: "company".

Rate limits

The MCP server shares the same base rate limit as the REST API: 2000 requests per hour.

• For API-key clients, the quota is tracked per API key.
• For Claude remote connectors, the quota is tracked per OAuth authorization (client + workspace + user). Refreshing an access token does not reset the quota.

Each tool call counts as one request.

MCP vs REST API

	MCP Server	REST API
Best for	AI assistants (Claude, Cursor, Codex)	Custom integrations, scripts
Protocol	Model Context Protocol	HTTP REST
Auth	OAuth for Claude remote connectors; leo_ API keys for local/API-key MCP clients	Same leo_ API keys
Scopes	Same scope system	Same scope system
Tools	Main CRM object tools, project pipeline entry tools, sequence enrollment tools + 4 resources	60+ endpoints (full CRUD)

Use the MCP server when connecting an AI assistant. Use the REST API when building custom integrations or scripts that need full CRUD access to all resources.