Leadbay

@leadbay/mcp — Leadbay MCP 服务

一个模型上下文协议服务，可让 Claude Desktop、Cursor、Claude Code 以及任何其他兼容 MCP 的 Agent 使用你的 Leadbay 账户查找、研究 B2B 潜在客户并准备外联。

正在升级？ 有关特定版本的行为变更，请参阅 CHANGELOG 和 MIGRATION.md。重要提示：自 0.3.0 起，复合写入工具默认启用——设置 LEADBAY_MCP_WRITE=0 可恢复只读行为。

Leadbay 会记住什么

Leadbay 不会存储你偏好的工作方式。这由你的助手负责——Claude、ChatGPT 和 Codex 各自会记住你的语气、命名方式和习惯，并在不同对话中保留这些记忆，无需我们介入。

Leadbay 存储的是会改变它为你找到谁的信息。当你告诉 Agent 一些关于你所在市场的信息（“我面向拥有 100 辆以上车辆的车队”，“除非承运商提供最后一公里配送服务，否则他们不适合”）时，它会调用 leadbay_refine_lead_targeting，这会调整整个组织的推荐结果——包括 Web 应用中的推荐，而且每次刷新都会生效。你拒绝的潜在客户会被记录为不喜欢，并以相同方式影响推荐系统。

1. 安装

在 macOS 和 Windows 上，从 npm 包启动 Electron 引导式安装程序：

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

它会下载 npm 包、打开安装程序应用、在浏览器中使用 Leadbay OAuth 登录、检测已安装的 MCP 客户端，然后安装选定的客户端。

在 Linux 上，请改用仅限终端的方式（不会打开桌面安装程序窗口）：

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

Claude 网页版 / 网页版 Cowork（无需终端）

网页端没有终端，因此不适用 npx … installer——请改为将 Leadbay 添加为自定义 Connector。Claude 会从 Anthropic 云端连接托管的 MCP，并在应用内进行 OAuth 登录（无需 localhost 回调，也无需填写客户端 ID/密钥）：

1. Customize → Connectors → "+" → Add custom connector
2. 名称： Leadbay · URL： https://mcp.leadbay.app/mcp
3. 添加，然后按照提示完成 Leadbay 登录。

同一个托管 URL 也可在装有 Claude Code CLI 的终端中使用：

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

在带终端的 Claude Cowork 中，引导式 installer 可照常使用——它会打开浏览器供你登录，并配置检测到的客户端。如果浏览器始终未打开，安装程序现在不会再卡住：它会在短暂的监控等待后退出，并显示上述 Connector / claude mcp add 说明。

从仓库检出目录运行同一个原生安装程序：

pnpm --filter @leadbay/mcp installer

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

测试本地构建

添加 --local，即可安装当前检出版本，而不是从 npm 拉取。在开发 MCP 并希望在 Claude Desktop 或 Claude Code 中测试更改、无需发布时，这很有用。

# 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

每个客户端配置中都会使用 node /absolute/path/to/dist/bin.js，而不是 npx -y @leadbay/mcp@latest。每次重新构建后，下一个 MCP 会话都会自动加载你的更改，无需重新安装。

仅通过终端安装（适用于 macOS、Windows 和 Linux）：

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

使用同一引导式应用卸载：

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

仅显示已配置 Leadbay MCP 的客户端。

这些命令会：

1. 在浏览器中打开 Leadbay OAuth。
2. 将浏览器中的授权交换为本地 MCP 凭据。
3. 自动检测已安装的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Codex），并在每个客户端中注册服务（逐个询问你是否要添加）。Claude Code 会使用 --scope user 注册，因此该服务会显示在任何项目中，而不仅限于你运行命令的项目。
4. 将凭据写入客户端配置文件——绝不会写入终端滚动记录。

添加 --no-write 可禁用组合写入工具（refine_prompt、report_outreach、adjust_audience 等；自 0.3.0 起默认启用；传入 --no-write 可使用只读 Agent）。添加 --yes 可用于非交互式运行（CI / 脚本）。添加 --target claude-code,cursor 可指定客户端。旧版 --include-write 标志仍可使用，但现在不执行任何操作。

OAuth 会通过 stargate 自动检测所在区域。仅当需要覆盖检测结果时，才传入 --region us|fr。

如需轮换本地 MCP 凭据，请重新运行 npx -y @leadbay/mcp install --oauth。

没有 Leadbay 账户？ 在此注册。

通过 Claude Code 插件市场安装

/plugin marketplace add leadbay/mcp

/plugin install leadbay@leadbay-mcp

