Leadbay

@leadbay/mcp — Leadbay MCP サーバー

Claude Desktop、Cursor、Claude Code、その他のMCP互換エージェントが、Leadbayアカウントを使ってB2Bの見込み顧客を見つけ、調査し、アプローチの準備をできるModel Context Protocolサーバーです。

アップグレードしますか？ バージョン固有の動作変更については、CHANGELOGとMIGRATION.mdを参照してください。重要なお知らせ：複合書き込みツールは0.3.0以降、デフォルトで有効です。読み取り専用の動作に戻すには、LEADBAY_MCP_WRITE=0を設定してください。

Leadbayが記憶すること

Leadbayは、あなたの仕事の進め方について何も保存しません。それはアシスタントがすでに行っています。Claude、ChatGPT、Codexはそれぞれ、あなたの口調や命名方法、習慣を独自に記憶し、私たちを介さず会話をまたいで保持します。

Leadbayが保存するのは、誰を見つけるかを変える情報です。市場についてエージェントに何かを伝えると（「車両が100台を超える車両群をターゲットにする」「ラストマイル配送を行っていない運送業者は適合しない」など）、leadbay_refine_lead_targetingが呼び出され、組織全体のおすすめが調整されます。ウェブアプリでも、更新するたびに反映されます。却下したリードは「好ましくない」という情報として記録され、同じようにおすすめ機能に反映されます。

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 web ／ウェブ版Cowork（ターミナル不要）

ウェブ版にはターミナルがないため、npx … installerは使えません。代わりにLeadbayをカスタムコネクタとして追加してください。ClaudeはAnthropicのクラウドからホスト型MCPに接続し、アプリ内でOAuthサインインを実行します（localhostコールバックや、入力が必要なクライアントID／シークレットはありません）。

1. カスタマイズ → コネクタ →「+」→ カスタムコネクタを追加
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を通常どおり使用できます。サインインのためにブラウザーが開き、検出されたクライアントが設定されます。ブラウザーが開かない場合でも、インストーラーは停止しません。短時間のウォッチドッグ後に終了し、上記のコネクタ／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

npx -y @leadbay/mcp@latest の代わりに、各クライアントの設定には node /absolute/path/to/dist/bin.js が設定されます。ビルドし直すと、次の 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 を指定してください）。非対話型の実行（CI／スクリプト）では --yes を追加してください。対象クライアントを指定するには --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 によるインストールと同等です。

プラグインをインストールすると、2 つの機能を一度に利用できます：

1. MCP サーバー — プラグインの mcpServers.leadbay ブロックを通じて登録されます（stdio 経由で @leadbay/mcp を起動します）。これにより、エージェントで leadbay_* ツールを利用できます。
2. skills/ の下にある、Claude Code が自動検出する 6 つのスキル — leadbay_daily_check_in、leadbay_research_a_domain、leadbay_import_file、leadbay_log_outreach、leadbay_qualify_top_n、leadbay_refine_audience。各スキルの説明に一致する自然言語（「今日のLeadbayリードを取得して」「acme.comを調査して」など）に応じて自動的に起動し、上記の MCP ツールを名前で呼び出します。各 SKILL.md は、MCP プロンプトと同じ .md.tmpl ソースから @leadbay/promptforge によって生成されるため、2 つの機能の内容が食い違うことはありません。

インストール後に /skill list を実行すると、インストールされたスキルを確認できます。すべてをアンインストールするには、/plugin uninstall leadbay@leadbay-mcp を実行すると、MCP サーバーの登録とスキルをまとめて削除できます。

Claude Desktop

ガイド付きインストーラーは、Linux の手順と同様に、claude_desktop_config.json のローカル mcpServers.leadbay エントリーに npx -y @leadbay/mcp@latest を書き込みます。インストール後、Claude Desktop を再起動してください。

リリースの .dxt／.mcpb バンドルも、別のインストール方法として引き続き利用できます。

npm install -g で「EACCES」／「permission denied」と表示される場合

Node を公式の nodejs.org の .pkg からインストールした場合、/usr/local/lib/node_modules の所有者は root です。次のいずれかの方法を利用できます：

