🧪 Official MCP Server for Debugg AI

Debugg AI — MCP サーバー

Model Context Protocol を介した AI によるブラウザーテストです。任意の URL（または localhost）を指定し、テスト内容を説明すると、AI エージェントがアプリをブラウズし、スクリーンショットとともに合格／不合格を返します。

セットアップ

Node.js 20.20.0 以降が必要です（posthog-node@^5.26.0 の推移的な要件です）。

http://localhost:... の URL をテストするには、caddy バイナリが必要です。check_app_in_browser、 probe_page、trigger_crawl は、ローカルの Caddy リバースプロキシを介して localhost のターゲットにトンネル接続します。 これは自動的にインストールされます。@radically-straightforward/caddy npm 依存関係が、通常は自分で何もインストールすることなく、 npm install／npx の実行中にお使いのプラットフォーム用の固定バージョンの Caddy をダウンロードします。現在、このパッケージがダウンロードするバイナリはこれだけです。トンネルクライアント自体は 純粋な TypeScript で、ngrok エージェントを取得していた ngrok パッケージを置き換えています。 ダウンロードが実行されなかった場合（npm install --ignore-scripts、オフライン／エアギャップ環境でのインストール）は、CADDY_BIN に 独自にインストールしたバイナリを指定してください（brew install caddy／apt install caddy／ caddyserver.com/docs/install を参照）。見つからない場合は、最初の localhost URL 呼び出し時に 明確なエラーが表示され、無言でハングすることはありません。公開 URL への呼び出し、ブラウザー以外のすべてのツール、および test_suite {action:"run"}（専用のトンネルを使用し、Caddy を完全に迂回します）には、いずれの場合も必要ありません。

debugg.ai で API キーを取得し、MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

または Docker を使用します。

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

原則として、Dockerfile の npm install 手順でも、ローカルインストールと同じ方法で caddy が自動的に取り込まれるはずです。しかし、この記事の執筆時点では、Dockerfile はビルドで必要になった複数のディレクトリ（ handlers、tools、types、config）を COPY しておらず、さらに現在は存在しない tunnels/ ディレクトリを参照し続けているため、それ以前の段階で新規ビルドが失敗する可能性があります。これは Caddy とは無関係の、以前からある不備です。現在公開されている quinnosha/debugg-ai-mcp イメージは、いずれにせよ Caddy 依存関係が追加される前のものです。Dockerfile が修正されて再ビルド・再公開されるか、別途組み込んだバイナリを CADDY_BIN に 指定するまでは、このイメージ内で localhost URL を指定して check_app_in_browser／probe_page／trigger_crawl を呼び出すと、 CaddyBinaryNotFoundError で失敗します。公開 URL への呼び出し、ブラウザー以外のツール、および test_suite {action:"run"} には、いずれの場合も影響しません。

ツール

このサーバーは 8 個のツールを公開します。3 つの ブラウザーツールと、管理対象エンティティごとに 1 つずつ用意された アクションベースのツールです。主なツールは check_app_in_browser（完全な AI エージェント）と probe_page（軽量で LLM を使用しないページプローブ）です。残りの project、environment、test_suite、test_case、executions は、それぞれ action 判別子（例：{"action":"list"}）を受け取り、実行する操作を選択します。破壊的な delete アクションには確認が必要です（対応している場合は確認を求めるプロンプト、それ以外の場合は confirm: true）。

ブラウザー

check_app_in_browser

AI ブラウザーエージェントをアプリに対して実行します。エージェントはページを移動して操作し、スクリーンショットとともに結果を報告します。localhost の URL は、デバッグトンネルサーバーを経由するよう自動的にトンネリングされます。