Claude Code 会通过插件的 userConfig 提示你配置 Leadbay 身份验证和设置。这与上面的 npm / CLI 安装方式等效。

安装插件后即可一次获得两种使用方式：

1. MCP 服务——通过插件的 mcpServers.leadbay 区块注册（通过 stdio 启动 @leadbay/mcp）。这会向 Agent 暴露 leadbay_* 工具。
2. skills/ 下的六个 Claude Code 技能会自动发现——leadbay_daily_check_in、leadbay_research_a_domain、leadbay_import_file、leadbay_log_outreach、leadbay_qualify_top_n、leadbay_refine_audience。当自然语言与各技能的描述（“get me leadbay leads today”“research acme.com”等）匹配时，这些技能会自动触发，并按名称调用上述 MCP 工具。每个 SKILL.md 都由 @leadbay/promptforge 根据与 MCP 提示词相同的 .md.tmpl 源文件生成，因此两种使用方式始终保持一致。

安装后运行 /skill list，即可验证技能是否已安装。如需卸载所有内容，运行 /plugin uninstall leadbay@leadbay-mcp，即可同时移除 MCP 服务注册和技能。

Claude Desktop

引导式安装程序会在 claude_desktop_config.json 中写入本地 mcpServers.leadbay 条目，使用 npx -y @leadbay/mcp@latest，与 Linux 安装流程相同。安装后请重启 Claude Desktop。

Releases 中仍提供 .dxt / .mcpb 程序包，作为另一种安装方式。

npm install -g 提示“EACCES”/“permission denied”

如果你从官方 nodejs.org 下载 .pkg 安装了 Node，/usr/local/lib/node_modules 的所有者为 root。以下方法任选其一：

• **使用 npx（推荐，无需全局安装）：**上面的所有示例都使用 npx -y @leadbay/mcp@latest ...，无需全局安装。
• 运行 sudo npm install -g @leadbay/mcp（输入你的 macOS 密码）。
• 使用 Node 版本管理器——nvm、volta、fnm。它们会将 Node 安装在你的主目录下，因此无需 sudo 即可运行 npm install -g。

如果你更希望在不自动安装的情况下进行身份验证

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

默认会在平台对应的凭据路径写入一个 0600 权限模式的 JSON 文件（Linux 上为 $XDG_CONFIG_HOME/leadbay/credentials.json，macOS 上为 ~/Library/Application Support/leadbay/credentials.json，Windows 上为 %APPDATA%\leadbay\credentials.json）。传入 --write-config /some/path.json 可覆盖路径。传入 --force 可覆盖来自其他账户的现有文件。对于无法使用浏览器的脚本，仍可使用旧版邮箱/密码路径。

2. 更新托管的 MCP

托管的 MCP 位于 https://mcp.leadbay.app/mcp，在 Leadbay k3s 集群（leadbay/infra）上以自托管方式运行。部署由发布标签自动触发，无需手动操作：

1. 在常规 PR 中更新 packages/mcp/package.json，然后合并到 main。 auto-tag.yml 会推送匹配的 mcp-v<ver> 标签。
2. build-image.yml 会构建此仓库的 Dockerfile，并将镜像推送到 Azure Container Registry，标签为 leadbay.azurecr.io/mcp:<commit-sha>（以及 :latest）。
3. leadbay/infra 中的 Argo CD Image Updater 会监视新的 SHA 标签镜像，并自动滚动更新 mcp 工作负载。

若要确认线上端点提供的是预期版本：

curl https://mcp.leadbay.app/healthz
# {"ok":true,"version":"<published-version>"}

基础设施详情（工作负载清单、Argo CD 应用、DNS）位于 leadbay/infra，不在此仓库中。

3. 快速开始

建议使用§1中的安装程序。如果需要手动编写配置，请先运行 npx -y @leadbay/mcp@latest login --oauth 完成身份验证，然后从其写入的凭据文件中复制 LEADBAY_TOKEN 和 LEADBAY_REGION 的值。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

重启 Claude Desktop。

Cursor

在 Cursor 设置中添加 MCP 服务：

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

Claude Code

claude mcp add leadbay --scope user \
  --env LEADBAY_TOKEN=<paste-oauth-token> \
  --env LEADBAY_REGION=us \
  -- npx -y @leadbay/mcp@latest

--scope user 会为你的账户全局注册 Leadbay（在任何项目中均可见）。如果不加此参数，claude mcp add 默认使用项目本地范围，服务只会出现在从运行命令的目录中打开的对话里。

