Hatchet Mcp

io.github.ElliotPadfieldPublished by GitHub account ElliotPadfieldv0.1.1Updated Oct 24, 2026

Observe and operate Hatchet workflows from an AI agent — runs, logs, trigger, cancel, replay.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Local MCP server that lets an AI assistant inspect and operate Hatchet workflows: runs, logs, workers, metrics, plus trigger, cancel and replay.

What you can do
  • Check the resolved tenant and server URL and confirm the token works
  • List workflow definitions, workflow runs and workers, and read one run's status, tasks and errors
  • Fetch log lines for a task and read queue health metrics
  • Trigger a new workflow run by name with a JSON input payload
  • Cancel or replay one or more runs or tasks by external id
When to use it
Useful when you run Hatchet workflows and want an assistant to diagnose failures, read run logs and queue health, or start, cancel and retry runs without switching to the dashboard.
Requirements
Runs locally over stdio, typically launched with npx from the hatchet-mcp npm package, so Node.js is needed. Requires a Hatchet API token in HATCHET_CLIENT_TOKEN, obtained from the Hatchet dashboard; the JWT encodes the server URL and tenant. Optional HATCHET_API_BASE and HATCHET_TENANT_ID override the endpoint and tenant, for self-hosted instances.
Before you install
The token grants full tenant access and should be treated as a secret and never committed. trigger_workflow, cancel_runs and replay_runs change live state and affect real runs, so confirm before letting an assistant use them. The token and workflow data are sent to the configured Hatchet instance.

Installation

In SourceWeft

  1. Open Hatchet Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

hatchet-mcp

[CI] [npm version] [license: MIT]

An MCP server that lets AI agents observe and operate Hatchet workflows — status, runs, logs, workers, and metrics, plus trigger / cancel / replay.

Why: Hatchet has a great API but no MCP. This wraps it so agents (Claude Code / Desktop, etc.) can see and act on workflow state.

Install

Add this to your Claude Code / Claude Desktop MCP config:

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

Get the token from the Hatchet dashboard → API tokens. The token is a JWT that encodes the server URL and tenant, so it's the only required setting.

Configuration

VariableRequiredDescription
HATCHET_CLIENT_TOKENYesHatchet API token (JWT). Encodes the server URL + tenant, so it's normally all you need.
HATCHET_API_BASENoOverride the API base URL. Self-hosters can point this at any Hatchet instance.
HATCHET_TENANT_IDNoOverride the tenant id decoded from the token.

Self-hosting? Set HATCHET_API_BASE to your own Hatchet instance and it works anywhere.

Tools

Observability (read-only)

ToolDescription
whoamiShow the resolved Hatchet tenant + server URL and confirm the token works.
list_workflowsList workflow definitions for the tenant.
list_runsList workflow runs (with an optional lookback window and filters).
get_runGet the full detail of one workflow run — status, tasks, errors.
get_run_logsGet log lines for a task by its external id.
list_workersList workers and their status.
get_queue_metricsGet task/queue metrics for the tenant (queue health).

Actions (mutate live state)

ToolDescription
trigger_workflowTrigger a new workflow run by name with a JSON input payload.
cancel_runsCancel one or more runs/tasks by external id.
replay_runsReplay/retry one or more runs/tasks by external id.

Safety

The read tools (whoami, list_workflows, list_runs, get_run, get_run_logs, list_workers, get_queue_metrics) are non-destructive.

trigger_workflow, cancel_runs, and replay_runs mutate live state — their descriptions are prefixed MUTATES LIVE STATE so agents and users know they affect real runs.

The token grants full tenant access — treat it as a secret. Never commit it to source control.

Development

bash
pnpm installpnpm test    # vitestpnpm build   # tsup -> dist/index.js

TypeScript / ESM, tested with vitest.

Status

v0.1.0 — all tools verified against Hatchet Cloud; works with self-hosted instances via HATCHET_API_BASE. trigger_workflow uses the stable /workflow-runs/trigger endpoint.

Source: README.md at commit 18b34bf

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts