docs(mcp): all-clients installation page + slimmer quickstart

SUMMARY.md

@@ -21,6 +21,7 @@
 
 * [What is Leadbay MCP?](leadbay-mcp/what-is-leadbay-mcp.md)
 * [Quickstart](leadbay-mcp/quickstart.md)
+* [Installation](leadbay-mcp/installation.md)
 * [Tools reference](leadbay-mcp/tools-reference.md)
 * [Example prompts](leadbay-mcp/example-prompts.md)
 

leadbay-mcp/installation.md

@@ -0,0 +1,217 @@
+# Installation
+
+Step-by-step setup for every assistant that works with Leadbay. Pick your client below — each takes a couple of minutes, and **none of them need an API token**. You add one server URL, sign in once with your Leadbay account, and you're connected.
+
+{% hint style="info" %}
+**Before you start, you need:**
+
+- A [Leadbay account](https://leadbay.ai/) (the same login you use for the web app).
+- One of the assistants below: **Claude.ai**, **Claude Desktop**, **Claude Code**, **ChatGPT**, or **Codex**.
+
+Everywhere a server URL is asked for, it's:
+
+```
+https://mcp.leadbay.app/mcp
+```
+
+Sign-in is handled by your browser (OAuth) — there are no tokens to copy or paste.
+{% endhint %}
+
+{% hint style="warning" %}
+**US vs EU accounts.** If your Leadbay account is on the **EU** instance, use `https://mcp.leadbay.app/fr/mcp` instead of `https://mcp.leadbay.app/mcp`. When in doubt, the US URL works for most accounts — a valid login is routed to whichever backend owns it.
+{% endhint %}
+
+---
+
+## Claude.ai (web)
+
+Add Leadbay as a **custom connector**.
+
+**1. Open the Add custom connector form.** Click this link (or in Claude, go to **Settings → Connectors**, then the **+** next to the search bar → **Add custom connector**):
+
+{% hint style="info" %}
+[https://claude.ai/customize/connectors?modal=add-custom-connector](https://claude.ai/customize/connectors?modal=add-custom-connector)
+{% endhint %}
+
+<figure><img src="../.gitbook/assets/claude-02-connectors-plus-menu.png" alt="Connectors + menu with Add custom connector"><figcaption><p>The + menu → Add custom connector</p></figcaption></figure>
+
+**2. Fill in the fields and click Add:**
+
+- **Name:** `Leadbay`
+- **URL:** `https://mcp.leadbay.app/mcp`
+
+Leave the Advanced settings as they are (Individual sign-in is fine).
+
+<figure><img src="../.gitbook/assets/claude-01-add-custom-connector-form.png" alt="Add custom connector form with Leadbay name and URL"><figcaption><p>Name it Leadbay, paste the URL, click Add</p></figcaption></figure>
+
+**3. Find the Leadbay connector** in the directory (search "Leadbay" — it appears under **Custom connectors**) and open it.
+
+<figure><img src="../.gitbook/assets/claude-03-directory-search.png" alt="Directory search showing the Leadbay custom connector"><figcaption><p>Your new Leadbay custom connector</p></figcaption></figure>
+
+**4. Click Connect** and sign in. A **Sign in with Leadbay** page opens — log in and approve. The connector shows as connected, and the Leadbay tools are available in your chats.
+
+<figure><img src="../.gitbook/assets/claude-04-connect.png" alt="Leadbay connector with the Connect button"><figcaption><p>Click Connect, then sign in with Leadbay</p></figcaption></figure>
+
+{% hint style="warning" %}
+**Not an admin of your organization?** Members can't add a custom connector themselves — your **workspace admin** needs to add the Leadbay connector first (steps 1–2 above). Once the admin has added it, you'll find it in the directory and can **Connect** (steps 3–4).
+{% endhint %}
+
+{% hint style="info" %}
+Custom connectors require a paid Claude plan (Pro, Max, Team, or Enterprise).
+{% endhint %}
+
+---
+
+## Claude Desktop
+
+Claude Desktop connects to Leadbay exactly like Claude.ai — same **custom connector**, same URL.
+
+1. Open **Settings → Connectors**, click the **+** → **Add custom connector**.
+2. Enter **Name** `Leadbay` and **URL** `https://mcp.leadbay.app/mcp`, then click **Add**.
+3. Open the **Leadbay** connector and click **Connect** — sign in with Leadbay in your browser.
+4. Open a new chat and wait a few seconds for the Leadbay tools to load before your first message.
+
+{% hint style="info" %}
+If your first message gets _"I don't see any Leadbay tools"_, the tools are still loading. Send any second message (even just _"try again"_) and Claude will pick them up. As with Claude.ai, if you're not an org admin, the admin must add the connector first.
+{% endhint %}
+
+---
+
+## Claude Code
+
+One command registers Leadbay for every project.
+
+```bash
+claude mcp add --scope user --transport http leadbay https://mcp.leadbay.app/mcp
+```
+
+Then:
+
+1. Run `/mcp` inside Claude Code.
+2. Select **leadbay** → **Authenticate**. Your browser opens for the Leadbay sign-in.
+3. Log in and approve — the status flips to **connected** and the Leadbay tools load.
+
+{% hint style="info" %}
+If you just ran the `add` command in an open Claude Code session, restart it once so the new server shows up in `/mcp`.
+{% endhint %}
+
+Remove it anytime with `claude mcp remove leadbay -s user`.
+
+---
+
+## Codex
+
+Codex has a built-in command for remote MCP servers.
+
+```bash
+codex mcp add leadbay --url https://mcp.leadbay.app/mcp
+```
+
+Codex detects OAuth automatically and opens your browser for the **Sign in with Leadbay** flow — log in and approve. Confirm it's connected with:
+
+```bash
+codex mcp list
+```
+
+You should see `leadbay` with **Status: enabled** and **Auth: OAuth**. Remove it with `codex mcp remove leadbay`.
+
+---
+
+## ChatGPT
+
+Add Leadbay as a custom app (MCP connector) in ChatGPT.
+
+{% hint style="info" %}
+Custom MCP connectors require a paid ChatGPT plan (Plus, Pro, Business, or Enterprise) and Developer mode, which you enable in step 5 below. On Business/Enterprise an admin may need to allow custom connectors first.
+{% endhint %}
+
+**1. Open the workspace menu** (bottom-left) and click your workspace name.
+
+<figure><img src="../.gitbook/assets/chatgpt-01-workspace-menu.png" alt="ChatGPT bottom-left workspace menu"><figcaption><p>Open the workspace menu</p></figcaption></figure>
+
+**2. Click Settings.**
+
+<figure><img src="../.gitbook/assets/chatgpt-02-settings.png" alt="Workspace menu with Settings highlighted"><figcaption><p>Click Settings</p></figcaption></figure>
+
+**3. Open the Apps tab** in the Settings sidebar.
+
+<figure><img src="../.gitbook/assets/chatgpt-03-apps.png" alt="Settings sidebar with Apps highlighted"><figcaption><p>Open the Apps tab</p></figcaption></figure>
+
+**4. Click Advanced settings.**
+
+<figure><img src="../.gitbook/assets/chatgpt-04-advanced-settings.png" alt="Apps page with Advanced settings highlighted"><figcaption><p>Click Advanced settings</p></figcaption></figure>
+
+**5. Turn on Developer mode.** This is required to add a custom MCP connector.
+
+<figure><img src="../.gitbook/assets/chatgpt-05-developer-mode.png" alt="Developer mode toggle switched on"><figcaption><p>Turn on Developer mode</p></figcaption></figure>
+
+**6. Go back to Apps and click Create app.**
+
+<figure><img src="../.gitbook/assets/chatgpt-06-create-app.png" alt="Apps page with Create app highlighted"><figcaption><p>Click Create app</p></figcaption></figure>
+
+**7. Fill in the New App form:**
+
+- **Name:** `Leadbay MCP`
+- **Connection:** select **Server URL**, then enter `https://mcp.leadbay.app/mcp`
+- **Authentication:** **OAuth**
+- Check **I understand and want to continue**, then click **Create**.
+
+<figure><img src="../.gitbook/assets/chatgpt-07-new-app-form.png" alt="New App form with name, server URL, and OAuth"><figcaption><p>Name it, set the Server URL and OAuth, then Create</p></figcaption></figure>
+
+**8. Click Sign in with Leadbay MCP.** Log in and approve — ChatGPT is now connected.
+
+<figure><img src="../.gitbook/assets/chatgpt-08-sign-in.png" alt="Sign in with Leadbay MCP prompt"><figcaption><p>Sign in with Leadbay MCP</p></figcaption></figure>
+
+In a chat, enable the **Leadbay MCP** app from the composer **+** / tools menu so ChatGPT can call its tools.
+
+### If the connection has a problem
+
+If the app shows as disconnected or its tools stop responding, reconnect it:
+
+**1. Open the Leadbay MCP app** (Settings → Apps → Leadbay MCP) and click the **⋯** menu (top-right).
+
+<figure><img src="../.gitbook/assets/chatgpt-09-app-menu.png" alt="Leadbay MCP app page with the three-dot menu highlighted"><figcaption><p>Open the ⋯ menu on the Leadbay MCP app</p></figcaption></figure>
+
+**2. Click Reconnect** and sign in again.
+
+<figure><img src="../.gitbook/assets/chatgpt-10-reconnect.png" alt="App menu with Reconnect highlighted"><figcaption><p>Click Reconnect and sign in again</p></figcaption></figure>
+
+---
+
+## After you connect — your first leads
+
+Whichever client you used, open a new conversation and try:
+
+> _Show me today's leads and tell me which two are worth opening first._
+
+A successful reply is a **ranked shortlist** — each lead with a fit score, a one-line "why it fits", and the best contact. If you see that, you're fully connected. 🎉
+
+{% content-ref url="example-prompts.md" %}
+[Example prompts](example-prompts.md)
+{% endcontent-ref %}
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| "Not authenticated" / 401 errors | Your sign-in expired or was revoked. Trigger any Leadbay tool again and approve the **Sign in with Leadbay** prompt. |
+| Connected, but "show me leads" returns an empty list | You're signed in fine — there's just nothing to show right now. Ask _"show me my lenses"_ to check which audience is active, or confirm you're on the right instance (US vs EU). |
+| Wrong instance (no leads / 404s) | Sign out and sign back in on the correct instance, or use the `/fr/mcp` URL for EU accounts. |
+| Tools don't appear after connecting | Open a new chat and wait a few seconds; send a second message and the tools finish loading. |
+| Tools appear but the assistant won't call them | Open the connector settings and set the Leadbay tool groups to **Always allow** (Claude) or enable the connector in the composer (ChatGPT). |
+| Custom connector option missing (Claude.ai / Claude Desktop / ChatGPT) | Custom connectors need a paid plan, and your workspace admin may need to enable them. |
+| Other issue | File a bug at [github.com/leadbay/mcp/issues](https://github.com/leadbay/mcp/issues). |
+
+---
+
+## Where to next
+
+{% content-ref url="what-is-leadbay-mcp.md" %}
+[What is Leadbay MCP?](what-is-leadbay-mcp.md)
+{% endcontent-ref %}
+
+{% content-ref url="tools-reference.md" %}
+[Tools reference](tools-reference.md)
+{% endcontent-ref %}

leadbay-mcp/quickstart.md

@@ -1,59 +1,50 @@
 # Quickstart
 
-Connect Leadbay to Claude and get your first qualified leads in about five minutes. Pick your client, install, sign in, and ask — no coding, no tokens to copy.
+Connect Leadbay to Claude and get your first qualified leads in about five minutes. This guide uses **Claude** (Claude.ai or Claude Desktop) — the simplest path. Using a different assistant? See [Installation](installation.md) for step-by-step setup of Claude Code, ChatGPT, and Codex.
 
 {% hint style="info" %}
-You'll need a [Leadbay account](https://leadbay.ai/) and an AI assistant that supports MCP (Claude Desktop, Claude Cowork, Claude Code, or Cursor — Codex too). That's it — no API tokens to copy or paste. _ChatGPT support is coming soon._
+You'll need a [Leadbay account](https://leadbay.ai/) and Claude (Pro, Max, Team, or Enterprise). That's it — no API tokens to copy or paste; you add one URL and sign in with your browser.
 {% endhint %}
 
 ---
 
-## Step 1 — Install
+## Step 1 — Add the Leadbay connector
 
-**On Claude (Desktop / Cowork) — `.dxt` extension** (recommended):
-
-1. **[⬇ Download the Leadbay extension (.dxt)](https://github.com/leadbay/leadclaw/releases/latest/download/leadbay-latest.dxt)** — this downloads the latest version directly.
-2. **Double-click the downloaded `.dxt`.** Claude opens with the extension details — click **Install**, then toggle the extension to **Enabled**.
+1. Open the **Add custom connector** form — use this link, or in Claude go to **Settings → Connectors** → the **+** → **Add custom connector**:
+   - [https://claude.ai/customize/connectors?modal=add-custom-connector](https://claude.ai/customize/connectors?modal=add-custom-connector)
+2. Enter:
+   - **Name:** `Leadbay`
+   - **URL:** `https://mcp.leadbay.app/mcp`
+3. Click **Add**.
 
 {% hint style="info" %}
-Doesn't open Claude? Install it from inside the app: **Settings → Extensions → Advanced → Install extension**, then pick the `.dxt` file.
+On the **EU** instance, use `https://mcp.leadbay.app/fr/mcp` instead. Custom connectors require a paid Claude plan. **If you're not an admin of your organization**, your workspace admin needs to add the connector first — then you can connect to it. See [Installation](installation.md) for the full walkthrough with screenshots.
 {% endhint %}
 
-**On Claude Code, Cursor, or Codex — one-command installer** (needs [Node.js](https://nodejs.org) 22+). It also works for Claude Desktop if you'd rather automate the setup:
-
-```bash
-npx -y -p @leadbay/mcp@latest installer
-```
-
-This opens a guided wizard that detects your installed clients, adds Leadbay to the ones you pick, and runs the sign-in flow.
-
 ---
 
-## Step 2 — Sign in (this happens automatically)
-
-You don't set anything up by hand. The moment you install — or the first time Claude uses a Leadbay tool — a **Sign in with Leadbay** page **opens automatically in your browser**:
+## Step 2 — Sign in
 
-1. The Leadbay login page appears on its own.
-2. Log in (or confirm your existing session).
-3. Click **Approve** to connect Claude to your account.
-4. The tab closes itself and Claude is ready.
+1. Open the new **Leadbay** connector and click **Connect**.
+2. A **Sign in with Leadbay** page opens in your browser — log in (or confirm your existing session) and click **Approve**.
+3. The tab closes itself and Claude is connected.
 
-That's the whole connection. No tokens, no config files. Claude is now linked to **your** account, with all the leads you already have in Leadbay. You can revoke access anytime from **Settings → Connected apps**.
-
-{% hint style="info" %}
-If you have both a US and an EU account, sign in on the instance you want Claude to use. You can switch later by signing out and back in on the other instance.
-{% endhint %}
+That's the whole connection — no tokens, no config files. Claude is now linked to **your** Leadbay account, with all the leads you already have. You can revoke access anytime from **Settings → Connected apps**.
 
 ---
 
 ## Step 3 — Ask for your first leads
 
 Open a new conversation and type:
 
-> *Show me today's leads and tell me which two are worth opening first.*
+> _Show me today's leads and tell me which two are worth opening first._
 
 Claude calls your Leadbay tools and replies with a short, ranked shortlist — company, why it fits, and the best contact to reach.
 
+{% hint style="info" %}
+First message gets _"I don't see any Leadbay tools"_? The tools are still loading. Send any second message (even just _"try again"_) and Claude will pick them up.
+{% endhint %}
+
 ---
 
 ## Step 4 — What you should see
@@ -74,44 +65,23 @@ If Claude replies with leads like that, you're fully connected. 🎉
 
 Once you've seen your first leads, try these:
 
-> *Research the top one for me — is it a fit?*
+> _Research the top one for me — is it a fit?_
 
-> *Draft me an outreach email to them.*
+> _Draft me an outreach email to them._
 
-> *I just emailed them. Log it as outreach.*
+> _I just emailed them. Log it as outreach._
 
 Claude remembers the leads it surfaced, so you can keep referring to "the top one" without repeating yourself.
 
 ---
 
-## Using Leadbay with Claude Desktop
+## Using another assistant?
 
-Claude Desktop is slower than Cowork to load MCP tools, so a couple of extra precautions help.
-
-After installing the Leadbay extension, **fully quit and relaunch Claude Desktop** (Cmd-Q on Mac, then reopen — not just closing the window). Open a new chat and wait about **30 seconds** before sending your first message. This gives Claude time to load the Leadbay tools.
-
-If your first message gets a response like *"I don't see any Leadbay tools"* or *"I can't find Leadbay in your setup"*, don't worry — the tools are still loading. Send any second message (even just *"try again"*) and Claude will pick them up. From that point on, the rest of your session works normally.
-
----
-
-## Updating
-
-For the **`.dxt` extension**, when a new release ships, repeat **Step 1** (download the new `.dxt`, double-click, Install). Claude replaces the old version in place; your sign-in stays valid, so you don't need to re-authenticate.
-
-The **one-command installer** always runs the latest version — there's nothing to update.
-
----
-
-## Troubleshooting
+{% content-ref url="installation.md" %}
+[Installation](installation.md)
+{% endcontent-ref %}
 
-| Symptom | Fix |
-|---------|-----|
-| Claude says "not authenticated" or 401 errors | Your sign-in may have expired or been revoked. Trigger any Leadbay tool again and Claude will re-prompt the **Sign in with Leadbay** flow |
-| Tools don't appear after install | Make sure the extension toggle is **Enabled** in Settings → Extensions |
-| Tools appear but Claude won't call them | Open **Configure** and switch the tool groups to **Always allow** |
-| Connected, but "show me leads" returns an empty list | You're signed in fine — there's just nothing to show right now. Ask *"show me my lenses"* to confirm which audience is active and switch if needed, or check you're on the right instance (US vs EU) |
-| Wrong instance (no leads / 404s) | Sign out from the Leadbay extension and sign back in on the right instance (US or EU) |
-| Other issue | File a bug at [github.com/leadbay/leadclaw/issues](https://github.com/leadbay/leadclaw/issues) |
+Step-by-step setup for **Claude.ai**, **Claude Desktop**, **Claude Code**, **ChatGPT**, and **Codex** — they all use the same `https://mcp.leadbay.app/mcp` endpoint.
 
 ---
 

leadbay-mcp/what-is-leadbay-mcp.md

@@ -5,7 +5,7 @@
 Pull leads, qualify them, draft outreach, log activity — in plain language. Claude acts on your real data, with your permissions, just as you would in the app.
 
 {% hint style="info" %}
-**MCP** stands for *Model Context Protocol* — an open standard that lets AI assistants like Claude securely connect to external tools and data. The Leadbay MCP server is open source and lives at [github.com/leadbay/leadclaw](https://github.com/leadbay/leadclaw).
+**MCP** stands for *Model Context Protocol* — an open standard that lets AI assistants like Claude securely connect to external tools and data. The Leadbay MCP server is open source and lives at [github.com/leadbay/mcp](https://github.com/leadbay/mcp).
 {% endhint %}
 
 ---