set_task_run_state

Update the execution status of a Prefect workflow task run by setting it to states like SCHEDULED, RUNNING, COMPLETED, or FAILED to manage task lifecycle and track progress.

Instructions

Set a task run's state.

Args: task_run_id: The task run UUID state: The new state to set (e.g., "SCHEDULED", "RUNNING", "COMPLETED", "FAILED") message: An optional message explaining the state change

Returns: Result of the state change operation

Input Schema

TableJSON Schema

Name	Required	Description	Default
`message`	No
`state`	Yes
`task_run_id`	Yes

Implementation Reference

src/mcp_prefect/task_run.py:208-253 (handler)

The main handler function for the 'set_task_run_state' tool, decorated with @mcp.tool for registration. It maps string state names to Prefect state objects and calls the Prefect client's set_task_run_state method to update the task run state.

@mcp.tool
async def set_task_run_state(
    task_run_id: str,
    state: str,
    message: Optional[str] = None,
    force: bool = False,
) -> List[Union[types.TextContent, types.ImageContent, types.EmbeddedResource]]:
    """
    Set a task run's state.
    
    Args:
        task_run_id: The task run UUID
        state: The new state to set (e.g., "SCHEDULED", "RUNNING", "COMPLETED", "FAILED")
        message: An optional message explaining the state change
        force: If True, disregard orchestration logic when setting the state
        
    Returns:
        Result of the state change operation
    """
    async with get_client() as client:
        state_obj = None
        if state.upper() == "SCHEDULED":
            state_obj = Scheduled(message=message)
        elif state.upper() == "RUNNING":
            state_obj = Running(message=message)
        elif state.upper() == "COMPLETED":
            state_obj = Completed(message=message)
        elif state.upper() == "FAILED":
            state_obj = Failed(message=message)
        elif state.upper() == "PENDING":
            state_obj = Pending(message=message)
        elif state.upper() == "CANCELLED":
            state_obj = Cancelled(message=message)
        else:
            return [types.TextContent(
                type="text", 
                text=f"Invalid state '{state}'. Must be one of: SCHEDULED, RUNNING, COMPLETED, FAILED, PENDING, CANCELLED"
            )]
        
        result = await client.set_task_run_state(
            task_run_id=UUID(task_run_id),
            state=state_obj,
            force=force
        )
        
        return [types.TextContent(type="text", text=str(result.model_dump()))]

src/mcp_prefect/task_run.py:208-208 (registration)
The @mcp.tool decorator registers the set_task_run_state function as an MCP tool.
```
@mcp.tool
```

Prefect MCP Server