Leadbay

@leadbay/mcp — Leadbay MCP server

A Model Context Protocol server that lets Claude Desktop, Cursor, Claude Code, and any other MCP-compatible agent find, research, and prepare outreach on B2B prospects using your Leadbay account.

Upgrading? See CHANGELOG and MIGRATION.md for version-specific behavior changes. Key callout: composite write tools are ON by default since 0.3.0 — set LEADBAY_MCP_WRITE=0 to restore read-only behavior.

What Leadbay remembers

Leadbay stores nothing about how you like to work. Your assistant already does that — Claude, ChatGPT and Codex each keep their own memory of your tone, naming and habits, and it survives across conversations without us.

What Leadbay stores is what changes who it finds for you. When you tell the agent something about your market ("I target fleets over 100 vehicles", "carriers are a bad fit unless they do last-mile"), it calls leadbay_refine_lead_targeting, and that reshapes your recommendations for your whole organization — in the web app too, on every refresh. A lead you reject is recorded as a dislike, which feeds the recommender the same way.

1. Install

On macOS and Windows, launch the guided Electron installer from the npm package:

npx -y -p @leadbay/mcp@latest installer

It downloads the npm package, opens the installer app, signs in with Leadbay OAuth in your browser, detects installed MCP clients, then installs the selected ones.

On Linux, use the terminal-only path instead (no desktop installer window):

npx -y @leadbay/mcp@latest install --oauth

Claude web / Cowork on the web (no terminal)

On the web there's no terminal, so npx … installer doesn't apply — add Leadbay as a custom Connector instead. Claude connects to the hosted MCP from Anthropic's cloud and runs the OAuth sign-in in-app (no localhost callback, no client id/secret to fill in):

1. Customize → Connectors → "+" → Add custom connector
2. Name: Leadbay · URL: https://mcp.leadbay.app/mcp
3. Add, then complete the Leadbay sign-in prompt.

The same hosted URL works from a terminal that has the Claude Code CLI:

claude mcp add --transport http leadbay https://mcp.leadbay.app/mcp

In Claude Cowork with a terminal, the guided installer works as usual — it opens your browser for sign-in and configures the detected clients. If the browser never opens, the installer no longer hangs: it exits after a short watchdog with the Connector / claude mcp add instructions above.

From a repo checkout, run the same native installer with:

pnpm --filter @leadbay/mcp installer

pnpm --filter @leadbay/mcp installer -- --uninstall

Testing a local build

Add --local to install your current checkout instead of pulling from npm. Useful when developing the MCP and wanting to test changes in Claude Desktop or Claude Code without publishing.

# 1. Build

pnpm --filter @leadbay/mcp build

2a. GUI wizard — same OAuth flow, writes node dist/bin.js into client configs

pnpm --filter @leadbay/mcp installer -- --local

2b. Terminal-only

node packages/mcp/dist/bin.js install --oauth --local

2c. Explicit path (if running from a different directory)

node packages/mcp/dist/bin.js install --oauth --local=/abs/path/to/packages/mcp/dist/bin.js

Instead of npx -y @leadbay/mcp@latest, each client config gets node /absolute/path/to/dist/bin.js. After each rebuild the next MCP session picks up your changes automatically — no reinstall needed.

For terminal-only installs (works on macOS, Windows, and Linux):

npx -y @leadbay/mcp@latest install --oauth

To uninstall with the same guided app:

npx -y -p @leadbay/mcp@latest installer --uninstall

Only shows clients that already have Leadbay MCP configured.

These commands:

1. Open Leadbay OAuth in your browser.
2. Exchange the browser approval for a local MCP credential.
3. Auto-detect which MCP clients you have installed (Claude Code, Claude Desktop, Cursor, Codex) and register the server in each (after asking you per-target). Claude Code is registered with --scope user so the server appears in any project, not just where you ran the command.
4. Write the credential into the client config files — never to your terminal scrollback.

Add --no-write to disable the composite write tools (refine_prompt, report_outreach, adjust_audience, etc. — ON by default since 0.3.0; pass --no-write for a read-only agent). Add --yes for non-interactive runs (CI / scripts). Add --target claude-code,cursor to scope to specific clients. The legacy --include-write flag is accepted but is now a no-op.

OAuth auto-detects your region through stargate. Pass --region us|fr only if you need to override it.

To rotate the local MCP credential, re-run npx -y @leadbay/mcp install --oauth.

Don't have a Leadbay account? Register here.

Install via the Claude Code plugin marketplace

/plugin marketplace add leadbay/mcp

/plugin install leadbay@leadbay-mcp

Claude Code prompts for Leadbay auth/config through the plugin's userConfig. This is equivalent to the npm/CLI install above.

The plugin install gives you two surfaces in one shot:

