MCP tool reference

Tools are registered in flux/mcp_server.py inside MCPServer._setup_tools. Each is a single async function decorated with @self.mcp.tool() and forwards to a Flux REST endpoint via the shared httpx.AsyncClient. Tool arguments are JSON; return values are JSON dicts. Most tools return {"success": true, ...} on the happy path and {"success": false, "error": "..."} on failure. A few — execute_workflow_sync, execute_workflow_async, resume_workflow_*, get_execution_status, get_execution — return either the full ExecutionContext dict or its summary() shape depending on the detailed argument.

For the overall process model and how to start the MCP server, see MCP server overview. Per-workflow MCP tools (with bespoke names and schemas) are produced by flux service create --mcp, not by this server.

Conventions used below

• Required permission assumes the standard Flux RBAC permission strings (workflow:<namespace>:<name>:run, schedule:*:manage, etc.). With [flux.security.auth] enabled = false (the default local-dev config), no permission is checked. Permission strings come from flux/security/dependencies.py::require_permission.
• REST equivalent links to the REST API reference, where each endpoint’s full schema lives.
• All execution tools accept a detailed: bool = False flag. detailed=False returns the ExecutionContext.summary() dict (workflow ids, execution_id, input, output, state, current_worker). detailed=True returns the full ExecutionContext including the events list.

Workflow management

list_workflows

List every workflow registered on the Flux server.

• Parameters: none
• Returns: {"success": true, "workflows": [...], "count": <int>}
• REST equivalent: GET /workflows — see REST API: workflows
• Required permission: per-row filtering — the route returns only the workflows the caller holds workflow:<namespace>:<name>:read on, rather than gating the whole list behind a single permission.

list_namespaces

List all workflow namespaces with their workflow counts.

• Parameters: none
• Returns: {"success": true, "namespaces": [...], "count": <int>}
• REST equivalent: GET /namespaces
• Required permission: workflow:*:*:read

get_workflow_details

Fetch one workflow’s metadata, including its input schema (if the workflow declares a Pydantic input type).

• Parameters:
  • workflow_name: str — short name, no namespace prefix
  • workflow_namespace: str = "default"
• Returns: {"success": true, "workflow": {...}}
• REST equivalent: GET /workflows/{namespace}/{name}
• Required permission: workflow:<namespace>:<name>:read

list_workflow_versions

List every registered version of a workflow.

• Parameters: workflow_name: str, workflow_namespace: str = "default"
• Returns: {"success": true, "versions": [...], "count": <int>}
• REST equivalent: GET /workflows/{namespace}/{name}/versions
• Required permission: workflow:<namespace>:<name>:read

get_workflow_version

Get details of a specific workflow version.

• Parameters:
  • workflow_name: str
  • version: int — the numeric version
  • workflow_namespace: str = "default"
• Returns: {"success": true, "workflow": {...}}
• REST equivalent: GET /workflows/{namespace}/{name}/versions/{version}
• Required permission: workflow:<namespace>:<name>:read

upload_workflow

Upload and register a new workflow file by sending its source as a multipart form field. The server parses the file and registers every @workflow it finds.

• Parameters: file_content: str — UTF-8 Python source
• Returns: {"success": true, "workflows": [<name>, ...], "result": [...]}
• REST equivalent: POST /workflows (multipart)
• Required permission: workflow:<namespace>:*:register (checked per parsed workflow)

delete_workflow

Delete a workflow. If version is omitted, every version is removed.

• Parameters:
  • workflow_name: str
  • version: int | None = None
  • workflow_namespace: str = "default"
• Returns: {"success": true, "message": "..."}
• REST equivalent: DELETE /workflows/{namespace}/{name} (optional ?version=)
• Required permission: workflow:<namespace>:*:register

Workflow execution

execute_workflow_async

Start an execution and return immediately. The MCP client then polls via get_execution_status.

• Parameters:
  • workflow_name: str
  • input_data: str — JSON-encoded string. If parsing fails the raw string is forwarded.
  • detailed: bool = False
  • workflow_namespace: str = "default"
• Returns: ExecutionContext.summary() dict, or the full context if detailed=True
• REST equivalent: POST /workflows/{namespace}/{name}/run/async
• Required permission: workflow:<namespace>:<name>:run

execute_workflow_sync

Start an execution and wait for it to reach a terminal state. The MCP server uses a 300-second HTTP timeout for this call.

• Parameters: same as execute_workflow_async
• Returns: ExecutionContext.summary() dict, or the full context if detailed=True
• REST equivalent: POST /workflows/{namespace}/{name}/run/sync
• Required permission: workflow:<namespace>:<name>:run

resume_workflow_async

Resume a paused execution by id without waiting.

• Parameters:
  • workflow_name: str
  • execution_id: str
  • input_data: str — JSON-encoded resume input
  • detailed: bool = False
  • workflow_namespace: str = "default"
• Returns: ExecutionContext.summary() dict, or full context if detailed=True
• REST equivalent: POST /workflows/{namespace}/{name}/resume/{execution_id}/async
• Required permission: workflow:<namespace>:<name>:run

resume_workflow_sync

Resume a paused execution and wait for it to reach a terminal state. 300-second HTTP timeout.

• Parameters: same as resume_workflow_async
• Returns: ExecutionContext.summary() dict, or full context if detailed=True
• REST equivalent: POST /workflows/{namespace}/{name}/resume/{execution_id}/sync
• Required permission: workflow:<namespace>:<name>:run

cancel_execution

Cancel an in-flight execution.