若要禁用复合写入工具（refine_prompt、report_outreach、adjust_audience 等），请添加 --env LEADBAY_MCP_WRITE=0。自 0.3.0 起，这些工具默认启用。旧版的 LEADBAY_MCP_WRITE=1 选择加入设置现在不起作用。

验证是否正常

启动 Claude 前，运行：

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

预期输出：

Leadbay connection OK.
  Organization:  Your Org
  Billing:       active
  AI credits:    420 / 1000

Claude Desktop / ChatGPT / 远程 MCP 客户端

Leadbay 运行着一个托管 MCP 服务，任何远程 MCP 客户端都可以连接，无需本地安装。为你的助手选择对应的 URL——每个 URL 都适用于所有地区：

https://mcp.leadbay.app/mcp           # Claude (Desktop, web, Cowork, Claude Code)
https://mcp.leadbay.app/chatgpt/mcp   # ChatGPT
https://mcp.leadbay.app/apps/mcp      # every other assistant (GitHub Copilot / VS Code, Goose, Cursor, …)

• Claude Desktop：Settings → Connectors → Add custom connector → 粘贴 /mcp URL。
• ChatGPT Desktop：Settings → Apps → Add app → 粘贴 /chatgpt/mcp URL。
• 任何其他助手：添加一个使用 /apps/mcp URL 的远程（Streamable HTTP）MCP 服务。

这三个 URL 指向同一个服务，使用相同的登录方式和潜在客户信息。/chatgpt/mcp 和 /apps/mcp 还会在助手能够显示 MCP Apps 时，在聊天中显示 Lead Triage Board；如果助手无法显示，则只会显示常规结果。Claude 在 /mcp 上保留自己的小组件和 artifacts。/chatgpt/mcp 还会省略充值和账单工具，因为 OpenAI 应用目录不允许提供这些工具。

首次连接时，客户端会启动 Leadbay OAuth 登录流程（服务会根据 RFC 9728 提供 OAuth 2.0 Protected Resource Metadata，并通过 401 + WWW-Authenticate 向未认证的请求发起质询）。在浏览器中登录一次即可；客户端会保存令牌，并在每个请求中以 Authorization: Bearer <token> 发送。无需复制粘贴令牌，也无需在本地安装 Node。

你无需选择地区。登录会通过 Stargate（Leadbay 不区分地区的统一 OAuth 授权机构）进行，你的地区信息包含在令牌本身中，而非连接器路径中，因此 /mcp、/chatgpt/mcp 和 /apps/mcp 对美国和法国的账户都能正常解析。/fr/mcp 仍可作为兼容别名，供此次变更前配置的连接器使用；无需迁移，使用它也没有任何好处。如果从未出现登录提示，说明你使用的是旧版托管服务（低于 0.21.0）；服务会在发布新版本时自动更新。

更新自动进行——托管服务始终运行最新发布版本。你无需更新配置文件，也无需在自己的设备上重启任何内容。

4. 可用的提示词示例

为我找出 20 家位于柏林、符合我的理想买家画像的 SaaS 公司。

研究这份名单中最有潜力的客户——提供 AI 摘要、近期动态，以及我应该联系谁。

为 Acme Corp 准备一份外联方案包——如果我们有额度，请包含推荐联系人及其补全后的邮箱。

5. 规范原语实战

如果你正在构建或审计 MCP 集成，本节将展示调用 @leadbay/mcp 时，各种规范原语在传输过程中的实际形式。每个示例都是客户端发送或接收的真实 JSON-RPC 帧——可原样复制到调试器中。

tools/list — 注释 + outputSchema

每个工具都会声明其读写、幂等和开放世界属性，并且（对于声明最完整的工具）提供类型化的返回架构。

请求：

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

响应（节选）：

{
  "tools": [
    {
      "name": "leadbay_account_status",
      "description": "Show the user's account state — admin rights, language, last-active lens, current quota …",
      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
      "annotations": {
        "title": "Show Leadbay account + quota state",
        "readOnlyHint": true, "destructiveHint": false,
        "idempotentHint": true, "openWorldHint": true
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "user": { "type": "object", "properties": { "email": {}, "name": {}, "admin": {}, "manager": {}, "language": {} } },
          "organization": { "type": "object", "properties": { "id": {}, "name": {}, "ai_agent_enabled": {}, "computing_intelligence": {}, "plan": {} } },
          "last_requested_lens": {},
          "quota": {},
          "_meta": { "type": "object", "properties": { "region": {} } }
        },
        "required": ["user", "organization"]
      }
    }
  ]
}

支持这些功能的客户端会利用注释决定是自动批准还是提示用户；outputSchema 则让它们能够根据数据结构分派，而不必重新解析文本。

