MCP Server - Leonar API

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)
NPX package (local/API-key fallback)
Direct HTTP

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.

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.

{
  "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.

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

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

{
  "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”

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.

Approval-gated mutations used by the in-app agent (for example project creation or launching sourcing directly into a pipeline) are intentionally not exposed over external MCP until a reviewed approval flow is available for third-party MCP clients.

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. Advanced sourcing and assistant memory tools are not exposed over external MCP.

Object	Tools	Scopes
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
  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"
  entity_id?: string
  search?: string
  limit?: number
  offset?: number
}

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

// update_note
{
  id: string
  entity_type: "contact" | "company" | "deal"
  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.

​Quick start

​1. Choose your setup

​2. Configure your MCP client

​3. Start using tools

​Authentication

​Transport

​Available resources

​Available tools

​Tool parameters reference

​Common read parameters

​Contacts

​Companies

​Projects

​Sequences

​Deals

​Notes

​Example use cases

CRM lookup

Pipeline preparation

Deal update

Meeting note

​Rate limits

​MCP vs REST API

Quick start

1. Choose your setup

2. Configure your MCP client

3. Start using tools

Authentication

Transport

Available resources

Available tools

Tool parameters reference

Common read parameters

Contacts

Companies

Projects

Sequences

Deals

Notes

Example use cases

Rate limits

MCP vs REST API