Healthchecks

healthchecks-mcp

Healthchecks 向けの Model Context Protocol（MCP）サーバーです。Healthchecks は、cron ジョブやスケジュールされたタスクのデッドマンスイッチとして機能し、ジョブからの通知が止まるとアラートを送信します。ホスト型サービスとセルフホストのインスタンスのどちらにも対応しています。

Claude Code、Claude Desktop、Codex などの MCP クライアントから、スケジュールされたジョブの正常性を確認したり、失敗したジョブが報告した出力を読んだり、チェックを作成・調整したりできます。取り消せない操作には確認トークンが必要で、書き込みツールをすべて無効にすることもできます。

ツール数は14個が上限であり、最低数ではありません。 HEALTHCHECKS_ALLOW_TOOLS=essential を設定すると、厳選された7個だけが登録されます。モデルは14個から選ぶよりも、7個からのほうが適切なツールをはるかに確実に選べます。詳しくは読み込むツールの選択をご覧ください。

異なる点

ping の本文を読み取ります。 get_ping_body は、ジョブが失敗を報告したときに実際に出力した内容を返します。どのチェックがダウンしているか、いつからか、どのくらいの頻度かといった、それ以外の質問はすべて、この情報から一段階先にあります。また、これは他の Healthchecks MCP サーバーが省いているエンドポイントです。

読み取り専用の API キーも正しく使えます。 Healthchecks は読み取り専用キーに異なるオブジェクトを返します。uuid、ping_url、channels はなく、代わりに 40 文字の unique_key があります。このサーバーではどちらの値でもチェックを指定でき、get_api_key_info を使えば、設定したキーの種類とアクセスできないツールを事前に確認できます。送信済みのキーに対して 401 missing api key が返されるまで待つ必要はありません。

チェックに ping を送ることはありません。 ping を送ることで、ジョブの実行を報告します。モデルが ping を送信できるツールがあると、停止したジョブを稼働中に見せかけられてしまいます。これは監視で絶対に許してはいけないことです。意図的に公開していない機能をご覧ください。

この API の注意点を把握しています。 timeout と schedule は併用できません。上流側で一方が黙って破棄されるためです。タグは空白区切り、キーワードはカンマ区切りとして検証されます。指定がなければ、新しいチェックにはすべてのインテグレーションが設定されます。API のデフォルトでは、どの通知も送らないチェックが作成されるためです。

要件

• Node.js ≥ 22
• Healthchecks プロジェクトの API キー — Project Settings → API Access。キーはアカウント単位ではなくプロジェクト単位で、正確に 32 文字です。

設定

変数	必須	説明
HEALTHCHECKS_API_KEY	はい	プロジェクト API キーです。読み取り専用キーではツールの一部のみ利用できます。詳しくは以下をご覧ください
HEALTHCHECKS_URL	いいえ	セルフホストインスタンスのサイトルート。例：https://hc.example.net。デフォルトは https://healthchecks.io です
HEALTHCHECKS_READ_ONLY	いいえ	true にすると、読み取りツールのみを登録します
HEALTHCHECKS_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* のプレフィックス、または厳選されたプリセットを指定する essential
HEALTHCHECKS_DENY_TOOLS	いいえ	同じ構文を使用します。HEALTHCHECKS_ALLOW_TOOLS で残った項目から除外されます
HEALTHCHECKS_INSECURE_TLS	いいえ	true にすると、自己署名証明書を許可します（この接続にのみ適用）
ELICITATION	いいえ	false にすると、承認ダイアログを2回の呼び出しによるトークンに置き換えます。プレフィックスは付きません

HEALTHCHECKS_URL はサイトルートであり、API ルートではありません。https://hc.example.net を指定してください。 https://hc.example.net/api/v3 ではありません。API ドキュメントの例では常に長い形式が使われているため、どちらも受け付けますが、サフィックスは削除されます。

https:// を使用してください。 通常の http では API キーが暗号化されずに送信されます。ホストがローカルでない場合、サーバーは警告を出力します。自己署名証明書には、HEALTHCHECKS_INSECURE_TLS よりも適切な内部 CA を使用してください。

API キーがなくてもサーバーは起動してツールを一覧表示するため、レジストリやインスペクターから情報を取得できます。ただし、get_status 以外のすべての呼び出しは API に接続せず、セットアップ手順を表示して失敗します。

読み取り専用キー。 Healthchecks では、読み取りのみを行う list_pings、get_ping_body、list_integrations の3つのツールも、読み書き可能なキーがなければ利用できません。読み取り専用キーでは、これらに加えて5つの書き込みツールも失敗します。