带有 structuredContent 的 tools/call

当工具声明了 outputSchema 时，响应会在 text 内容之外，同时包含一个类型化的 structuredContent 区块：

请求：

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "leadbay_account_status", "arguments": {} } }

响应：

{
  "content": [
    { "type": "text", "text": "{\"user\":{...},\"organization\":{...}, ...}" }
  ],
  "structuredContent": {
    "user":  { "email": "[email protected]", "name": "You", "admin": true, "manager": false, "language": "en" },
    "organization": { "id": "org-1", "name": "Your Co", "ai_agent_enabled": true, "computing_intelligence": false, "plan": "PRO" },
    "last_requested_lens": 42,
    "quota": { "plan": "PRO", "windows": [...] },
    "_meta": { "region": "us" }
  }
}

prompts/list 和 prompts/get — 斜杠命令

请求：

{ "jsonrpc": "2.0", "id": 3, "method": "prompts/list" }

响应（节选）：

{
  "prompts": [
    { "name": "daily-check-in", "description": "Pull fresh leads, surface auto-qualified top, deepen 1-3 promising ones.", "arguments": [] },
    { "name": "research-a-domain", "description": "Import a domain → resolve to leadId → research_lead.",
      "arguments": [{ "name": "domain", "description": "Company domain (e.g., acme.com)", "required": true }] },
    { "name": "log-outreach", "description": "Gather verification → report_outreach.",
      "arguments": [{ "name": "lead_id", "required": true }, { "name": "what", "required": true }] }
  ]
}

随后，prompts/get 会将选定的工作流生成为结构化的 messages 数组，供 Agent 展开：

{ "jsonrpc": "2.0", "id": 4, "method": "prompts/get",
  "params": { "name": "research-a-domain", "arguments": { "domain": "acme.com" } } }

没有 prompts/list 界面的客户端（Cowork 是典型例子）：提示词目录仍会传递给 Agent。服务端的 initialize 响应包含一个 serverInfo.instructions 字符串，其中列出了每个提示词、触发语句及其必需参数，因此 Agent 可以匹配用户的自然语言请求，并直接调用 prompts/get，无需用户点击斜杠菜单。除标准 MCP initialize 握手外，无需客户端执行其他操作。

resources/list 和 resources/read — 可通过 URI 访问的只读数据

会公布三种 URI 方案：lead://{uuid}/profile、lens://{id}/definition、org://taste-profile。支持的客户端会跨轮次缓存这些数据。

请求：

{ "jsonrpc": "2.0", "id": 5, "method": "resources/templates/list" }

响应（节选）：

{
  "resourceTemplates": [
    { "uriTemplate": "lead://{uuid}/profile", "name": "Lead profile", "description": "Lead profile by Leadbay UUID — basics + qualifications + contacts.", "mimeType": "application/json" },
    { "uriTemplate": "lens://{id}/definition", "name": "Lens definition", "description": "Filter + scoring config for a lens.", "mimeType": "application/json" }
  ]
}

读取特定线索：

{ "jsonrpc": "2.0", "id": 6, "method": "resources/read",
  "params": { "uri": "lead://0xabcd-…/profile" } }

响应会将 JSON 封装在带有 URI 对应 MIME 类型的 text 内容块中，供客户端呈现或缓存。

notifications/progress — 长时间运行的操作期间流式传输进度

当 Agent 调用长时间运行的工具，并在 _meta 中提供 progressToken 时，服务会向客户端流式传输进度通知。会发送进度通知的长时间运行工具：bulk_qualify_leads、import_and_qualify、enrich_titles、bulk_enrich_status、qualify_status。

请求：

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": {
    "name": "leadbay_bulk_qualify_leads",
    "arguments": { "leadIds": ["lead-1", "lead-2", "lead-3"] },
    "_meta": { "progressToken": "bq-1" }
  } }

调用运行期间，会收到以下通知：

{ "jsonrpc": "2.0", "method": "notifications/progress",
  "params": { "progressToken": "bq-1", "progress": 1, "total": 3, "message": "Qualified Acme Corp (1/3)" } }
{ "jsonrpc": "2.0", "method": "notifications/progress",
  "params": { "progressToken": "bq-1", "progress": 2, "total": 3, "message": "Qualified Globex (2/3)" } }
{ "jsonrpc": "2.0", "method": "notifications/progress",
  "params": { "progressToken": "bq-1", "progress": 3, "total": 3, "message": "Qualified Initech (3/3)" } }

随后是最终的 tools/call 响应。

notifications/cancelled — 实际取消操作

