hatchet-ops-mcp

A small, read-only MCP server that exposes Hatchet client / REST observability APIs to coding agents — across multiple environments from one process.

Hatchet itself does not ship an official ops MCP. This project is a thin wrapper around the official Python hatchet-sdk: each tool call picks an env, resolves that environment's Hatchet JWT from envs.yaml, uses a cached Hatchet client, and returns the SDK response as structured MCP output.

The default transport is local stdio (no host / API key). For a shared process on a trusted network, streamable HTTP (and legacy SSE) are also available.

Why this exists

Hatchet's official agent integrations today are mainly docs MCP, CLI skills, and SDK helpers that turn your workflows/tasks into agent tools. None of those is a multi-tenant ops console for listing runs, workers, and queue metrics.

This server fills that gap by mapping read-only hatchet-sdk feature clients (workflows, runs, workers, metrics, logs, …) to MCP tools, with one extra capability: explicit env routing so one MCP process can talk to several Hatchet tenants/instances.

Related MCP server: poly-observability-mcp

Requirements

• Python 3.12 or newer

• uv

• A Hatchet API token (JWT) for each environment you want to query

• Docker and Docker Compose (optional, for HTTP deployment)

Setup

git clone <repository-url>
cd hatchet-ops-mcp
cp envs.example.yaml envs.yaml
uv sync

Edit envs.yaml. Each environment has its own Hatchet JWT (token). Entries left as TODO remain visible in list_envs, but cannot be queried until a token is provided.

envs:
  development:
    description: "Development"
    token: "eyJ..."   # Hatchet API JWT for this env
    server_url: "http://localhost:8080"
    tls_strategy: "none"

  production:
    description: "Production"
    token: "TODO"
    server_url: "https://hatchet.example.com"

server_url and tls_strategy are optional. When server_url is omitted, Hatchet resolves it from the JWT.

Note: envs.yaml token is the Hatchet credential. The MCP HTTP Bearer key is separate: set HATCHET_OPS_MCP_API_KEY (only needed for streamable-http / sse).

Local use (stdio)

This is the usual path for Cursor / Claude Code on your laptop — no bind address, no API key:

uv run hatchet-ops-mcp

Set HATCHET_OPS_MCP_ENVS when the config is outside the current checkout:

HATCHET_OPS_MCP_ENVS=/absolute/path/to/envs.yaml uv run hatchet-ops-mcp

MCP client configuration:

{
  "mcpServers": {
    "hatchet-ops": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/hatchet-ops-mcp",
        "run",
        "hatchet-ops-mcp"
      ],
      "env": {
        "HATCHET_OPS_MCP_ENVS": "/absolute/path/to/hatchet-ops-mcp/envs.yaml"
      }
    }
  }
}

Shared HTTP (trusted network)

For one process that several clients hit on a LAN / VPN. Auth is a single shared Bearer API key checked by middleware — not OAuth.

HTTP refuses to start without an API key unless you pass --allow-insecure (trusted network only). Default bind is 127.0.0.1; only override --host when something other than this machine must connect (Docker Compose already sets 0.0.0.0).

export HATCHET_OPS_MCP_API_KEY='replace-with-a-strong-random-value'

uv run hatchet-ops-mcp --transport streamable-http
# optional: --port 8765
# Docker / LAN only: --host 0.0.0.0

Endpoints: /mcp (MCP), /health (no auth).

Docker Compose mounts local envs.yaml and binds 0.0.0.0 for you:

export HATCHET_OPS_MCP_API_KEY='replace-with-a-strong-random-value'
docker compose up --build

Remote MCP client example:

{
  "mcpServers": {
    "hatchet-ops": {
      "url": "http://hatchet-ops.internal:8765/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-the-shared-api-key"
      }
    }
  }
}

Tools

All tools except list_envs require env.

Debug playbook

Typical failed / stuck run investigation:

1. list_runs with statuses, workflow_name (exact name), and/or additional_metadata

2. get_run for status and per-task summaries (include_payloads=true for I/O)

3. get_run_events for QUEUED / STARTED / FAILED / CANCELLED timeline

4. get_run_logs with workflow_run_id for merged application logs (newest lines kept)

5. If stuck QUEUED: list_workers / get_worker

6. For environment health: get_queue_metrics, get_task_metrics, get_task_stats

list_runs / get_run omit payloads by default. include_payloads=true on list_runs also disables minimal_output.

Security

• envs.yaml is ignored by Git. Never commit real Hatchet tokens.

• Prefer stdio on developer machines; treat shared HTTP as an internal service.

• HTTP refuses to start without a Bearer API key unless --allow-insecure is set.

• Prefer read-only Hatchet tokens when the deployment supports scoped tokens.

• Tool results may contain workflow inputs, outputs, errors, or logs. Treat MCP output according to the sensitivity of the underlying environment.

• The server intentionally exposes no mutating Hatchet operations.

Development

uv sync
uv run pytest
uv build

License

MIT