この失敗は権限の問題のようには見えません。API は 401 {"error": "wrong api key"} と応答するため、キーが間違っているか、存在しないかのように見えます。実際にはそうではありません。これら3つのツールは、実際に起きたことを伝えます。get_api_key_info は設定されているキーの種類を報告します。また、これらのツールを一切提示しないようにするには、HEALTHCHECKS_DENY_TOOLS を使うのが簡単です。

読み込むツールの選択

HEALTHCHECKS_ALLOW_TOOLS と HEALTHCHECKS_DENY_TOOLS には、カンマ区切りでツール名を指定します。末尾に * を付けると、ファミリー全体に一致します。essential は、厳選されたプリセットです。list_checks、get_check、list_pings、list_flips、create_check、update_check、resume_check が含まれ、ツールリファレンスではその旨が示されています。

HEALTHCHECKS_ALLOW_TOOLS=essential
HEALTHCHECKS_ALLOW_TOOLS=list_*,get_check
HEALTHCHECKS_DENY_TOOLS=delete_check,pause_check

どのツールにも一致しない項目があると、起動は中断され、その項目名が示されます。これにより、入力ミスによってツールが気付かないうちに非表示になることはありません。ツールが見つからないときに、環境変数が原因だと突き止めるのは簡単ではありません。フィルターされたツールは登録されないため、tools/list にも表示されず、tools/call からも認識されません。これは HEALTHCHECKS_READ_ONLY によって書き込みツールが使えない場合と同じです。

これらのサーバーを複数同時に実行する場合は、もう一つの選択肢として mcp-hub があります。その /hub エンドポイントは、各サーバーのツールを6つのメタツールに置き換えます。

インストール

Claude Code

claude mcp add healthchecks-mcp -- npx -y healthchecks-mcp

Claude Desktop

{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_API_KEY": "…"
      }
    }
  }
}

Codex

[mcp_servers.healthchecks-mcp]
command = "npx"
args = ["-y", "healthchecks-mcp"]
env = { HEALTHCHECKS_API_KEY = "…" }

Docker

docker run --rm -i \
  -e HEALTHCHECKS_API_KEY=… \
  ghcr.io/ni-c/healthchecks-mcp

セルフホストインスタンスの場合は、-e HEALTHCHECKS_URL=https://hc.example.net を追加します。

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT connectors、Claude on the web、 Cursor、LibreChat）は、mcp-hub 経由で healthchecks-mcp にアクセスします。1 つの コンテナが複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、単一のパスワードによる OAuth 2.1 ログインと、OAuth を利用できないクライアント向けの長期間有効なトークンを備えています。その /hub エンドポイントは、すべてのサーバーを 6 つのメタツールの背後に配置するため、1 つのコネクターから、モデルのコンテキストに N×ツールスキーマを含めずにすべてのサーバーにアクセスできます。また、両方のプロトコルリビジョンに対応しています。このサーバーが問いかける質問は、mcp-hub を通じて相手側の担当者に届きます。

/config/mcp.json は Claude Code の形式を使用するため、すでに設定済みのエントリーをそのまま使用できます。

{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_URL": "https://hc.example.net",
        "HEALTHCHECKS_API_KEY": "…",
        "HEALTHCHECKS_ALLOW_TOOLS": "essential"
      },
      "denyTools": ["delete_check,pause_check"]
    }
  }
}

ここでの allowTools と denyTools は、サーバーごとに適用される hub 独自のフィルターです。env 内の *_ALLOW_TOOLS とは異なります。その違いと、間違いやすい点については、クライアントガイドをご覧ください。

ツール

読み取りツールは常に登録されます。🔑 は、読み取り専用であっても Healthchecks に読み書きキーを要求されるツールを示します。👤 は、操作の前に確認トークンを要求するツールを示します。

ツール	説明
list_checks	tag、slug、status で絞り込んだ、プロジェクト内のチェック
get_check	UUID または unique_key で指定した、すべてのフィールドを含む 1 件のチェック
list_pings 🔑	チェックの最近の ping。新しい順
get_ping_body 🔑	1 件の ping とともにジョブが POST した本文（出力）
list_flips	チェックのアップ／ダウンの遷移と、期間
list_integrations 🔑	通知インテグレーションと、書き込みツールで受け付けられる UUID
list_badges	タグごと、およびプロジェクト全体のステータスバッジ URL
get_status	インスタンスにアクセスできるかどうか。API キーは不要
get_api_key_info	インスタンス、キーの種類、およびそのキーで実行できない操作

HEALTHCHECKS_READ_ONLY=true を設定していない場合、書き込みツールが登録されます。