按 ID 发送取消请求；服务的 ToolContext.signal 会在 ≤2 秒内中止轮询循环。任务本身会继续在后端运行——稍后使用 notification_id 轮询 leadbay_bulk_enrich_status，即可继续处理。

{ "jsonrpc": "2.0", "method": "notifications/cancelled",
  "params": { "requestId": 7, "reason": "user clicked cancel" } }

elicitation/create — 服务向用户提问

供 refine_prompt（澄清流程）和 report_outreach（防投毒用户确认）使用。服务向客户端发送 elicitation/create 请求；客户端呈现表单；用户输入内容；响应会反馈到工具调用中。Agent 永远不会看到提示词。

服务发送（在 tools/call 调用期间）：

{ "jsonrpc": "2.0", "id": 99, "method": "elicitation/create",
  "params": {
    "message": "An AI agent wants to log outreach on lead-1: 'Called Acme'. The agent claims you confirmed this. Type your literal confirmation to proceed; cancel to reject.",
    "requestedSchema": {
      "type": "object",
      "properties": { "confirmation": { "type": "string", "title": "Your confirmation" } },
      "required": ["confirmation"]
    }
  } }

客户端返回：

{ "jsonrpc": "2.0", "id": 99, "result": { "action": "accept", "content": { "confirmation": "yes I called Acme today" } } }

用户输入的原文会替换外联记录中的 verification.ref，且响应会包含 confirmed_via: "elicit"，用于 SDR 审计记录。

6. 故障排除

问题	原因	解决方法
LEADBAY_TOKEN environment variable is required	配置环境中缺少本地 MCP 凭据	重新运行 npx -y @leadbay/mcp install --oauth，然后重启客户端
Authentication token expired or invalid	凭据已撤销或区域错误	重新进行身份验证：npx -y @leadbay/mcp install --oauth；检查 LEADBAY_REGION
Leadbay doctor: could not reach any Leadbay region	区域错误或网络受阻	使用 LEADBAY_REGION=fr 运行 doctor 以自动探测。检查是否能访问 https://api-us.leadbay.app。
No enrichment credits remaining	配额已用完	联系 Leadbay 支持团队以增加配额
Claude Desktop 首次使用时“一直加载”	npx 冷启动时正在获取软件包	首次运行需要约 10 秒。建议使用 npm install -g @leadbay/mcp 以加快启动速度。
Claude Desktop 未显示 Leadbay 工具	服务启动时崩溃	检查 ~/Library/Logs/Claude/mcp*.log（macOS）或 %APPDATA%\Claude\logs\mcp*.log（Windows）。
Claude Code 在新对话中找不到 Leadbay	MCP 服务安装在项目作用域（0.3.0 之前的默认设置）	使用 --scope user 重新运行：claude mcp remove leadbay && claude mcp add leadbay --scope user --env LEADBAY_TOKEN=… --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@latest
Agent 报告 refine_prompt / adjust_audience 等“找不到工具”	安装的是 0.3.0 之前的版本，且未设置 LEADBAY_MCP_WRITE（写入功能已关闭）	重新运行 npx @leadbay/mcp install，或从客户端配置中移除 LEADBAY_MCP_WRITE=0（0.3.0 及更高版本默认启用写入功能）

7. 升级与轮换

升级：引导式安装程序会固定使用 @leadbay/mcp@latest，因此每个 MCP 会话都会自动使用最新发布版本——只需重启客户端。（如果在配置中手动固定了特定版本，请将其改为 @latest 或所需版本，然后重启。）0.3.0 默认启用组合写入工具——请参阅 MIGRATION.md。另请参阅更新日志。

轮换本地凭据：重新运行 npx -y @leadbay/mcp@latest install --oauth（或 login --oauth）——新凭据会替换 MCP 客户端配置中的旧凭据。

8. 高级

OAuth 登录

建议使用基于浏览器的登录方式：

npx -y @leadbay/mcp login --oauth

CLI：

1. 探测 stargate.leadbay.app/1.0/user_info，通过 GeoIP 自动检测你的地区（如果你使用 VPN 或身处常驻地区以外，请使用 --region us|fr 覆盖）。
2. 在浏览器中打开 leadbay.app/oauth/authorize。
3. 点击 Allow 后，重定向到 http://127.0.0.1:<random-port>/callback 上的一次性环回 URL。
4. 使用 PKCE（S256）将授权码交换为令牌，然后写入与电子邮件/密码登录流程生成的相同凭据文件。

