Running workflows from MCP

Expose your Flux workflows as MCP tools so AI agents and other MCP clients can discover and invoke them.

This page covers the publisher perspective: how to expose your workflows as MCP tools so other clients (like AI agents) can invoke them. For the consumer perspective (Flux agents calling MCP tools), see Agents → Integrations → MCP integration.

Flux ships a built-in MCP server that bridges a running Flux server to the Model Context Protocol. It registers a fixed tool set — list workflows, execute them, check status, cancel executions, manage schedules — and exposes them to any MCP-compatible client (Claude Desktop, a Flux agent, or any MCP client library).

Prerequisites

You need a Flux server and at least one worker running before starting the MCP server. The MCP server does not execute workflows; it proxies requests to the Flux HTTP API.

# Terminal 1: start the server
flux start server

# Terminal 2: start a worker
export FLUX_WORKERS__BOOTSTRAP_TOKEN=$(flux server bootstrap-token)
flux start worker

Start the MCP server

flux start mcp

By default it binds to localhost:8080 using the streamable-http transport and proxies to the Flux server at http://localhost:8000. Override any of those with CLI flags:

flux start mcp \
  --host 0.0.0.0 \
  --port 9000 \
  --transport streamable-http \
  --server-url http://my-flux-server:8000 \
  --name my-flux-mcp

Available options

Usage: flux start mcp [OPTIONS]

  Start the Flux MCP server that exposes API endpoints as tools.

Options:
  -h, --host TEXT                 Host to bind the MCP server to.
  -p, --port INTEGER              Port to bind the MCP server to.
  -n, --name TEXT                 Name for the MCP server.
  -surl, --server-url TEXT        Server URL to connect to.
  -t, --transport [stdio|streamable-http|sse]
                                  Transport protocol for MCP (stdio,
                                  streamable-http, sse)
  --help                          Show this message and exit.

Persistent configuration

To avoid passing flags on every start, set the defaults in flux.toml:

[flux.mcp]
name       = "flux-workflows"
host       = "localhost"
port       = 8080
server_url = "http://localhost:8000"
transport  = "streamable-http"

The same keys are available as environment variables: FLUX_MCP__HOST, FLUX_MCP__PORT, FLUX_MCP__SERVER_URL, FLUX_MCP__TRANSPORT, FLUX_MCP__NAME.

Transport modes

The --transport flag controls the wire protocol:

Transport	When to use
`streamable-http` (default)	Recommended for server-to-server integrations and newer MCP clients that support chunked responses.
`sse`	Persistent HTTP connection; works with Claude Desktop and most MCP clients out of the box.
`stdio`	Used when the MCP server is launched as a subprocess by the client (e.g. Claude Desktop’s local server model). The client manages the process lifecycle.

Connecting a client

Claude Desktop

Add a block to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "flux": {
      "command": "flux",
      "args": ["start", "mcp", "--transport", "stdio"]
    }
  }
}

With stdio transport, Claude Desktop launches and manages the flux start mcp process. It appears in the MCP tools panel the next time Claude Desktop restarts.

For a persistent server using SSE instead:

{
  "mcpServers": {
    "flux": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Flux agent

A Flux agent configured with the MCP integration can call Flux workflows as tools directly. See Agents → Integrations → MCP integration for the agent-side configuration.

Exposed tools

The MCP server registers the following tools automatically. Any workflow registered with the Flux server is immediately reachable through them, with no additional configuration.

Workflow management

Tool	Description
`list_workflows`	List all registered workflows.
`get_workflow_details`	Get metadata for a specific workflow by name and namespace.
`list_namespaces`	List namespaces and their workflow counts.
`upload_workflow`	Upload a Python source file to register a new workflow.
`list_workflow_versions`	List all registered versions of a workflow.
`get_workflow_version`	Retrieve details of a specific version.
`delete_workflow`	Delete a workflow (optionally by version).

Execution

Tool	Description
`execute_workflow_async`	Start an execution and return immediately with an execution ID.
`execute_workflow_sync`	Start an execution and block until it reaches a terminal state.
`resume_workflow_async`	Resume a paused execution asynchronously.
`resume_workflow_sync`	Resume a paused execution and wait for completion.

Both execute_workflow_async and execute_workflow_sync accept workflow_name (the short name without namespace), input_data (a JSON string encoding the workflow’s input), workflow_namespace (defaults to "default"), and detailed (set to true to include the per-task event log in the response).

Monitoring

Tool	Description
`get_execution_status`	Retrieve the current state and output of an execution.
`get_execution`	Retrieve full execution details by execution ID.
`list_executions`	List executions with optional filtering by state.
`list_workflow_executions`	List executions for a specific workflow.
`cancel_execution`	Cancel a running execution (sync or async mode).

Schedule management

Tool	Description
`list_schedules`	List schedules, with optional filtering by workflow.
`get_schedule`	Get details of a schedule by ID or name.
`create_schedule`	Create a new cron or interval schedule for a workflow.
`update_schedule`	Update a schedule’s config, description, or input data.
`pause_schedule`	Pause a schedule without deleting it.
`resume_schedule`	Resume a paused schedule.
`delete_schedule`	Delete a schedule.
`get_schedule_history`	Retrieve execution history for a schedule.

Infrastructure

Tool	Description
`list_workers`	List all connected workers.
`get_worker`	Get details of a specific worker by name.
`health_check`	Check whether the Flux server is reachable and healthy.

Authentication

The MCP server does not enforce authentication; it inherits whatever auth is configured on the Flux server it proxies to. If your Flux server has API key or OIDC auth enabled, the MCP server needs valid credentials in its --server-url connection. Pass credentials via the server URL (e.g. http://user:token@host:8000) or configure the Flux server to allow unauthenticated requests from trusted internal addresses.

What’s next

Running workflows from the SDK — trigger executions programmatically from Python.
Running workflows from the CLI — run and monitor executions from the terminal.
Running workflows from the REST API — call the HTTP API directly from any language.
Agents → Integrations → MCP integration — consumer perspective: Flux agents calling external MCP tools.
Workflow control → Scheduling — set up cron and interval schedules so workflows run on a timer.