Hatchet MCP

hatchet-mcp

AI エージェントが Hatchet のワークフローを監視・操作できる MCP サーバーです。ステータス、実行、ログ、ワーカー、メトリクスの確認に加え、トリガー／キャンセル／再実行ができます。

理由： Hatchet には優れた API がありますが、MCP はありません。この MCP サーバーを使えば、エージェント（Claude Code／Desktop など）がワークフローの状態を確認し、操作できるようになります。

インストール

これを Claude Code／Claude Desktop の MCP 設定に追加します。

{
  "mcpServers": {
    "hatchet": {
      "command": "npx",
      "args": ["-y", "hatchet-mcp"],
      "env": { "HATCHET_CLIENT_TOKEN": "<your-hatchet-api-token>" }
    }
  }
}

Hatchet ダッシュボード → API tokens からトークンを取得してください。このトークンはサーバー URL とテナントをエンコードした JWT なので、必須の設定はこれだけです。

設定

変数	必須	説明
HATCHET_CLIENT_TOKEN	はい	Hatchet API トークン（JWT）です。サーバー URL とテナントがエンコードされているため、通常はこれだけで十分です。
HATCHET_API_BASE	いいえ	API のベース URL を上書きします。セルフホストの場合は、任意の Hatchet インスタンスを指定できます。
HATCHET_TENANT_ID	いいえ	トークンからデコードされたテナント ID を上書きします。

セルフホストする場合は、HATCHET_API_BASE に自身の Hatchet インスタンスを設定すれば、どこでも動作します。

ツール

可観測性（読み取り専用）

ツール	説明
whoami	解決された Hatchet のテナントとサーバー URL を表示し、トークンが機能することを確認します。
list_workflows	テナントのワークフロー定義を一覧表示します。
list_runs	ワークフローの実行を一覧表示します（任意の遡及期間とフィルターを指定できます）。
get_run	1 件のワークフロー実行の詳細（ステータス、タスク、エラー）を取得します。
get_run_logs	外部 ID を指定して、タスクのログ行を取得します。
list_workers	ワーカーとそのステータスを一覧表示します。
get_queue_metrics	テナントのタスク／キューのメトリクス（キューの健全性）を取得します。

アクション（稼働中の状態を変更）

ツール	説明
trigger_workflow	JSON 入力ペイロードを指定し、名前で新しいワークフロー実行をトリガーします。
cancel_runs	外部 ID を指定して、1 件以上の実行／タスクをキャンセルします。
replay_runs	外部 ID を指定して、1 件以上の実行／タスクを再実行／リトライします。

安全性

読み取りツール（whoami、list_workflows、list_runs、get_run、get_run_logs、list_workers、get_queue_metrics）は破壊的な操作を行いません。

trigger_workflow、cancel_runs、replay_runs は稼働中の状態を変更します。これらの説明には、実際の実行に影響することをエージェントやユーザーが認識できるよう、MUTATES LIVE STATE の接頭辞が付いています。

トークンにはテナント全体へのアクセス権があります。シークレットとして取り扱い、ソース管理に絶対にコミットしないでください。

開発

pnpm install
pnpm test    # vitest
pnpm build   # tsup -> dist/index.js

TypeScript／ESM で、vitest を使ってテストしています。

ステータス

v0.1.0 — すべてのツールを Hatchet Cloud で検証済みです。HATCHET_API_BASE を使えば、セルフホストのインスタンスでも動作します。trigger_workflow は安定版の /workflow-runs/trigger エンドポイントを使用します。