CLI 会为每台机器注册一个全新的 OAuth 客户端（RFC 7591 动态客户端注册），因此二进制文件中不会包含共享密钥。生成的令牌长期有效，并且可与旧版 bearer 令牌互换使用。手动配置 MCP 时，仍可将其作为 LEADBAY_TOKEN 传入；Claude Desktop 捆绑包会自行执行 OAuth 流程并保存令牌，无需你粘贴令牌。

若要在生产后端部署完成前针对预发布环境进行测试：

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

--staging 会切换后端（staging.api.leadbay.app / api-{us,fr}-staging.leadbay.app）、授权界面（staging.leadbay.app）和 stargate 地区探测服务（staging.stargate.leadbay.app）。它还会在凭据文件中保存 LEADBAY_BASE_URL，以免后续运行时切回生产环境。

暴露细粒度工具并禁用写入工具

默认情况下，服务会暴露组合式工作流工具——包括读取工具（leadbay_pull_leads、leadbay_research_lead_by_id、leadbay_account_status、leadbay_list_previously_enriched_titles、leadbay_research_lead_by_name_fuzzy、leadbay_prepare_outreach、leadbay_qualify_status、leadbay_list_mappable_fields）和写入工具（leadbay_bulk_qualify_leads、leadbay_enrich_titles、leadbay_refine_lead_targeting、leadbay_report_outreach、leadbay_adjust_audience、leadbay_answer_clarification、leadbay_import_leads、leadbay_import_and_qualify）。这些工具适用于大多数提示词。

若要禁用写入工具（运行严格只读的 Agent），请设置 LEADBAY_MCP_WRITE=0。服务的系统提示词会相应调整，省略对这些工具的引用。

若要启用细粒度 API 工具（leadbay_list_lenses、leadbay_discover_leads、leadbay_get_lead_profile、leadbay_get_contacts、leadbay_get_quota、leadbay_get_taste_profile、leadbay_get_lens_filter、leadbay_list_sectors 等），请设置 LEADBAY_MCP_ADVANCED=1。

"env": {
  "LEADBAY_TOKEN": "<token>",
  "LEADBAY_MCP_ADVANCED": "1",
  "LEADBAY_MCP_WRITE": "0"
}

每次调用 leadbay_report_outreach 时都必须提供 verification 字段（Gmail 邮件 ID、Calendar 事件 ID，或包含用户原文的 user_confirmed），以防 Agent 用幻觉生成的外联内容污染你的 SDR 工作流。

注意：leadbay_login 不会通过 MCP 暴露，这是有意为之——请参阅下文的安全性。

从外部系统导入域名 → leadIds

leadbay_import_leads 是一个写入工具（自 0.3.0 起默认开放；设置 LEADBAY_MCP_WRITE=0 可隐藏），适用于你从其他系统（CRM、分析工具、邮件往来对象等）获取了一组公司域名，并希望获得稳定的 Leadbay leadId，以便串联后续资格评估：

设置环境：

export LEADBAY_TOKEN="<your-token>"

export LEADBAY_REGION="us"

（自 0.3.0 起，LEADBAY_MCP_WRITE 默认为 "1"（开启），无需设置。）

然后按照 §2 配置 MCP 客户端，并向 Agent 发出请求：

“导入这些域名：apple.com、microsoft.com、salesforce.com。然后评估匹配到的潜在客户。”

Agent 会调用 leadbay_import_leads({ domains: [...] })，获取 { leads: [{domain, leadId, name}], not_imported: [{domain, reason}], importIds, _meta }，然后将 leads.map(l => l.leadId) 传给 leadbay_bulk_qualify_leads。

⚠️ 会写入用户状态。 内部封装了 Leadbay 的 CRM 导入向导（目前后端唯一提供的域名导入基础功能）。每次调用都会：

• 在你的 CRM 导入列表中创建一行记录（可在网页 UI 中查看）
• 更新入门引导状态（startFileless，入门步骤 → PROCESSING）

适用于偶尔自动化。不适用于高频调用（每天超过 5 次）——合适的基础功能是一个干净的异步导入并抓取后端端点，已在 leadbay/backend 中作为后续事项跟踪。

uncrawled 行表示待处理，而非失败。 该匹配机制会匹配爬虫已知的域名。对于爬虫尚未编入索引的域名，会将其放入 not_imported，并设为 reason: "uncrawled"——导入仍会完成，随后 Leadbay 会在后台抓取该域名，并异步添加潜在客户（即延迟导入），因此这类行通常会在几分钟到几小时内自动处理完成。抓取完成后，这些延迟添加的潜在客户会显示在用户的 Leadbay 账户中。leadbay_import_status 只会刷新状态和进度（不会刷新已添加的潜在客户），而 leadbay_pull_leads 会读取当前活动视图的愿望清单（因此，视图之外导入的潜在客户可能不会显示）。对于一家指定公司，leadbay_research_lead_by_name_fuzzy 会搜索所有可见数据（不受视图范围限制），并在公司被抓取后找到它；若要批量刷新，可稍后重新运行相同的导入，以重新核对已抓取的域名。uncrawled 并非失败，也不代表网站有问题——绝不要向用户这样描述。

