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.
MCP server for debugging and monitoring Hatchet jobs from Claude Code or other MCP clients.
git clone https://github.com/GJakobi/hatchet-mcp.git
cd hatchet-mcp
uv syncRelated MCP server: hatchet-mcp
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"
}
}
}
}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) |
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_metricsqueued - Waiting to be processed
running - Currently executing
completed - Finished successfully
failed - Finished with error
cancelled - Manually cancelled
MIT
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).
| Name | Required | Description | Default |
|---|---|---|---|
| workflow_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It successfully discloses the return structure (counts by status: queued, running, completed, failed) and the filtering behavior. However, it lacks safety/performance notes (e.g., whether this is cached, rate limits, or real-time vs. eventually consistent data).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Uses an efficient docstring format (Args/Returns) that front-loads the purpose and provides structured supplemental detail. Every sentence earns its place; the description is appropriately compact for a single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional parameter, no nested objects) and lack of output schema, the description adequately compensates by specifying the return format (counts by four status categories). It is complete enough for an agent to invoke successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage (only types and title provided). The description compensates well by stating the parameter is 'Optional workflow name to filter metrics,' adding both semantic meaning (filtering) and cardinality (optional) that the JSON schema structure alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Get queue depth and job counts by status' provides a clear verb and specific resource. However, it does not explicitly differentiate from sibling tools like list_runs or get_run_status, which also deal with job status but at a per-run rather than aggregate queue level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Args section explains the optional workflow_name filter provides filtering capability, implying this is used for aggregate monitoring. However, it lacks explicit guidance on when to choose this over list_runs (aggregate counts vs. individual job listings) or mention of prerequisites like workflow existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the important behavioral trait of returning current status instead of output when the run is incomplete, but omits safety characteristics (read-only nature), error handling, or rate limiting that agents need when annotations are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Uses standard docstring format with Args/Returns sections that front-load the purpose before implementation details. Three information-dense sentences with no filler, though the structured labels slightly reduce immediate scanability for LLMs compared to plain prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter retrieval tool with no output schema: it explains the dual return format (output vs status). However, given the existence of 'get_run_status', the description should clarify why both tools exist and their specific domains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (only 'title' present, no descriptions). The description compensates with 'The ID of the workflow run' in the Args section, which adds minimal semantic meaning beyond the parameter name itself, but does not specify format constraints, validity rules, or how to obtain the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves result/output of a completed workflow run using specific verb 'Get' and resource 'result/output'. However, it fails to explicitly distinguish from sibling tool 'get_run_status', which creates ambiguity about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes conditional behavior (returns output if completed, status if running), implying usage patterns, but provides no explicit guidance on when to prefer this over 'get_run_status' or other sibling tools. The overlap with 'get_run_status' remains unresolved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States it returns 'current status and details' implying a read operation, but doesn't specify possible status values (running/completed/failed), whether data is real-time or cached, or what 'details' includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with clear purpose sentence. 'Args' and 'Returns' sections are structured and functional given lack of schema/output descriptions. No redundant or wasted sentences, though docstring-style formatting is slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter read operation. Mentions return value (status/details) to compensate for missing output schema, and describes the parameter to compensate for 0% schema coverage. However, sibling tool confusion (result vs status) leaves a gap that should be addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage (only 'title': 'Run Id'). Description adds 'The ID of the workflow run' which provides basic context, but with only one parameter and no schema docs, it could elaborate on ID format or source (e.g., obtained from list_runs).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Get the current status of a specific workflow run'), but lacks differentiation from sibling 'get_run_result' (status vs. output data) and 'list_runs' (specific vs. list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus 'get_run_result' (which also takes a run_id) or when to prefer 'list_runs' followed by this call. No prerequisites mentioned (e.g., obtaining run_id from list_runs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workflow_name | No | ||
| status | No | ||
| since_hours | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully documents default values (24 hours, 50 limit) and return structure ('status, metadata, and timing info'), but omits critical behavioral details like result ordering (chronological?), pagination mechanics beyond the limit parameter, and whether archived/completed runs are included indefinitely or time-boxed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The docstring-style format with explicit 'Args' and 'Returns' sections is clear and pragmatic given the schema deficiencies. While the Args block is lengthy, every line is necessary to compensate for the undocumented schema. No tautology or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (which handles return value details) and the comprehensive Args documentation, the description is largely complete for a filtering tool. The only notable gaps are the lack of sibling differentiation and absence of result ordering guarantees or time-window behavior explanations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Excellent compensation for 0% schema description coverage. The Args section provides detailed semantics for all 4 parameters: workflow_name includes realistic examples ('qa-workflow'), status enumerates valid values not present in the schema enum, and since_hours/limit explain units and defaults. This adds substantial meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('workflow runs') with scope ('with optional filters'). However, it fails to distinguish from the sibling tool 'search_runs', leaving ambiguity about which to use for filtering vs searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like 'search_runs' or 'get_run_status'. The description does not specify prerequisites, expected query patterns, or when 'list_runs' is insufficient and 'search_runs' should be preferred instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all registered Hatchet workflows.
Returns a list of workflows with their IDs, names, and descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must carry the full burden of behavioral disclosure. It partially satisfies this by specifying return fields (IDs, names, descriptions), but omits critical safety characteristics (read-only nature, idempotency), pagination behavior, or performance implications of listing 'all' workflows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely efficient two-sentence structure: first sentence declares purpose, second declares return payload. Every word earns its place with no redundancy or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Appropriate for a zero-parameter list operation with existing output schema. Previewing the return fields (IDs, names, descriptions) provides helpful context without duplicating the full schema. Minor gap: lacks mention of pagination behavior or maximum result limits typical for unfiltered 'list all' endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema contains zero parameters, establishing a baseline score of 4 per evaluation rules. The description appropriately does not invent parameter documentation where none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses specific verb 'List' with clear resource 'registered Hatchet workflows'. Effectively distinguishes from siblings like 'list_runs' and 'search_runs' through explicit use of 'workflows' terminology, though could be strengthened by explicitly contrasting workflow definitions versus run executions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains no guidance on when to select this tool over alternatives. Does not clarify the distinction between retrieving workflow definitions (this tool) versus querying run executions (list_runs/search_runs siblings), leaving the agent to infer from naming alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata_key | Yes | ||
| metadata_value | Yes | ||
| status | No | ||
| since_hours | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions time-bounded search (since_hours) and that it returns full metadata, but does not explicitly confirm read-only nature, rate limits, or behavior when no matches exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with distinct sections for purpose, common keys, and arguments. Metadata key list is domain-specific and valuable. Slightly verbose but every section earns its place by aiding correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description adequately covers all inputs and provides crucial domain context (common keys). Sufficient for correct invocation though could clarify what constitutes a 'run' in this system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the Args section fully compensates by documenting all 5 parameters with clear semantics, optionality, and default values (e.g., since_hours defaults to 24).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb (Search) + resource (runs) + method (by metadata key-value pairs). Effectively distinguishes from sibling list_runs (unfiltered listing) and get_run_* tools (direct ID lookup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides valuable 'Common metadata keys' section (audit_id, patient_id, etc.) implying search capabilities, but does not explicitly contrast with list_runs or state when to prefer this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_queue_metricsget_run_resultget_run_statuslist_runslist_workflowssearch_runsScored 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.
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.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