• npx を使う（推奨、グローバルインストール不要）： 上記の例はすべて npx -y @leadbay/mcp@latest ... を使っているため、グローバルインストールは不要です。
• sudo npm install -g @leadbay/mcp を使う（macOS のパスワードを入力してください）。
• Node のバージョンマネージャーを使う — nvm、volta、fnm。これらはホームディレクトリに Node をインストールするため、npm install -g を sudo なしで実行できます。

自動インストールを使わずに認証する場合

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 の更新

https://mcp.leadbay.app/mcp のホスト型 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：設定 → コネクター → カスタムコネクターを追加 → /mcp URL を貼り付けます。
• ChatGPT Desktop：設定 → アプリ → アプリを追加 → /chatgpt/mcp URL を貼り付けます。
• その他のアシスタント：/apps/mcp URL を使って、リモート（Streamable HTTP）MCP サーバーを追加します。

3 つとも、同じサーバー、サインイン、リードを利用します。/chatgpt/mcp と /apps/mcp では、アシスタントが MCP Apps を表示できる場合、チャット内に Lead Triage Board も表示されます。表示できないアシスタントでは、通常の結果が表示されます。Claude は /mcp 上で独自のウィジェットとアーティファクトを保持します。OpenAI のアプリディレクトリではトップアップと請求ツールが許可されていないため、/chatgpt/mcp ではそれらのツールも除外されています。

初回接続時、クライアントは Leadbay の OAuth サインインを実行します（サーバーは RFC 9728 に準拠した OAuth 2.0 Protected Resource Metadata を公開し、未認証リクエストには 401 + WWW-Authenticate でチャレンジします）。ブラウザーで一度サインインすると、クライアントがトークンを保存し、すべてのリクエストで Authorization: Bearer <token> として送信します。トークンをコピーして貼り付ける必要も、Node をローカルにインストールする必要もありません。

リージョンを選ぶ必要はありません。サインインは、Leadbay のリージョンに依存しない単一の OAuth 認証機関である Stargate を経由します。また、リージョン情報はコネクターのパスではなくトークン自体に含まれるため、/mcp、/chatgpt/mcp、/apps/mcp のいずれでも、US と FR のアカウントを解決できます。この変更より前に設定されたコネクターとの互換性のため、/fr/mcp も引き続き利用できます。移行する必要はなく、使用するメリットもありません。サインインのプロンプトが表示されない場合は、ホスト型サーバーの古いビルド（0.21.0 より前）を使用しています。リリース時に自動更新されます。

更新は自動です — ホスト型サーバーは常に、公開済みの最新リリースを実行しています。設定ファイルを更新したり、何かを再起動したりする必要はありません。

4. 動作するプロンプトの例

Ideal Buyer Profile に合致する、ベルリンの SaaS 企業を 20 社探してください。

そのリストの最有力見込み客を調査してください。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 配列として具体化します。

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

prompts/list UI を備えていないクライアント（代表例は Cowork）：カタログは引き続きエージェントに届きます。サーバーの initialize レスポンスには、すべてのプロンプト、そのトリガーとなる表現、必須引数を示す serverInfo.instructions 文字列が含まれます。これによりエージェントは、ユーザーの自然言語による依頼に合うプロンプトを判断し、ユーザーがスラッシュメニューを操作しなくても、prompts/get を直接呼び出せます。標準の MCP initialize ハンドシェイク以外に、クライアント側での操作は必要ありません。

resources/list と resources/read — URI で指定できる読み取り専用データ

3 つの 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 — 長時間処理中のストリーミング

エージェントが _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 リクエストを送信し、クライアントがフォームを表示して、ユーザーが入力します。そのレスポンスがツール呼び出しに返されます。エージェントにプロンプトが見えることはありません。

サーバーが送信する内容（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 を置き換え、SDR の監査証跡用にレスポンスには confirmed_via: "elicit" が含まれます。

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
refine_prompt / adjust_audience などで、エージェントが「ツールが見つからない」と報告する	LEADBAY_MCP_WRITE が未設定のまま 0.3.0 より前のバージョンをインストールしています（書き込み機能は無効でした）	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 Dynamic Client Registration）、共有シークレットがバイナリ内に保存されることはありません。生成されたトークンは有効期間が長く、従来のベアラートークンと相互に置き換えて使用できます。手動の 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）を公開します。これらはほとんどのプロンプトで適切に機能します。