ツール	説明
create_check	チェックを作成します。channels で指定しない限り、すべてのインテグレーションに通知します
update_check	指定したフィールドを変更します。channels はリストに追加するのではなく置き換えます。空のリストは拒否されます
pause_check	ping を待ち受けるチェックを停止し、アラートも止めます。resume_check で再開できます
resume_check	一時停止中のチェックを new 状態に戻します
delete_check 👤	チェックを削除します。UUID は復元できません

構造化出力

各ツールは outputSchema を宣言し、テキストブロックとともに structuredContent を返すため、クライアントは文章を解析せずに結果を利用できます。

{
  "untrusted": true,
  "source": "healthchecks",
  "checks": [{ "id": "…", "name": "Nightly Backup", "status": "up" }],
  "total_in_project": 12,
}

インスタンスから何らかの情報を報告する各ツールには、フィールドとして untrusted: true と source: "healthchecks" が含まれます。チェック名、説明、そして何よりログに記録された ping の本文は ping を実行した人が書き込むものであり、ping URL は監視対象のすべてのホストの cron ジョブに設定されています。get_api_key_info にはこれらのフィールドはなく、get_status にはインスタンスが OK 以外の内容を返した場合にのみ含まれます。単なる OK はこのサーバー自身の文であり、すべてにマーカーを付けても意味のないマーカーになるだけです。

このサーバーが構築するフィールドは正確に記述されています。チェックレコードは未定義のフィールドを許容します。これは、normalizeCheck がセルフホスト可能なリリースで追加されたフィールドをそのまま通過させ、SDK が結果を送信する前にすべてスキーマに照らして検証するためです。

意図的に公開していないもの

• Ping の実行。 サーバーが ping URL を呼び出すことはありません。Ping はジョブの実行を知らせる手段です。ping を実行できるツールがあれば、モデル、あるいはモデルが読み取ったテキストによって、実行されていないジョブを成功として報告できてしまいます。また、緑色のステータスに誘導できる監視システムは、何もないよりも悪いものです。
• Ping キー。 Management API から読み取ることはできず、このサーバーもキーを要求しません。
• インテグレーションの作成。 API にそのエンドポイントはありません。インテグレーションは Web UI で設定します。list_integrations で読み取れます。
• デフォルトでの unique アップサート。 create_check はこれを受け付け、使用した場合は結果ではっきりと示します。これは作成処理を、既存のチェックへの通知なしの更新に変えるためです。

安全性

• delete_check ではユーザーに確認を求めます。 クライアントが MCP elicitation に対応している場合は、モデルが代わりに回答できない実際のダイアログを表示します。対応していない場合は、そのチェックと操作だけに紐付いた短期間有効なトークンに切り替え、誰かが承認したかのように装わず、その旨を伝えます。pause_check では意図的に確認を求めません。resume_check で元に戻せ、その間に失われるものはありません。また、取り消し可能な変更の前にダイアログを表示するのは、人々に読まずにチェックを入れることを覚えさせるようなものです。ユーザーへの確認を参照してください。
• 確認プロンプトで Healthchecks の内容を引用することはありません。 チェック名と説明は、このサーバーが制御できない自由入力テキストであり、モデルが読み取ります。
• Ping の本文とチェックの説明には、信頼できないデータとしてマークを付けます。 チェックに ping できるものなら、これらの内容に書き込めるためです。
• エラー本文は切り詰められ、HTML のエラーページは破棄されます。また、ストリーム中にすべてのレスポンスにバイト数の上限が適用されます。Management API はページネーションを行いません。
• HEALTHCHECKS_READ_ONLY=true の場合、書き込みツールは登録されません。HEALTHCHECKS_DENY_TOOLS を使うと、同じ方針でさらに細かく制限できます。フィルタリングされたツールは構築されず、呼び出し時に拒否されることもありません。
• API キーは読み取り後に process.env から削除され、リクエスト本文に含まれることはありません。

ドキュメント

完全なガイド、ツールリファレンス、安全性に関する注意事項は healthchecks-mcp.ni-c.de（ソースは docs/）にあります。

開発

npm install
npm run lint && npm run build && npm run test:coverage

リリース

1. CHANGELOG の項目を追加し、package.json のバージョンを上げます。
2. npm run lint && npm run build && npm run test:coverage
3. コミットし、署名付きタグをプッシュします：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

リリースワークフローは npm に公開し（Trusted Publishing、provenance 付き）、CHANGELOG のセクションから GitHub リリースを作成して、MCP Registry のエントリーを更新します。

貢献

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.mdをご覧ください。脆弱性については、公開 Issue ではなく非公開での報告をご利用ください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel