Hatchet MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Hatchet MCP Server show me any workflow runs that failed in the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hatchet MCP Server
MCP server for debugging and monitoring Hatchet jobs from Claude Code or other MCP clients.
Installation
git clone https://github.com/GJakobi/hatchet-mcp.git
cd hatchet-mcp
uv syncRelated MCP server: hatchet-mcp
Configuration
Add to your .mcp.json (Claude Code) or MCP client config:
{
"mcpServers": {
"hatchet": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/hatchet-mcp", "python", "-m", "hatchet_mcp.server"],
"env": {
"HATCHET_CLIENT_TOKEN": "your-hatchet-token"
}
}
}
}Available Tools
Tool | Description |
| List all registered Hatchet workflows |
| List workflow runs with filters (workflow_name, status, since_hours, limit) |
| Get status of a specific run by ID |
| Get the output/result of a completed run |
| Get job counts by status (queued, running, completed, failed) |
| Search runs by metadata (e.g., audit_id, patient_id) |
Example Usage
Once configured in Claude Code:
> List all Hatchet workflows
Uses: mcp__hatchet__list_workflows
> Show me runs that failed in the last 24 hours
Uses: mcp__hatchet__list_runs with status="failed"
> Find all runs for audit_id abc123
Uses: mcp__hatchet__search_runs with metadata_key="audit_id", metadata_value="abc123"
> What's the current queue depth?
Uses: mcp__hatchet__get_queue_metricsStatus Values
queued- Waiting to be processedrunning- Currently executingcompleted- Finished successfullyfailed- Finished with errorcancelled- Manually cancelled
License
MIT
Available Tools
6 toolsget_queue_metricsA
Get queue depth and job counts by status.
Args: workflow_name: Optional workflow name to filter metrics
Returns counts of jobs in each status (queued, running, completed, failed).
Inputs: workflow_name.
get_run_resultB
Get the result/output of a completed workflow run.
Args: run_id: The ID of the workflow run
Returns the run's output data if completed, or current status if still running.
Inputs: run_id (required).
get_run_statusB
Get the current status of a specific workflow run.
Args: run_id: The ID of the workflow run
Returns the run's current status and details.
Inputs: run_id (required).
list_runsA
List workflow runs with optional filters.
Args: workflow_name: Filter by workflow name (e.g., 'qa-workflow', 'embed-workflow') status: Filter by status ('queued', 'running', 'completed', 'failed', 'cancelled') since_hours: How many hours back to search (default: 24) limit: Maximum number of runs to return (default: 50)
Returns a list of runs with their status, metadata, and timing info.
Inputs: workflow_name, status, since_hours, limit. Returns: result
list_workflowsA
List all registered Hatchet workflows.
Returns a list of workflows with their IDs, names, and descriptions.
Inputs: no named parameters. Returns: result
search_runsA
Search runs by metadata key-value pairs.
Common metadata keys:
audit_id: The audit being processed
audit_type: Type of audit (e.g., 'standard', 'express')
patient_id: Patient being processed
application_id: Application ID
rule_id: Rule being processed
Args: metadata_key: The metadata key to search (e.g., 'audit_id') metadata_value: The value to match status: Optional status filter since_hours: How many hours back to search (default: 24) limit: Maximum runs to return (default: 50)
Returns matching runs with their full metadata.
Inputs: metadata_key (required), metadata_value (required), status, since_hours, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have distinct purposes focused on different aspects of workflow management (metrics, runs, workflows), but get_run_result and get_run_status could potentially overlap in some use cases since both retrieve information about specific runs. The descriptions help clarify that get_run_result focuses on output data while get_run_status focuses on current status, but an agent might still need to carefully choose between them.
All tools follow a consistent verb_noun pattern with clear, descriptive names. The naming convention is uniform throughout: get_queue_metrics, get_run_result, get_run_status, list_runs, list_workflows, and search_runs. This consistency makes it easy for agents to understand and predict tool functionality.
Six tools is an appropriate number for a workflow management server. This provides comprehensive coverage without being overwhelming. The tools cover metrics retrieval, run status checking, run listing/searching, and workflow listing - a well-scoped set that addresses the core needs of interacting with a workflow system.
The tool set provides strong read/search capabilities for workflows and runs, with good coverage for querying metrics, status, results, and metadata. Minor gaps exist in write operations (no tools for creating/triggering workflows or managing runs), but for a monitoring/query-focused server, the surface is reasonably complete for its apparent purpose.
Maintenance
Related MCP Connectors
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Related MCP Servers
- FlicenseBqualityFmaintenanceEnables comprehensive Datadog monitoring capabilities including CI/CD pipeline management, service logs analysis, metrics querying, monitor and SLO management, service definitions retrieval, and team management through Claude and other MCP clients.1320-
- AlicenseNot gradedqualityCmaintenanceAn MCP server for Hatchet, the durable orchestration engine, enabling LLMs to inspect workflow definitions, runs, logs, and more, with optional mutating tools for triggering, canceling, and managing workflows.73 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceLet AI agents observe and operate your Hatchet workflows: runs, logs, workers, metrics, plus trigger/cancel/replay.45 npm1MIT
- AlicenseNot gradedqualityDmaintenanceProvides Claude AI assistants with focused monitoring tools for n8n workflow execution analysis, including active workflow listing, execution history with KPIs, and detailed failure information.1MIT