パラメーター	型	説明
description	string required	テスト内容（自然言語）
url	string required	対象 URL — http://localhost:3000 は自動的にトンネリングされます
environmentId	string	特定の環境の UUID
credentialId	string	特定の認証情報の UUID
credentialRole	string	ロール（例：admin、guest）で認証情報を選択します
username	string	ログイン用のユーザー名（一時的な値で、保存されません）
password	string	ログイン用のパスワード（一時的な値で、保存されません）
loginCredentials	array	タスクの途中でエージェントがアクセスするログインに使うアカウント — [{username, password, label?}]
useEnvironmentCredentials	boolean	デフォルトは true です。false にすると、環境に保存された認証情報の自動入力を禁止します。アカウントを指定しない場合は、一切ログインしません
freshSession	boolean	デフォルトは false です。true にすると、そのアカウント用に保持されているウォームセッションを再利用せず、実際のログインを強制します
auth	object	認証の前提条件 — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	string	自動検出された Git リポジトリ名を上書きします（例：my-org/my-repo）

1 回の呼び出しにつき、焦点を絞ったチェックを 1 つ実行します。エージェントの内部予算は約 25 ステップです。範囲の広いテストスイートは、複数回の呼び出しに分けてください。

認証情報：説明文ではなくパラメーターとして渡してください

description にアカウント名を書くだけでは、エージェントはそのアカウントを使用しません。環境に保存された認証情報にフォールバックするため、アプリが誤ったアカウントを拒否すると、アプリケーションの障害のように見えてしまいます。パラメーターとして渡した値は、最初のログインだけでなく、実行中のすべてのログインで環境のデフォルトより優先されます。

• username / password（または credentialId / credentialRole）— 実行時に使用するアカウントです。
• auth.username / auth.password — auth.precondition: "login" も使う場合、前提条件でのログインに使うアカウントを固定します。
• loginCredentials — タスクの途中でエージェントが到達するログインフォームで使うアカウントです。パスワードを設定する → サインイン画面に戻される → 作成したばかりのアカウントでログインする といったフローでは、呼び出しを分けるとブラウザーの状態が失われるため、この方法を使います。

デフォルトのテストユーザーへのサイレントなフォールバックによってチェックが無効になる場合は、useEnvironmentCredentials: false を設定してください。

クロスドメイン SSO の場合：実行中、認証情報が入力されるのはアプリ自身のホストとそのサブドメインのみです。別のドメインにあるサインインページは offscope_host として拒否されます。ID プロバイダーのホストを、環境の authorizedCredentialHosts に追加してください（environment を参照）。

ログインがまったく不要なページをチェックする場合：useEnvironmentCredentials: false を渡し、アカウントを指定しないでください。この組み合わせは文字どおり「ログインしない」という意味で、ログインフォームを探す代わりに、認証を完全にスキップします。公開ページ、マーケティングサイト、ドキュメント、認証前のページなどに使います。また、こちらのほうが高速です。デフォルト（auto）では、エージェントはページ上の「ログイン」リンクをたどってページ外に移動し、何かを評価する前に、環境に保存されたアカウントでログインを試みます。

セッションの再利用：チェック結果が「ログインフォームなし」になる理由

実行のたびにログインするわけではありません。ログインが検証されると、バックエンドはそのアカウントのセッションを取得して復元し、同じアカウントでの次回の実行時にログインを完全に省略します。そのため、チェック結果が正当に submitted: false でログインフォームなしとなることがあります。すでにサインイン済みだからです。セッションが復元された実行は、logins 内で reason: "restored_session" と報告されるため、フォームが本当に見つからなかった実行と区別できます。

セッションはアカウントごとに管理されるため、別のアカウントを指定しても、他のユーザーのセッションが再利用されることはありません。再利用を回避する方法は2つあります。

• 1回の呼び出しに freshSession: true を指定します。今回は実際にログインしてから、再度セッションを取得します。ログインフロー自体をチェックする場合、保存済みセッションが古いと思われる場合、またはペルソナを切り替える手段がログアウトしかないアプリの場合に使用してください。
• environment ツールで action: "clearSessions" を指定します。保存済みセッションを無効化し、以降の実行でログインするようにします。username / credentialId で対象を絞り込めます。対象を指定せずにクリアする場合は、その環境のすべてのアカウントが再認証されるため、確認が必要です。

action: "sessions" を使うと、環境が現在保持しているセッションと、それぞれが再利用されるかどうかを確認できます。

