> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Overview

> Connect your AI assistant to Kalent's talent database using the Model Context Protocol (MCP).

## What is the Kalent MCP Server?

Find and contact top talent without leaving your AI workspace.

Search +200M professional profiles with AI-powered matching, access verified emails and mobile numbers, and launch personalized outreach campaigns effortlessly. Built for recruiting firms, staffing agencies, and HR teams, Kalent delivers up to 60% reply rates powered by 50+ data sources.

Discover developers, sales reps, accountants, or any role worldwide. Research candidates, build strong talent pipelines, and fill positions faster — all directly within your favorite AI assistant.

Turn any LLM into a full recruiting platform with Kalent.

<CardGroup cols={2}>
  <Card title="Natural language search" icon="message-bot">
    Describe the talent you need in everyday language — the AI translates your
    request into structured filters automatically.
  </Card>

  <Card title="Rich profile data" icon="address-card">
    Get full professional profiles including experience, education, skills,
    languages, and certifications.
  </Card>
</CardGroup>

## API vs MCP — When to use what

|                        | REST API                                              | MCP Server                                                        |
| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
| **Interface**          | HTTP endpoints with JSON payloads                     | AI assistant (Claude, Cursor, etc.)                               |
| **Authentication**     | API key via header                                    | OAuth 2.0 (one-time browser flow)                                 |
| **How you search**     | Build a JSON filter array                             | Describe the candidate in natural language                        |
| **Best for**           | Programmatic integrations, ATS pipelines, automations | Interactive sourcing, ad-hoc searches, conversational exploration |
| **Filter translation** | You build the filters manually                        | The AI builds them for you from your prompt                       |

Use the **REST API** when you need to integrate Kalent into your own software. Use the **MCP server** when you want to search talent interactively from an AI assistant like Claude.

***

## Setup with Claude

You can add Kalent to Claude in one click from **Settings → MCP Connection** in the Kalent app: the **Add to Claude** button opens Claude with the Kalent connector pre-filled. To add it manually, follow the steps below.