書き込みツールを無効にするには（読み取り専用のエージェントとして実行するには）、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）。これにより、エージェントが幻覚によるアウトリーチで 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"（ON）なので、設定する必要はありません。）

次に、§2 に従って MCP クライアントを接続し、エージェントに次のように依頼します。

「次のドメインをインポートしてください：apple.com、microsoft.com、salesforce.com。一致した見込み顧客を評価してください。」

エージェントは 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）。

たまに実行する自動化に適しています。高頻度（1 日 5 回超）での実行には適していません。必要なのは、クロールを伴うクリーンな非同期インポート用バックエンドエンドポイントであり、leadbay/backend で今後の対応項目として追跡されています。

uncrawled の行は保留中であり、失敗ではありません。 この仕組みでは、クローラーがすでに認識しているドメインが照合されます。クローラーがまだインデックスしていないドメインは not_imported に reason: "uncrawled" として追加されます。インポート自体は完了し、その後 Leadbay がバックグラウンドでそのドメインをクロールして見込み顧客を非同期で追加します（遅延インポート）。そのため、該当する行は通常、数分から数時間以内に自然に解決されます。後から追加された見込み顧客は、クロールが完了するとユーザーの Leadbay アカウントに反映されます。leadbay_import_status はステータスと進捗のみを更新し（追加された見込み顧客は更新しません）、leadbay_pull_leads はアクティブなレンズのウィッシュリストを読み取るため、インポートした見込み顧客がそのレンズの対象外だと表示されないことがあります。会社名を指定する場合は、leadbay_research_lead_by_name_fuzzy で表示可能な全データ（レンズの範囲外も含む）を検索でき、クロール後に該当する会社を見つけられることがあります。一括で更新する場合は、後で同じインポートを再実行して、クロール済みのドメインを再照合してください。uncrawled は失敗ではなく、不正なウェブサイトを意味するものでもありません。ユーザーにそのようなものとして伝えないでください。

インポートと評価を1つの動詞で実行（0.5.0）

leadbay_import_and_qualify は、インポートから AI による評価までを1回の複合呼び出しにまとめます。予算に余裕がある場合は、見込み顧客ごとの評価結果と ai_agent_lead_score をインラインで返します。余裕がない場合は、エージェントが後で leadbay_qualify_status に渡せる qualify_id UUID ハンドルを返します（ハンドルは30日間保持され、MCP を再起動しても有効です）。詳しい実例（検出 → プレビュー → インポート → qualify_status）、JSON の形式、エラーコード一覧、ツールごとの前提条件、not_in_lens の分類の意味については、MIGRATION.md を参照してください。

関連ツール：leadbay_list_mappable_fields は、標準 CRM フィールドとこの組織のカスタムフィールドをまとめて返します（mappings.fields に貼り付けられる mapping_value 付き）。省略可能な for_records パラメーターを指定すると、サンプルに対してウィザードの前処理を実行し、マッピングのヒントとカスタムフィールド名の候補を1回の呼び出しで追加します。

必要条件： LEADBAY_MCP_WRITE が 0 に設定されていないこと（0.3.0 以降はデフォルトで ON。OpenClaw では exposeWrite: true を設定する方法もあります）、Leadbay アカウントでの管理者ロール、アクティブな請求。

dry_run: true を指定すると、見込み顧客と CRM のリンクを確定せずに、ドメインの形式とウィザードへの接続を検証できます。（CRM インポートの行は引き続き表示されます。これを取り除くにはバックエンドの変更が必要です。）

環境変数