一次调用完成导入和资格评估（0.5.0）

leadbay_import_and_qualify 将导入 → AI 资格评估合并为一次复合调用。预算允许时，会直接返回每个潜在客户的资格评估结果和 ai_agent_lead_score；否则会返回 qualify_id UUID 句柄，Agent 可稍后将其传给 leadbay_qualify_status（句柄会保留 30 天，即使 MCP 重启也仍然有效）。完整示例（发现 → 预览 → 导入 → qualify_status）、JSON 结构、错误代码参考、各工具的前置条件，以及 not_in_lens 分区语义，请参阅 MIGRATION.md。

配套工具：leadbay_list_mappable_fields 会返回标准 CRM 字段与此组织自定义字段的并集（附带可直接粘贴到 mappings.fields 的 mapping_value）。可选参数 for_records 会针对样本运行向导的预处理，在一次调用中附上映射提示和自定义字段名称匹配候选项。

要求： LEADBAY_MCP_WRITE 未设为 0（自 0.3.0 起默认开启；或者在 OpenClaw 中设置 exposeWrite: true）；你的 Leadbay 账户具有管理员角色；账单处于有效状态。

使用 dry_run: true 可验证域名格式和向导是否可访问，而不提交潜在客户与 CRM 的关联。（CRM 导入行仍会显示——只有后端变更才能移除该行。）

环境变量

变量	必需	默认值	用途
LEADBAY_TOKEN	是	—	Bearer 令牌（通过 install 或 login 创建，或手动设置）
LEADBAY_REGION	强烈建议	（自动探测 — 见下方警告）	us 或 fr
LEADBAY_BASE_URL	否	根据区域推导	覆盖设置，用于 staging/dev
LEADBAY_MCP_ADVANCED	否	未设置	"1" 会公开细粒度 API 工具
LEADBAY_MCP_WRITE	否	"1"（开启）	自 0.3.0 起默认开启。设为 "0" / "false" / "no" / "off" 可隐藏组合写入工具（refine_prompt、report_outreach、adjust_audience 等）以及提及这些工具的系统提示词。注意：0.2.x 将 "true" / "yes" / "on" 视为关闭；0.3.0+ 将它们视为开启。
LEADBAY_MOCK	否	未设置	"1" 会从磁盘上的固定数据读取所有内容（仅用于开发）
LEADBAY_MOCK_DIR	否	./.context/leadbay-live-shapes/	模拟模式的固定数据目录
LEADBAY_LOG_LEVEL	否	error	debug | info | error，日志输出到 stderr
LEADBAY_TIMEOUT_MS	否	600000	单个 Leadbay 出站请求的兜底截止时间，适用于没有任何操作取消请求的情况。这不是延迟预算：耗时较长的工作（数据丰富、批量资格审核、导入）会启动并轮询，而已取消的工具调用会自行关闭其请求。超时后会关闭套接字，工具返回 TIMEOUT 错误。设为 0 可禁用此兜底机制。

⚠️ 请明确设置 LEADBAY_REGION。 如果不设置，服务会携带你的 Bearer 令牌，并行探测 api-us.leadbay.app 和 api-fr.leadbay.app，从而将令牌发送到并不管理你账户的后端。正因如此，install 和 login 子命令会强制要求提供 --region；运行时自动探测只是为了向后兼容，并非推荐设置。

安全性

• 令牌仅保存在 MCP 客户端的配置文件中，不会通过网络传输，除非发送到 api-{region}.leadbay.app。
• OpenClaw 适配器中的 leadbay_login 工具不会在 MCP 上注册：向大模型公开需要凭据的工具会带来提示词注入风险。请使用上文所述的令牌配置方式。
• leadbay_add_note 工具是一项标记为 optional: true 的写入操作。如果你的客户端支持按工具选择启用，请在需要时再启用。leadbay_enrich_contacts（丰富一位指定联系人的信息）自 0.33.4 起包含在默认写入工具范围内；此前仅限高级模式。

隐私与遥测

