About Hatchet MCP
Hatchet MCP lets AI agents inspect and operate Hatchet workflows, for teams that need workflow visibility and control. It combines read-only status tools with actions that trigger, cancel, or replay live runs.
Key features
- 01Inspect workflow definitions and runs
- 02Read run details and task logs
- 03View worker status and queue metrics
- 04Trigger, cancel, or replay runs
Use cases
- 01Investigate workflow run errors
- 02Check worker and queue health
- 03Trigger or retry workflows from an agent
MCP support
This MCP server exposes Hatchet workflows, runs, logs, workers, and metrics as tools, along with actions to trigger, cancel, and replay runs.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y hatchet-mcpHATCHET_CLIENT_TOKENSecretHatchet API token (a JWT). Encodes the server URL and tenant, so it is normally the only setting required.HATCHET_API_BASEOverride the API base URL. Self-hosters can point this at any Hatchet instance.HATCHET_TENANT_IDOverride the tenant id decoded from the token.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEhatchet-mcp
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:
{
"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
| Variable | Required | Description |
|---|---|---|
HATCHET_CLIENT_TOKEN | Yes | Hatchet API token (JWT). Encodes the server URL + tenant, so it's normally all you need. |
HATCHET_API_BASE | No | Override the API base URL. Self-hosters can point this at any Hatchet instance. |
HATCHET_TENANT_ID | No | Override 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)
| Tool | Description |
|---|---|
whoami | Show the resolved Hatchet tenant + server URL and confirm the token works. |
list_workflows | List workflow definitions for the tenant. |
list_runs | List workflow runs (with an optional lookback window and filters). |
get_run | Get the full detail of one workflow run — status, tasks, errors. |
get_run_logs | Get log lines for a task by its external id. |
list_workers | List workers and their status. |
get_queue_metrics | Get task/queue metrics for the tenant (queue health). |
Actions (mutate live state)
| Tool | Description |
|---|---|
trigger_workflow | Trigger a new workflow run by name with a JSON input payload. |
cancel_runs | Cancel one or more runs/tasks by external id. |
replay_runs | Replay/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
pnpm install
pnpm test # vitest
pnpm 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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.