• Parameters:
  • workflow_name: str
  • execution_id: str
  • mode: str = "async" — "sync" (wait for cancellation to complete) or "async" (return immediately). Other values return an error.
  • detailed: bool = False
  • workflow_namespace: str = "default"
• Returns: {"success": true, "execution_id": ..., "workflow_name": ..., "cancellation_mode": ..., "status": <server response>}
• REST equivalent: GET /workflows/{namespace}/{name}/cancel/{execution_id} (with ?mode=)
• Required permission: workflow:<namespace>:<name>:run

Execution monitoring

get_execution_status

Fetch status of an execution by id, scoped under a workflow name.

• Parameters:
  • workflow_name: str
  • execution_id: str
  • detailed: bool = False — when true, includes the event log
  • workflow_namespace: str = "default"
• Returns: ExecutionContext.summary() dict, or full context if detailed=True
• REST equivalent: GET /workflows/{namespace}/{name}/status/{execution_id}
• Required permission: workflow:<namespace>:<name>:read

list_executions

List executions across the server, with optional filters.

• Parameters:
  • workflow_name: str | None = None
  • state: str | None = None — e.g. "running", "completed", "failed"
  • limit: int = 50
  • offset: int = 0
• Returns: {"success": true, "executions": [...], "total": <int>, "limit": <int>, "offset": <int>}
• REST equivalent: GET /executions
• Required permission: execution:*:read

get_execution

Get one execution by id alone (no workflow name required).

• Parameters:
  • execution_id: str
  • detailed: bool = False
• Returns: ExecutionContext.summary() dict, or full context if detailed=True
• REST equivalent: GET /executions/{execution_id}
• Required permission: execution:<id>:read

list_workflow_executions

List executions scoped to a single workflow.

• Parameters:
  • workflow_name: str
  • state: str | None = None
  • limit: int = 50
  • offset: int = 0
  • workflow_namespace: str = "default"
• Returns: {"success": true, "workflow_name": ..., "executions": [...], "total": <int>, "limit": <int>, "offset": <int>}
• REST equivalent: GET /workflows/{namespace}/{name}/executions
• Required permission: workflow:<namespace>:<name>:read

Workers

list_workers

List every worker known to the server.

• Parameters: none
• Returns: {"success": true, "workers": [...], "count": <int>}
• REST equivalent: GET /workers
• Required permission: none beyond an authenticated identity — worker discovery is intentionally unpermissioned.

get_worker

Get one worker by name.

• Parameters: worker_name: str
• Returns: {"success": true, "worker": {...}}
• REST equivalent: GET /workers/{worker_name}
• Required permission: none beyond an authenticated identity — worker discovery is intentionally unpermissioned.

Schedules

create_schedule

Create a schedule for a workflow.

• Parameters:
  • workflow_name: str
  • name: str — schedule name (must be unique)
  • schedule_config: str — JSON-encoded config (cron, interval, once). Must parse as JSON or the tool returns an error.
  • description: str | None = None
  • input_data: str | None = None — JSON-encoded; if it fails to parse, the raw string is forwarded.
• Returns: {"success": true, "schedule": {...}}
• REST equivalent: POST /schedules
• Required permission: schedule:*:manage

list_schedules

List schedules with optional filtering.

• Parameters:
  • workflow_name: str | None = None
  • active_only: bool = True
  • limit: int | None = None
  • offset: int | None = None
• Returns: {"success": true, "schedules": [...], "count": <int>}
• REST equivalent: GET /schedules
• Required permission: schedule:*:read

get_schedule

Get one schedule by id or name.

• Parameters: schedule_id: str
• Returns: {"success": true, "schedule": {...}}
• REST equivalent: GET /schedules/{schedule_id}
• Required permission: schedule:<id>:read

update_schedule

Update an existing schedule. At least one of schedule_config, description, input_data must be supplied or the tool returns an error.

• Parameters:
  • schedule_id: str
  • schedule_config: str | None = None — JSON-encoded
  • description: str | None = None
  • input_data: str | None = None
• Returns: {"success": true, "schedule": {...}}
• REST equivalent: PUT /schedules/{schedule_id}
• Required permission: schedule:*:manage

pause_schedule

Pause an active schedule.

• Parameters: schedule_id: str
• Returns: {"success": true, "schedule": {...}}
• REST equivalent: POST /schedules/{schedule_id}/pause
• Required permission: schedule:*:manage

resume_schedule

Resume a paused schedule.

• Parameters: schedule_id: str
• Returns: {"success": true, "schedule": {...}}
• REST equivalent: POST /schedules/{schedule_id}/resume
• Required permission: schedule:*:manage

delete_schedule

Delete a schedule.

• Parameters: schedule_id: str
• Returns: {"success": true, "message": "..."}
• REST equivalent: DELETE /schedules/{schedule_id}
• Required permission: schedule:*:manage

get_schedule_history

Fetch execution history for a schedule.

• Parameters:
  • schedule_id: str
  • limit: int = 50
  • offset: int = 0
• Returns: {"success": true, "schedule_id": ..., "workflow_name": ..., "entries": [...], "total": <int>, "limit": <int>, "offset": <int>}
• REST equivalent: GET /schedules/{schedule_id}/history
• Required permission: schedule:*:read

Health

health_check

Check the Flux server’s /health endpoint.

• Parameters: none
• Returns: {"success": true, "health": {...}}
• REST equivalent: GET /health
• Required permission: none (the underlying endpoint is unauthenticated)

Custom tools