@leadbay/mcp 会向 PostHog 发送产品使用事件，并向 Sentry 报告意外错误——与 Leadbay Web 应用采用相同的做法。PostHog 用于衡量产品使用情况（哪些工具被调用、耗时、错误率）；Sentry 用于捕获我们原本永远不会发现的崩溃。

这些事件并非匿名。 每个事件都关联到你的 Leadbay 账户邮箱（distinctId = me.email），因此你的 MCP 活动会在我们的分析中与 Web 应用活动归并到同一身份下——Web 应用本身也采用相同的身份模型。如果你不希望 MCP 使用情况关联到你，请选择退出（见下文）。

我们向 PostHog 发送的内容（每次工具调用）：

事件	触发时机	属性
mcp tool called	每次调用工具时	tool、ok、duration_ms、format、bytes、error_code（如果失败）
mcp quota hit	API 返回 QUOTA_EXCEEDED（HTTP 429/402）时	tool、retry_after_s、endpoint
mcp topup link created	leadbay_create_topup_link 返回结账 URL 时	tool（绝不会捕获 URL 本身）
mcp tool timeout	对外发起的 Leadbay 请求超出 LEADBAY_TIMEOUT_MS 时	tool、timeout_ms、endpoint、region

首次完成身份验证的调用后，你的 PostHog distinctId 会设为你的 Leadbay 账户邮箱，使同一用户的 MCP 事件与 Web 应用事件归并。事件还会附带 $groups.organization，以支持组织级汇总。

我们绝不会发送的内容：工具参数正文、响应正文、潜在客户的邮箱／电话号码、Stripe URL、lens 描述、资格认定答案。

发送到 Sentry 的错误：仅限意外抛出的错误（TypeError、网络故障、解析错误）。预期的业务结果——配额限制、资源缺失、身份验证过期、账单暂停——仅保留在 PostHog 中。

选择退出——最简单的方法是直接向 Agent 说：“关闭遥测”（或“遥测已开启吗？”）。这会调用 leadbay_set_telemetry 工具，并将你的选择保存到 Leadbay 账户中。托管版／Web 连接器会逐请求遵循此设置（无需编辑本地配置）。在本地安装中，服务会在启动时根据 LEADBAY_TELEMETRY_ENABLED 决定是否启用遥测，不会读取账户设置，因此还需将 LEADBAY_TELEMETRY_ENABLED=false（见下文）以停止本地事件。

你也可以通过配置选择退出：leadbay-mcp install 默认会在 MCP 客户端的 env 配置块中写入 LEADBAY_TELEMETRY_ENABLED=true。大多数客户端（Claude Desktop、Cursor）会在设置界面中将 env 变量布尔值显示为开关，因此无需编辑文件即可切换。若要在安装时选择退出，请传入 --no-telemetry；若要手动选择退出，请将 env 值切换为 "false"：

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

可接受的值："true"|"1"|"yes"|"on" 表示启用；"false"|"0"|"no"|"off" 表示停用（不区分大小写）。未设置或无法识别的值默认启用。

覆盖目标地址：设置 LEADBAY_POSTHOG_KEY=<your-project-key> 和／或 LEADBAY_SENTRY_DSN=<your-dsn>，即可将数据发送到你自己的项目。NODE_ENV=test 时也会自动停用遥测。

通过此服务获取的联系人数据会留在 MCP 客户端会话本地——遥测不会包含这些数据。向 Leadbay 发出的请求受 Leadbay 隐私政策约束。

9. 面向开发者——测试本地构建

如果你想在真实的 MCP 客户端（Claude Desktop、Claude Code、Cursor、Codex）中测试 MCP 服务的更改，而不将其发布到 npm，请使用此方法。

1. 构建

pnpm install
pnpm build

2. 使用 --local 运行安装程序

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

这会在浏览器中打开安装向导。使用 OAuth 登录，选择客户端，然后点击 Install。向导会在每个客户端的配置中写入 node /absolute/path/to/dist/bin.js，而不是通常使用的 npx @leadbay/mcp@latest 调用。

3. 重启 MCP 客户端

重启 Claude Desktop / Claude Code / Cursor / Codex，以加载新配置。

恢复到已发布版本

重新运行安装程序，不带 --local，即可切换回 npm：

pnpm --filter @leadbay/mcp installer

或者直接使用已发布的软件包：

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

10. 维护者指南 — 发布

发布由标签驱动，通过 .github/workflows/release.yml 执行。更新 packages/mcp/package.json#version，更新 packages/mcp/CHANGELOG.md，合并到 main，然后：

git tag mcp-v0.3.0 && git push origin mcp-v0.3.0

完整操作流程请参阅 RELEASE.md。

许可证

MIT。请参阅 LICENSE。