変数	必須	デフォルト	用途
LEADBAY_TOKEN	はい	—	ベアラートークン（install または login で発行するか、手動で設定します）
LEADBAY_REGION	強く推奨	（自動検出 — 下記の警告を参照）	us または fr
LEADBAY_BASE_URL	いいえ	リージョンから導出	ステージング／開発環境用の上書き
LEADBAY_MCP_ADVANCED	いいえ	未設定	"1" にすると、詳細な API ツールを公開します
LEADBAY_MCP_WRITE	いいえ	"1"（ON）	0.3.0 以降、デフォルトで ON です。"0"／"false"／"no"／"off" に設定すると、複合書き込みツール（refine_prompt、report_outreach、adjust_audience など）と、それらについて言及するシステムプロンプトが非表示になります。注：0.2.x では "true"／"yes"／"on" は OFF として扱われましたが、0.3.0 以降では ON として扱われます。
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 を明示的に設定してください。 設定しない場合、サーバーはベアラートークンを付けたまま api-us.leadbay.app と api-fr.leadbay.app の両方に並行して問い合わせるため、アカウントを管理していないバックエンドにもトークンが送信されます。このため、install および login サブコマンドでは --region が必須です。実行時の自動検出は後方互換性のためのフォールバックであり、推奨される設定ではありません。

セキュリティ

• トークンは MCP クライアントの設定ファイル内にのみ保存され、api-{region}.leadbay.app 以外にネットワーク経由で送信されることはありません。
• OpenClaw アダプターの leadbay_login ツールは MCP に登録されません。認証情報を受け取るツールを LLM に公開することは、プロンプトインジェクションのリスクとなるためです。上記のトークン設定手順を使用してください。
• leadbay_add_note ツールは、optional: true として指定された書き込み操作です。クライアントがツールごとのオプトインに対応している場合は、必要になるまで無効にしておいてください。leadbay_enrich_contacts（名前を指定した連絡先 1 件のエンリッチメント）は、0.33.4 以降、デフォルトの書き込み対象に含まれています。それ以前は詳細ツールのみで利用できました。

プライバシーとテレメトリー

@leadbay/mcp は PostHog に製品使用イベントを送信し、予期しないエラーを Sentry に報告します。Leadbay のウェブアプリと同じ方針です。PostHog は製品の使用状況（どのツールが実行されたか、実行時間、エラー率）を測定し、Sentry は、そうでなければ気付けないクラッシュを検知します。

これらのイベントは匿名ではありません。 各イベントは Leadbay アカウントのメールアドレス（distinctId = me.email）に紐付けられるため、分析では MCP のアクティビティが、同じ ID のウェブアプリのアクティビティと統合されます。これは、ウェブアプリですでに使用しているものと同じ ID モデルです。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 イベントとウェブアプリのイベントが統合されます。イベントには $groups.organization も含まれるため、組織レベルで集計できます。

送信しない情報：ツール引数の内容、レスポンス本文、見込み客のメールアドレス／電話番号、Stripe の URL、レンズの説明、適格性確認の回答。

Sentry に報告されるエラー：予期しない例外（TypeError、ネットワーク障害、解析の不具合）のみです。クォータ超過、リソース不足、認証期限切れ、課金停止など、想定されるビジネス上の結果は PostHog のみに記録されます。

オプトアウト — 最も簡単な方法は、エージェントに「テレメトリーをオフにして」（または「テレメトリーは有効？」）と尋ねることです。これにより leadbay_set_telemetry ツールが呼び出され、設定が Leadbay アカウントに保存されます。ホスト型／ウェブコネクターではリクエストごとに設定が適用されます（編集が必要なローカル設定はありません）。ローカルインストールでは、サーバーは起動時に LEADBAY_TELEMETRY_ENABLED からテレメトリーの有効／無効を決定し、アカウントの設定フラグを読み取りません。そのため、ローカルでのイベント送信も停止するには、以下のように LEADBAY_TELEMETRY_ENABLED=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. 開発者向け — ローカルビルドのテスト

npm に公開せずに、実際の MCP クライアント（Claude Desktop、Claude Code、Cursor、Codex）で MCP サーバーの変更をテストする場合に使用します。

1. ビルド

pnpm install
pnpm build

2. --local を指定してインストーラーを実行

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

ブラウザーでインストーラーウィザードが開きます。OAuth でサインインし、クライアントを選択して、「インストール」をクリックします。ウィザードは、通常の npx @leadbay/mcp@latest の呼び出しの代わりに、各クライアントの設定へ node /absolute/path/to/dist/bin.js を書き込みます。

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 を参照してください。