結果には実際に使用されたアカウントが報告されるため、誤ったアカウントが使われた場合も、アプリの不具合のように見えてしまうことはありません。

"logins": [
  { "username": "[email protected]", "source": "task", "submitted": true, "authenticated": true },
  { "username": "[email protected]", "source": "env_default", "submitted": false, "authenticated": false,
    "reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
  "requested": "[email protected]",
  "used": ["[email protected]"]
}

source は task | explicit | credential_id（指定したアカウント）または env | env_default（環境に保存されたアカウント）です。submitted が true になるのは、認証情報が実際に入力されて送信された場合のみです。reason には発生した内容（例：offscope_host、restored_session）が示され、detail がある場合は、その内容を人が読める形で説明します。offscope_host による拒否の場合は、ホスト名とその認可方法が記載されます。credentialWarning は、アカウントを指定したにもかかわらず、別のアカウントに対応する環境のデフォルトアカウントが実際に送信された場合にのみ表示されます。ログインが拒否された場合やスキップされた場合は表示されません。指定したアカウントを解決できず、別のアカウントへの置き換えを実行が見送った場合は、loginError が表示されます。

成功した実行では、スクリーンショットとともに browserSession ブロックが返されます。これには、取得した HAR（ネットワークトレース全体）とコンソールログ（すべての JS コンソールメッセージ）の、事前署名付き S3 URL が含まれます。これらを使って、型チェックや単体テストでは検出できない再取得ループ、ハイドレーションエラー、その他の実行時の問題を検出できます。

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

URL は有効期間の短い事前署名付き S3 URL です。更新するには、親実行を executions {action:"get", uuid} で再取得してください。harStatus / consoleLogStatus によって、'downloaded'（URL から取得可能）、'not_available'（ページから何も出力されなかった）、'failed'（取得に失敗した）を区別できます。新しい実行では、エージェントの完了後に取得データが非同期でアップロードされるため、URL が null になることがよくあります。ステータスが 'downloaded' になるまで executions {action:"get", uuid: executionId} をポーリングしてください。Authorization / Cookie / token/secret/api_key ヘッダーは、アーティファクトが保存される前にサーバー側でマスキングされます。

trigger_crawl

プロジェクトのナレッジグラフにデータを追加するため、サーバー側のブラウザーエージェントによるクロールを実行します。localhost の URL は自動的にトンネリングされます。成功した取り込みでは knowledgeGraph.skipped === false となり、{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} が返されます。crawlSummary と knowledgeGraph に含まれるのは、バックエンドのクロール／インポートノードが報告したキーのみです。件数が報告されていない場合、その項目は省略され、0 が補われることはありません。完了したクロールにも、browserSession ブロック（上記と同じ形式の HAR およびコンソールログの URL）が含まれます。

probe_page

LLMを使わない軽量な一括ページプローブです。 1〜20個のURLを渡すと、それぞれのページに移動してコンテンツが落ち着くまで待機します（DOMの変化が一定時間止まるまで待機します。上限があり、ネットワークが静かになるのを待つことはありません。稼働中のアプリではネットワークが静止しないためです）。その後、レンダリングされた状態（スクリーンショット、ページのメタデータ、構造化されたコンソールエラー、ネットワークの概要）を返します。エージェントのループもLLMのコストもシナリオのアサーションもありません。check_app_in_browserの60〜150秒のエージェントループでは大げさすぎる「/settingsを壊していないか」の確認、リファクタリング後の複数ルートのスモークテスト、PRごとのCIスイープ、すばやい稼働確認に使用できます。

パラメーター	型	説明
targets	array 必須	1〜20件のエントリー：[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	string 必須	公開URLまたはlocalhost（自動でトンネル接続）
targets[].waitForLoadState	enum	'domcontentloaded'（デフォルト。加えてコンテンツが落ち着くまで上限付きで待機）／'load'（サードパーティの埋め込みコンテンツも読み込み完了まで待機）／'networkidle'（指定できますが、実行されません。稼働中のサイトではネットワークがアイドル状態にならないためです）
targets[].waitForSelector	string	ページ遷移後に待機する任意のCSSセレクター
targets[].timeoutMs	number	URLごとのタイムアウト。1000〜30000（デフォルトは10000）
includeHtml	boolean	各結果に生のHTMLを含めます（デフォルトはfalse）
captureScreenshots	boolean	ターゲットごとにPNGを1枚返します（デフォルトはtrue）

バッチ内のすべてのターゲットで1つのセッショントンネルを共有しますが、同じポート（またはすべて公開URL）のバッチでは、バックエンドの実行を1回だけ共有します。同じポート上の5つのURLを1回の呼び出しで処理する方が、URLごとに5回並列で呼び出すより大幅に高速です。複数のローカルポートが混在するバッチは、ポートグループごとにバックエンドを順番に実行します（呼び出しは1回のままで、元の順序でマージされたresults[]が返されますが、バックエンドとの往復は1回ではなくN回になり、遅くなります。ただし拒否はされません）。URLごとのerrorフィールドによりバッチの堅牢性が保たれます。1つのターゲットに失敗しても、ほかのターゲットは失敗しません。

networkSummaryの集約キーはorigin + pathnameです。同じエンドポイントに繰り返しアクセスする再取得ループ（?n=0..4）は件数付きの1つのエントリーにまとめられるため、/api/pollがcount: 47で表示されると、ユーザーが当初求めていた「無限再取得ループ」を特定するためのシグナルになります。

パフォーマンスの目安：URL 1件で10秒未満、20件で25秒未満。localhostの停止中ポートはワークフローの実行を消費せず、2秒未満でLocalServerUnreachableを返します。

project

アクション	パラメーター	結果
get	{uuid}	要点をまとめたプロジェクトの詳細
list	{q?, page?, pageSize?}	ページ分割された概要
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	作成されたプロジェクト

チームとリポジトリは、UUIDまたは名前で解決できます（大文字と小文字を区別しない完全一致。該当なしの場合はNotFound、複数ある場合はAmbiguousMatch）。update／deleteはありません。プロジェクトの名前変更や削除は、DebuggAIのウェブアプリから行ってください。

environment

アクション	パラメーター	結果
get	{uuid, projectUuid?}	認証情報がインライン化された環境（パスワードは返されません）
list	{projectUuid?, q?, page?, pageSize?}	ページネーションされた環境。各環境に認証情報の配列が含まれます
create	{name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?}	作成された環境（認証情報を任意で登録します）
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}	更新された環境。認証情報の操作は 削除 → 更新 → 追加 の順で実行されます
delete	{uuid, projectUuid?, confirm?}	環境を削除します（認証情報も連鎖して削除されます） — 確認が必要です
sessions	{uuid, username?, credentialId?}	環境が保持するキャプチャ済みログインセッション。アカウントごとに、それぞれ独自の isUsable を持ちます
clearSessions	{uuid, username?, credentialId?, confirm?}	セッションを無効化し、次回の実行で実際にログインするようにします — 対象を絞らない削除には確認が必要です

projectUuid を省略すると、git リポジトリから自動的に解決されます。認証情報ごとの失敗は credentialWarnings[] に表示され、環境の操作は妨げられません。

authorizedCredentialHosts には、アプリ自体のホスト以外で、この環境の認証情報を実行時に入力できるホストを指定します — クロスドメイン SSO では、IdP のホストをここに追加してください（例：["auth.example.com"]）。ホスト名のみを指定してください。スキーム、パス、ポート、ワイルドカードは指定できません（アプリのホストのサブドメインはすでに対象範囲内です）。update ではリストが置き換えられます。[] を指定するとクリアされます。サーバーが対応している場合、get／list はこのリストを返します。レスポンスには保存されたリストが含まれます。サーバーがリストを保存しなかった場合（古いサーバーはこのフィールドを無視します）は、成功として通知されず、代わりに authorizedCredentialHostsWarning: {requested, returned} が返されます。

sessions／clearSessions は、ログインを省略するためにバックエンドが再利用する認証済みセッションを管理します（セッションの再利用を参照）。セッションの内容は返されません — セッション Cookie はベアラー認証情報です。clearSessions はセッションの行を削除せず、無効としてマークします。そのため、再利用は直ちに停止し、キャプチャ履歴は引き続き参照できます。

test_suite

アクション	パラメーター	結果
list	{projectUuid|projectName, search?, page?, pageSize?}	ページネーションされたスイート。ステータスと合格率を含みます
create	{name, description, projectUuid|projectName}	作成されたスイート
run	{suiteUuid|(suiteName+project), targetUrl?}	すべてのテストを非同期で実行します
results	{suiteUuid|(suiteName+project)}	スイートとテストごとの結果
delete	{suiteUuid|(suiteName+project), confirm?}	論理削除 — 確認が必要です

test_case

アクション	パラメーター	結果
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	作成されたテストケース（自動実行されません）
update	{testUuid, name?, description?, agentTaskDescription?}	更新されたテストケース
delete	{testUuid, confirm?}	論理削除 — 確認が必要です

executions

アクション	パラメーター	結果
get	{uuid}	詳細情報（nodeExecutions、state、errorInfo）とスクリーンショット／GIF の成果物
list	{status?, projectUuid?, page?, pageSize?}	ページネーションされた概要

バックエンドからの 404 は、{error: 'NotFound', message, uuid} を含む isError: true として表示されます。認証情報は常にパスワードを除いて返されます。

ページネーション

すべての list レスポンスはページネーションされます。レスポンスの形式：

{
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

任意で page（1 から始まる。既定値は 1）と pageSize（既定値は 20、最大 200。上限を超える値はクランプされます）を指定します。レスポンスが通知なく切り詰められることはありません。

get は単一のオブジェクトを単数形の名前で返します — {project}、{execution}、{project, environment} — pageInfo は含まれません。

リソース

ツールに加えて、サーバーは読み取り専用のエンティティを MCP リソースとして公開しているため、 クライアントはこれらを参照し、@メンションしてコンテキストとして使用できます。

URI	内容
debugg-ai://projects	すべてのプロジェクト（最初のページ）
debugg-ai://environments	自動検出されたプロジェクトの環境
debugg-ai://executions	最近の実行（最初のページ）
debugg-ai://project/{uuid}	1 つのプロジェクトの詳細全体
debugg-ai://environment/{uuid}	1 つの環境（認証情報はインライン、パスワードは伏せ字）
debugg-ai://execution/{uuid}	1 つの実行の詳細（ノードの詳細全体とアーティファクトへのリンク）

読み取りは project ／ environment ／ executions ツールと同じハンドラーにディスパッチされるため、データと認証は同一です。リソースは追加機能です。 リソースに対応していないクライアントは、引き続きツールを使用できます。

セキュリティ上の不変条件

• パスワードは書き込み専用です。どのツールのレスポンス本文にも表示されません。
• トンネル URL（*.tunnel.debugg.ai および、過去の実行が現在も参照している廃止済みの *.ngrok.debugg.ai）は、エージェントが作成したテキストを含む、すべてのブラウザーエージェントのレスポンスから除去されます。
• バックエンドからの 404 は、スローされる例外ではなく、isError: true と {error: 'NotFound', ...} として表面化します。
• DEBUGGAI_API_KEY がない場合、最初の呼び出し時に構造化されたツールエラーとして表面化します。サーバーは通常どおりツールを登録し、一覧表示します。

v6.0.0 への移行（バックエンドによる判定、MCP が作成するテキストなし）

実行の判定結果は pass | fail | error で、バックエンドの reason がそのまま中継されます。テストを一度も試行しなかった実行では、 outcome: null、skipped: true、skipReason が返されます。

削除された項目	置き換え
success	outcome
failureCategory	outcome + reason
stepsTaken / stepsBudget / stepsRemaining	budget: {maxSteps, usedSteps}
failedNode	errorInfo
get → projects[0] / executions[0] / environments[0] + pageInfo + filter	{project} / {execution} / {project, environment}
警告や結果の message / note	構造化フィールドのみ

一覧については、CHANGELOG.md 6.0.0 を参照してください。

v3.0.0 への移行（アクションベースのツール）

v3 では、動詞ごとに分かれていた 20 個のツールが、8 個のアクションベースのツールに統合されました。旧ツール → 新しい tool {action}：

削除された項目	置き換え
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project、delete_project	削除 — DebuggAI Web アプリを使用してください
search_environments	environment {action:"get"} / {action:"list"}
create_environment / update_environment / delete_environment	environment {action:"create"|"update"|"delete"}
create_test_suite / search_test_suites / run_test_suite / get_test_suite_results / delete_test_suite	test_suite {action:"create"|"list"|"run"|"results"|"delete"}
create_test_case / update_test_case / delete_test_case	test_case {action:"create"|"update"|"delete"}
search_executions	executions {action:"get"|"list"}
trigger_crawl の headless パラメーター	削除 — 常にヘッドレスで実行

delete アクションには、確認（確認プロンプト、または confirm: true）が必要になりました。MCP を再起動すると、クライアントに新しいインターフェースが反映されます。

v1.x からの移行（v2.0.0 での破壊的変更）

v2 では、22 個のツール構成が 11 個に集約されました。旧ツールから新ツールへの対応関係：

削除されたツール	置き換え
list_projects, get_project	search_projects（uuid モードまたはフィルターモード）
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — 認証情報は各環境にインラインで含まれます
create_credential	create_environment({credentials: [...]}) でシードするか、update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — 曖昧さに対処した名前解決
list_executions, get_execution	search_executions
cancel_execution	削除 — バックエンドのスピンダウンは自動で行われます

レスポンス形式の変更：リストレスポンスの count フィールドは削除されました。pageInfo.totalCount を使用してください。

設定

環境変数	必須	用途
DEBUGGAI_API_KEY	はい	バックエンド API キー。別名：DEBUGGAI_API_TOKEN、DEBUGGAI_JWT_TOKEN。
DEBUGGAI_API_URL	いいえ	バックエンドのベース URL。デフォルトは https://api.debugg.ai です。
DEBUGGAI_TOKEN_TYPE	いいえ	token（デフォルト）または bearer。
DEBUGGAI_EVAL_TEMPLATE	いいえ	check_app_in_browser がディスパッチする App Evaluation ワークフローの スラッグ を上書きします。デフォルトは flow/e2es/app-eval です。ディスパッチ先をこのスラッグに固定することで、バックエンドのテンプレート名が変更されても動作に影響しません。
LOG_LEVEL	いいえ	error / warn / info（デフォルト）/ debug。
POSTHOG_API_KEY	いいえ	埋め込みテレメトリプロジェクトキーを上書きします（例：プライベートフォーク）。
DEBUGGAI_TELEMETRY_DISABLED	いいえ	テレメトリを完全に無効にするには、1 / true / yes / on を設定します。

DEBUGGAI_API_KEY=your_api_key

リモート／HTTP トランスポート（任意）

デフォルトでは、サーバーは stdio（ローカルの npx）で通信します。代わりに、ステートレスな Streamable HTTP と OAuth を使用する、ホスト型のマルチユーザー向けリモート MCP として実行することもできます。

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

これは OAuth の リソースサーバーです。すべての POST /mcp リクエストに Authorization: Bearer <token> が必要です。トークンがない、または無効な場合は、 RFC 9728 メタデータを指す WWW-Authenticate を含む 401 が返され、クライアントは 通知された認可サーバーに対して OAuth フローを実行します。ベアラーはリクエスト単位で適用され、 api.debugg.ai が検証します。

エンドポイント	用途
POST /mcp	MCP Streamable HTTP（ベアラーで保護）
GET /.well-known/oauth-protected-resource	RFC 9728 メタデータ（認可サーバーの検出）
GET /health	ロードバランサー／ECS のヘルスチェック

環境変数	デフォルト	用途
DEBUGGAI_MCP_TRANSPORT	stdio	リモートトランスポートを使用するには http に設定します
PORT	3000	HTTP のリッスンポート
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	このサーバーのパブリックリソース URL（RFC 9728 の resource）
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	クライアントに通知する認可サーバー
DEBUGGAI_TOKEN_TYPE	token	OAuth トークンを Authorization: Bearer として転送するには bearer に設定します

stdio でインストールする場合、これらの設定は不要です。

複数レプリカでのデプロイ（ロールアウト前に可否を判断してください）： トンネルの状態（セッショントンネル、 その Caddy インスタンス、およびポートルートのロック）はプロセス内にあり、ベアラートークンのハッシュを使って呼び出し元ごとに管理されます。プロセス間の連携はありません。通常の ラウンドロビン方式のロードバランサーの背後で複数のレプリカを実行すると、同じ呼び出し元からのリクエストが別々のレプリカに振り分けられ、セッション全体で 1 つではなく、アクセスしたレプリカごとに 1 つのトンネルが作成されることがあります（レプリカ数が上限です。既存の 55 分間のアイドル時自動シャットダウンによって解消されます。単一のツール呼び出しは処理中ずっと 1 つのレプリカで実行されるため、セッションをまたぐ整合性の問題は発生しません）。複数レプリカの HTTP デプロイで意図した「セッションごとに 1 つのトンネル」という動作を実現するには、ロードバランサーでセッションアフィニティルーティングを設定してください（getSessionKey() が導出するものと同じ識別情報、つまり実際には呼び出し元の Authorization ベアラートークンをキーとしたスティッキー方式／コンシステントハッシュ方式）。詳しい説明と、未設定の場合に正直に想定される縮退動作については、 docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 を参照してください。

テレメトリ

MCP サーバーではデフォルトでテレメトリが有効です。書き込み専用の PostHog プロジェクトキー（phc_*）が組み込まれており、チームはインストール全体にわたるキャッシュヒット率、ポーリング間隔、トンネルの信頼性、その他の運用メトリクスを確認できます。収集されるイベントは次のとおりです。

イベント	発生時
tool.executed / tool.failed	ツール呼び出しごと
workflow.executed	ブラウザーエージェントの実行ごと（pollCount、durationMs、finalIntervalMs を記録）
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	トンネルのライフサイクルイベントごと
template.lookup / project.lookup	キャッシュのヒット／ミス。キャッシュミス時の呼び出しでは durationMs を記録

プライバシーに関する方針：

• 固有 ID は SHA-256(api_key).slice(0, 16) です。生のキーや個人を特定できる情報は使用しません。
• PostHog の規約上、phc_* キーは書き込み専用であり、ソースコードに埋め込んでも安全です。
• DEBUGGAI_TELEMETRY_DISABLED=1 を設定すると、テレメトリを完全にオプトアウトできます（何もしないプロバイダーに切り替わり、プロセスの外部にイベントは送信されません）。

有効なモードは起動時にログへ記録されます。

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

ローカル開発

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

評価スイートはビルド済みの MCP サーバーをサブプロセスとして起動し、実際のバックエンドに対してすべてのツールを実行して、フローごとのアーティファクトを scripts/evals/artifacts/<timestamp>/ に書き込みます。個別のシナリオについては scripts/evals/flows/ を参照してください。

MCP の登録：debugg-ai-local と debugg-ai

このリポジトリには、node dist/index.js（ビルド済みの最新のローカルコード）を参照する、debugg-ai-local という名前のプロジェクトスコープのサーバーを登録する .mcp.json が含まれています。これは、Claude Code の作業ディレクトリがこのリポジトリの場合にのみ有効になります。

ほかのプロジェクトでは、公開されている npm パッケージを使用するユーザースコープの debugg-ai 登録を使用してください。

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

ここでコードを編集した後、npm run mcp:local（再ビルドするだけのコマンド）を実行すると、次回 debugg-ai-local を起動したときに変更が反映されます。

リンク

ダッシュボード · ドキュメント · イシュー · Discord

---

Apache-2.0 ライセンス © 2025 DebuggAI