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

# MCP server

> Connect Leadey to Claude, ChatGPT and other AI assistants, so they can read and update your CRM as you.

Leadey speaks the [Model Context Protocol](https://modelcontextprotocol.io). Connect it once and an assistant can answer "which deals slipped this week, and who should I call first?" from your actual pipeline — then log the call, move the deal and set the follow-up without you opening a tab.

**Endpoint**

```
https://backend.leadey.ai/mcp
```

## How it differs from an API key

The REST API authenticates a *machine*: a key belongs to your workspace and carries a blanket read or read-and-write scope. The MCP server authenticates a *person*. You sign in with your Leadey account, and every tool then enforces your own permissions — the same ones the Cockpit enforces.

|             | REST API                     | MCP server                    |
| ----------- | ---------------------------- | ----------------------------- |
| Identity    | An API key                   | Your Leadey login             |
| Permissions | Read, or read and write      | Exactly what your role allows |
| Workspace   | Fixed to the key's workspace | Any workspace you belong to   |
| Best for    | Integrations and pipelines   | Working through an assistant  |

Nothing an assistant does through MCP is something you could not do yourself. If your role cannot delete opportunities, neither can it.

## Connecting

<Tabs>
  <Tab title="Claude">
    In **Settings → Connectors → Add custom connector**, paste the endpoint above and click **Connect**. A Leadey sign-in opens; approve it, and the tools appear.

    From the command line:

    ```bash theme={"dark"}
    claude mcp add --transport http leadey https://backend.leadey.ai/mcp
    ```
  </Tab>

  <Tab title="ChatGPT">
    In **Settings → Connectors → Create**, paste the endpoint above, choose **OAuth** for authentication, and complete the Leadey sign-in.
  </Tab>

  <Tab title="Anything else">
    Any client that supports remote MCP servers over HTTP with OAuth will work. Point it at the endpoint; it discovers the rest from `/.well-known/oauth-protected-resource/mcp`.
  </Tab>
</Tabs>

## If you are in more than one workspace

A Leadey login can belong to several workspaces, and your sign-in does not say which one you mean. Ask a question and the assistant will list them and ask — answer once and it carries that choice through the conversation.

This is deliberate. These are different companies' data, and a server that guessed would eventually guess wrong.

## What it can do

<AccordionGroup>
  <Accordion title="Find people and companies">
    `search_leads`, `get_lead`, `get_lead_timeline`, `get_lead_activities`, `search_companies`, `search_contacts`, `list_lead_statuses`, `list_workspaces`

    The timeline is **person-scoped**: calls, emails, texts, meetings and notes for the human, across every campaign they appear in — not just the one row you searched. Call recordings are never returned, only whether one exists.
  </Accordion>

  <Accordion title="Pipeline">
    `list_pipelines`, `search_opportunities`, `get_pipeline_metrics`, `create_opportunity`, `update_opportunity`, `move_opportunity_stage`, `win_opportunity`, `lose_opportunity`

    Money comes back as a decimal **string** beside a currency code, never a JSON number, and a workspace with deals in two currencies is reported per currency.
  </Accordion>

  <Accordion title="Daily work">
    `list_tasks`, `create_task`, `complete_task`, `log_call`, `add_note`, `log_activity`, `list_activity_types`, `create_lead`, `update_lead`, `set_lead_status`

    `log_call` records a call that already happened — it does not dial anyone.
  </Accordion>

  <Accordion title="Reporting">
    `get_metrics_summary`, `get_call_metrics`, `get_meeting_metrics`, `get_pipeline_metrics`

    Each takes a window (30 days by default, 62 maximum) and an optional `groupBy` of day, week, rep or campaign.
  </Accordion>

  <Accordion title="Campaigns">
    `list_campaigns`, `add_leads_to_campaign`
  </Accordion>
</AccordionGroup>

## The one to be careful with

<Warning>
  **`add_leads_to_campaign` starts real outreach.** Every lead added fires the campaign's entry trigger, so any sequence on it begins sending email, SMS or LinkedIn messages to those people. It is not a filing action.

  It is capped at 50 leads per call and the tool description says plainly what it does, so an assistant should confirm the campaign and the list with you first. Check both before you approve it.
</Warning>

## Repeating a call

Some tools are safe to retry and some are not, and the distinction matters when an assistant is unsure whether a call went through.

* **`create_lead` is safe.** It deduplicates on the person across your whole workspace and returns `alreadyExists: true` on a repeat rather than a second row.
* **`create_task`, `log_call`, `add_note`, `log_activity` and `create_opportunity` are not.** A repeat creates a second record. Confirm before retrying rather than calling again.

## Ids are never guessable

Every tool that acts on something takes an id, and those ids come from other tools: a `leadId` from `search_leads`, a `stageId` from `list_pipelines`, a status key from `list_lead_statuses`. An invented id is refused rather than matched to something close.