1. The MCP server — registered via the plugin's mcpServers.leadbay block (boots @leadbay/mcp over stdio). This exposes the leadbay_* tools to the agent.
2. Six auto-discovered Claude Code skills under skills/ — leadbay_daily_check_in, leadbay_research_a_domain, leadbay_import_file, leadbay_log_outreach, leadbay_qualify_top_n, leadbay_refine_audience. These auto-trigger on natural-language matches against each skill's description ("get me leadbay leads today", "research acme.com", etc.) and dispatch to the MCP tools above by name. Each SKILL.md is generated by @leadbay/promptforge from the same .md.tmpl source as the MCP prompt, so the two surfaces never drift.

You can verify the skills installed by running /skill list after install. To uninstall everything, /plugin uninstall leadbay@leadbay-mcp removes the MCP server registration and the skills together.

Claude Desktop

The guided installer writes the local mcpServers.leadbay entry in claude_desktop_config.json with npx -y @leadbay/mcp@latest, like the Linux flow. Restart Claude Desktop after install.

The .dxt / .mcpb bundle from Releases remains available as an alternative install path.

npm install -g says "EACCES" / "permission denied"

If you installed Node from the official nodejs.org .pkg, /usr/local/lib/node_modules is root-owned. Any of these works:

• Use `npx` (recommended, no global install): all examples above use npx -y @leadbay/mcp@latest ... — no global install needed.
• `sudo npm install -g @leadbay/mcp` (enter your macOS password).
• Use a Node version manager — nvm, volta, fnm. They install Node under your home directory, so npm install -g works without sudo.

If you'd rather authenticate without auto-install

npx -y @leadbay/mcp@latest login --oauth

Default writes a 0600-mode JSON file at the platform-correct credentials path ($XDG_CONFIG_HOME/leadbay/credentials.json on Linux, ~/Library/Application Support/leadbay/credentials.json on macOS, %APPDATA%\leadbay\credentials.json on Windows). Pass --write-config /some/path.json to override the path. Pass --force to overwrite an existing file from a different account. The legacy email/password path still exists for scripts that cannot use a browser.

2. Updating the hosted MCP

The hosted MCP at https://mcp.leadbay.app/mcp runs self-hosted on the Leadbay k3s cluster (leadbay/infra). Deploys are automatic and driven off release tags — there is nothing to run by hand:

1. Bump packages/mcp/package.json in a normal PR and merge to main. auto-tag.yml pushes the matching mcp-v tag.
2. build-image.yml builds this repo's Dockerfile and pushes the image to Azure Container Registry as leadbay.azurecr.io/mcp: (and :latest).
3. Argo CD Image Updater in leadbay/infra watches for the new SHA-tagged image and rolls the mcp workload automatically.

To confirm the live endpoint is serving the expected version:

curl https://mcp.leadbay.app/healthz

{"ok":true,"version":" "}

Infrastructure details (workload manifests, Argo CD app, DNS) live in leadbay/infra — not this repo.

3. Quickstart

Prefer the installer in §1. If you need to hand-write config, first authenticate with npx -y @leadbay/mcp@latest login --oauth, then copy the LEADBAY_TOKEN and LEADBAY_REGION values from the credentials file it writes.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "leadbay": { "command": "npx", "args": ["-y", "@leadbay/mcp@latest"], "env": { "LEADBAY_TOKEN": " ", "LEADBAY_REGION": "us" } } } }

Restart Claude Desktop.

Cursor

In Cursor settings, add the MCP server:

{

"mcp.servers": { "leadbay": { "command": "npx", "args": ["-y", "@leadbay/mcp@latest"], "env": { "LEADBAY_TOKEN": " ", "LEADBAY_REGION": "us" } } } }

Claude Code

claude mcp add leadbay --scope user \

--env LEADBAY_TOKEN= \ --env LEADBAY_REGION=us \ -- npx -y @leadbay/mcp@latest

`--scope user` registers Leadbay globally for your account (visible from any project). Without it, claude mcp add defaults to project-local scope and the server only appears in conversations opened from the directory where you ran the command.

To disable the composite write tools (refine_prompt, report_outreach, adjust_audience, etc.), add --env LEADBAY_MCP_WRITE=0. They are ON by default since 0.3.0. The legacy LEADBAY_MCP_WRITE=1 opt-in is now a no-op.

Verify it works

Before starting Claude, run:

LEADBAY_TOKEN=<paste-oauth-token> npx -y @leadbay/mcp@latest doctor

Expected output:

Leadbay connection OK.

Organization: Your Org Billing: active AI credits: 420 / 1000

Claude Desktop / ChatGPT / remote-MCP clients

Leadbay runs a hosted MCP server that any remote-MCP client can connect to without a local install. Pick the URL for your assistant — each one works for every region:

https://mcp.leadbay.app/mcp           #