Add to Cursor Add to Claude Copy for LLM View as MD

Hatchet and MCP: Exposing Tasks and Workflows as Agent Tools

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools, data sources, and services. This guide shows how to expose Hatchet workflows and standalone tasks as tools that frameworks like the Claude Agent SDK and OpenAI Agents SDK can invoke. Later cookbooks in this series will show how to integrate those tools into a full agent loop.

In this guide, we define a Hatchet workflow and a standalone task, each with a description and a typed input schema, then convert each into an agent tool. When an agent invokes one of those tools, the tool handler submits a run to the Hatchet engine. A worker picks up and executes the workflow or task and reports the result to Hatchet. The tool handler returns that result to the agent.

What this guide builds

This guide builds a temperature lookup tool backed by Hatchet. The workflow and standalone task call the Open-Meteo API and return the current temperature for a given location. The same operation is implemented as both a workflow and a standalone task, so you can see how each becomes an agent tool.

The agent process contains the tool handler that submits the run, but it does not execute the workflow or task. Instead, a Hatchet worker executes the registered workflow or task and reports the result through Hatchet to the waiting tool handler. Since each tool call submits a run through Hatchet, the work the agent triggers gets the same observability and core reliability guarantees as any other Hatchet task or workflow.

Setup

Prepare your environment

To run this example, you need:

a working local Hatchet environment or access to Hatchet Cloud
a Hatchet SDK example environment (see the Quickstart)

Install the optional dependencies for the language and agent framework you plan to use:

Install the Hatchet SDK extra for your provider:

pip install "hatchet-sdk[claude]"

or:

pip install "hatchet-sdk[openai]"

Define the models

Start by defining the input and output types. The agent uses the input schema to understand what arguments the tool accepts.

examples/python/agent/workflows.py

class TemperatureCoords(BaseModel):
    latitude: float
    longitude: float


class TemperatureInput(BaseModel):
    location_name: str
    coords: TemperatureCoords


class TemperatureContent(BaseModel):
    text: str

In Python, Pydantic models or dataclasses define the schema. In TypeScript, Zod v4 schemas serve the same purpose and also generate the JSON Schema that agent frameworks require.

Define a workflow

Agent tools need a description and an input validator. The description tells the agent when to use the tool. The input validator provides the schema for the tool arguments. Define the workflow with both so it can be exposed as an agent tool.

examples/python/agent/workflows.py

get_temperature_workflow = hatchet.workflow(
    name="get_temperature",
    input_validator=TemperatureInput,
    description="Get the current temperature at a location",
)


@get_temperature_workflow.task()
async def get_temperature(input: TemperatureInput, ctx: Context) -> TemperatureContent:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": input.coords.latitude,
                "longitude": input.coords.longitude,
                "current": "temperature_2m",
                "temperature_unit": "fahrenheit",
            },
        )
        data = response.json()

    return TemperatureContent(
        text=f"Temperature in {input.location_name}: {data['current']['temperature_2m']}°F"
    )

Or expose a standalone task

You can expose a standalone task the same way. This is useful when the agent tool maps to a single operation rather than a multi-step workflow.

examples/python/agent/workflows.py

@hatchet.task(
    input_validator=TemperatureInput,
    description="Get the current temperature at a location",
)
async def get_temperature_standalone(
    input: TemperatureInput, ctx: Context
) -> TemperatureContent:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": input.coords.latitude,
                "longitude": input.coords.longitude,
                "current": "temperature_2m",
                "temperature_unit": "fahrenheit",
            },
        )
        data = response.json()

    return TemperatureContent(
        text=f"Temperature in {input.location_name}: {data['current']['temperature_2m']}°F"
    )

Create agent tools

Create the tool in the process that runs your agent. The examples use helper functions around Hatchet’s MCP tool conversion call so the workflow and task definitions can be imported without loading every optional provider SDK. Each helper returns a provider-specific tool definition that the agent SDK can use. The description and input validator you added above become part of that tool definition, which is why they are required.

examples/python/agent/workflows.py

def create_temperature_workflow_tool_claude() -> Any:
    return get_temperature_workflow.mcp_tool(MCPProvider.CLAUDE)


def create_temperature_workflow_tool_openai() -> Any:
    return get_temperature_workflow.mcp_tool(MCPProvider.OPENAI)


def create_temperature_task_tool_claude() -> Any:
    return get_temperature_standalone.mcp_tool(MCPProvider.CLAUDE)


def create_temperature_task_tool_openai() -> Any:
    return get_temperature_standalone.mcp_tool(MCPProvider.OPENAI)

The worker does not discover agent tools. It registers Hatchet workflows and tasks normally. When the tool handler submits a run, Hatchet dispatches it to a worker that registered the corresponding workflow or task.

Register and start the worker

The worker must be running for tools to function. When the agent calls a tool, the tool handler submits a run to the Hatchet engine, and the engine dispatches it to a worker for execution.

examples/python/agent/worker.py

from examples.agent.workflows import (
    hatchet,
    get_temperature_workflow,
    get_temperature_standalone,
)


def main() -> None:
    worker = hatchet.worker(
        "test-worker", workflows=[get_temperature_workflow, get_temperature_standalone]
    )
    worker.start()


if __name__ == "__main__":
    main()

Test it

You can confirm that the workflow definitions and helper functions import successfully without requiring provider SDKs:

cd sdks/python
poetry run python -c "from examples.agent.workflows import create_temperature_workflow_tool_claude, create_temperature_task_tool_claude; print('OK')"

To test the full round trip between the agent and the Hatchet-backed tool, start the worker in one terminal and run a provider-specific agent example in another. This requires the provider SDK and API key for the agent example you run (ANTHROPIC_API_KEY or OPENAI_API_KEY).

Start the worker:

cd sdks/python
poetry run python -m examples.agent.worker

In a second terminal, run the Claude or OpenAI agent example:

cd sdks/python
poetry run python -m examples.agent.agent_claude
# or
poetry run python -m examples.agent.agent_openai

If successful, the agent will invoke the tool and print the temperature result to the terminal.

Because each agent tool call submits a run through Hatchet, you can apply the same controls you use for other tasks and workflows:

Durable execution: Hatchet tracks execution state durably so work can survive worker restarts and failures.
Configurable retries: Failed tasks can retry according to your workflow or task configuration.
Rate limits and concurrency control: Protect downstream systems from agent-driven bursts.
Observability: Inspect tool-triggered runs in the Hatchet dashboard with status, timing, logs, and OpenTelemetry traces.

Security considerations

MCP is a protocol for exposing tools to agents. It is not a security boundary. Tools can represent arbitrary code execution and should be treated with appropriate caution. Do not rely on the agent prompt alone to enforce security rules.

For production deployments:

Validate tool inputs at the workflow level before executing business logic.
Apply rate limits and concurrency controls to prevent runaway tool invocations.
Use additional metadata to track which agent session triggered each run.
Run workers with restricted permissions.
Use network policies to limit what workers can reach.
Use external sandbox providers when tools may execute untrusted code.

Hatchet does not provide native code sandboxing. If you need isolation between the agent and the execution environment, that is an infrastructure decision.

PDF Pipeline

We use cookies

Hatchet and MCP: Exposing Tasks and Workflows as Agent Tools

What this guide builds

Setup

Prepare your environment

Define the models

Define a workflow

Or expose a standalone task

Create agent tools

Register and start the worker

Test it

Related Hatchet features

Security considerations