<Steps>
  <Step title="Open Claude settings">
    In Claude Desktop or on [claude.ai](https://claude.ai/customize/connectors), open **Settings → Connectors**.
  </Step>

  <Step title="Add a custom connector">
    Click **Add custom connector** and enter the following server URL:

    ```
    https://app.kalent.ai/api/mcp
    ```
  </Step>

  <Step title="Authenticate via OAuth">
    Claude will redirect you to Kalent's login page. Sign in with your Kalent credentials and authorize the connection. Once approved, you are redirected back to Claude — the connector is now ready to use.
  </Step>
</Steps>

<Info>
  The OAuth flow uses **OAuth 2.0 with PKCE**. Your AI client handles the entire
  handshake automatically — you only need to sign in and click **Authorize**.
</Info>

***

## Setup with Cursor

You can add Kalent to Cursor in one click from **Settings → MCP Connection** in the Kalent app: the **Add to Cursor** button opens Cursor and prompts you to install the Kalent MCP server. To add it manually, follow the steps below.

<Steps>
  <Step title="Open the MCP settings">
    In Cursor, open **Settings → MCP** (or **Tools & Integrations → MCP**) and click **Add custom MCP server**.
  </Step>

  <Step title="Add the Kalent server">
    Add the following entry to your `mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "Kalent": {
          "url": "https://app.kalent.ai/api/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate via OAuth">
    Cursor opens a browser window to Kalent's login page. Sign in and authorize the connection — the server then shows as connected in Cursor.
  </Step>
</Steps>

***

## Setup with ChatGPT

<Steps>
  <Step title="Enable Developer Mode">
    In ChatGPT, go to **Settings** → **Connectors** → **Advanced** and enable **Developer Mode**.
  </Step>

  <Step title="Add the Kalent connector">
    Add a new app with the following URL:

    ```
    https://app.kalent.ai/api/mcp
    ```
  </Step>

  <Step title="Authenticate">
    Complete the Kalent authentication flow. Once approved, the connector is ready to use.
  </Step>
</Steps>

***

## Authentication

The Kalent MCP server uses **OAuth 2.0** to authenticate your AI assistant. This is different from the REST API, which uses a static API key.

### How it works

1. Your AI client (Claude, Cursor, etc.) connects to `https://app.kalent.ai/api/mcp`.
2. The server responds with a `401` and points to its OAuth metadata.
3. The client opens a browser window where you sign in to Kalent.
4. You see a consent screen asking you to authorize the connection to your workspace.
5. After clicking **Authorize**, the client receives an access token and the MCP session starts.

The entire flow is handled transparently by your AI client. You only interact with the Kalent login and consent pages.

<Warning>
  Each MCP session is scoped to a single Kalent workspace. If you have access to
  multiple workspaces, the connection uses the workspace associated with your
  API key.
</Warning>

***

## Available Tools

The Kalent MCP server exposes search, sourcing, enrichment, and outreach sequence tools.

<CardGroup cols={2}>
  <Card title="search_talents" icon="magnifying-glass" href="/mcp/search-talents">
    Search the Kalent talent database using natural language.
  </Card>

  <Card title="search_talents_with_filters" icon="filter" href="/mcp/search-talents-with-filters">
    Search with structured filters directly.
  </Card>

  <Card title="create_sourcing" icon="briefcase" href="/mcp/create-sourcing">
    Create an empty sourcing campaign.
  </Card>

  <Card title="add_talent_to_sourcing" icon="user-plus" href="/mcp/add-talent-to-sourcing">
    Attach a talent to a sourcing as a candidate.
  </Card>

  <Card title="create_sequence_blueprint" icon="diagram-project" href="/mcp/create-sequence-blueprint">
    Create a manual outreach sequence blueprint.
  </Card>

  <Card title="get_dynamic_sequences" icon="list" href="/mcp/get-dynamic-sequences">
    List sequence blueprints for a sourcing.
  </Card>

  <Card title="update_sequence_blueprint" icon="pen-to-square" href="/mcp/update-sequence-blueprint">
    Update sequence blueprint steps or configuration.
  </Card>

  <Card title="start_dynamic_sequences" icon="paper-plane" href="/mcp/start-dynamic-sequences">
    Start outreach sequences for candidates.
  </Card>

  <Card title="enrich_candidate_contacts" icon="address-book" href="/mcp/enrich-candidate-contacts">
    Start contact enrichment for a candidate.
  </Card>

  <Card title="enrich_linkedin_contacts" icon="linkedin" href="/mcp/enrich-linkedin-contacts">
    Start LinkedIn contact enrichment for a talent.
  </Card>

  <Card title="get_contact_enrichment_result" icon="square-poll-horizontal" href="/mcp/get-contact-enrichment-result">
    Read enrichment results for a talent.
  </Card>

  <Card title="get_sourcings" icon="briefcase" href="/mcp/get-sourcings">
    List paginated sourcings for the workspace.
  </Card>

  <Card title="get_candidates" icon="users" href="/mcp/get-candidates">
    List paginated candidates for a sourcing.
  </Card>

  <Card title="get_candidate" icon="id-card" href="/mcp/get-candidate">
    Resolve candidate and talent details.
  </Card>

  <Card title="get_candidate_dynamic_sequence_status" icon="chart-line" href="/mcp/get-candidate-dynamic-sequence-status">
    Read dynamic sequence progress for a candidate.
  </Card>
</CardGroup>

<Info>
  Search results are **non-deterministic by design** — identical requests may
  return different results due to real-time profile enrichment, AI-powered
  scoring, and continuous indexing. Learn more in the [Non-deterministic
  Results](/mcp/non-deterministic-results) guide.
</Info>

***

## Example Prompts

Once connected, you can search for talent by simply describing what you need. Here are some examples:

<AccordionGroup>
  <Accordion title="Find software engineers from OpenAI">
    **Prompt:**

    > Find software engineers who have worked at OpenAI for at least 3 years.

    The AI will create filters for:

    * `JOB_TITLE` = "Software Engineer"
    * `COMPANY_NAME` = "OpenAI" with `history` = "CURRENT\_AND\_PAST"
    * `DURATION_IN_JOB` = "3-5" (or higher)
  </Accordion>

  <Accordion title="Marketing talent in Paris">
    **Prompt:**

    > I need to find talent in Paris (within 20km radius) with expertise in SEO and marketing strategies.

    The AI will create filters for:

    * `LOCATION` = "Paris" with `radius` = 20
    * `SKILL` = "SEO"
    * `SKILL` = "Marketing Strategy"
  </Accordion>

  <Accordion title="Senior UX designers from YC startups">
    **Prompt:**

    > Find talent with 10+ years of experience as a UX designer who has worked for a YC startup.

    The AI will create filters for:

    * `JOB_TITLE` = "UX Designer"
    * `YEARS_OF_EXPERIENCE` = "10-15" (or higher)
    * `KEYWORD` = "Y Combinator"
  </Accordion>
</AccordionGroup>

<Tip>
  **About location radius:** The radius parameter is always in **kilometers**.
  If you mention miles in your prompt (e.g., "within 10 miles"), the AI will
  automatically convert to kilometers before making the search. You don't need
  to worry about unit conversion.
</Tip>

***

## Response Format

For each search, the MCP server returns two content blocks:

1. **Structured JSON** — Complete profile data (experiences, educations, skills, languages, certifications) that the AI uses for reasoning and follow-up questions.
2. **Markdown table** — A formatted summary with name, job title, company, location, and LinkedIn profile link, displayed directly in the conversation.

Up to **5 matching profiles** are returned per search.

## Subscription and plan errors

When a tool is blocked because the workspace has no eligible Kalent subscription or needs a higher plan, the MCP response is marked as an error and tells the AI assistant to ask the user to subscribe or upgrade before retrying. The message also includes the billing URL:

```text theme={null}
A Kalent subscription or plan upgrade is required to create sourcings.

Ask the user to subscribe or upgrade their Kalent plan before retrying. They can manage billing here: https://app.kalent.ai/settings/billing
```

***

## Supported AI Clients

The Kalent MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io) standard and is compatible with any MCP-compliant client, including:

* **Claude Desktop** — Full OAuth support with built-in connector management
* **Claude Code** — Add via CLI: `claude mcp add --transport http kalent https://app.kalent.ai/api/mcp`
* **ChatGPT** — Enable Developer Mode in Settings → Connectors → Advanced, then add the app URL
* **Cursor** — Configure as a custom MCP server in settings
* Any other MCP-compatible AI client