Workflow exposes a local MCP server that lets an AI client inspect, create, validate, run, and debug Workflow flows. The server is available only on the computer running the Workflow application.

This guide covers Codex (desktop app, CLI, and IDE extension) and Claude Code. The verified client versions are listed in Client-interoperability.md.

Before connecting

1. Start the Workflow UI application and leave it running.

2. Confirm that the local REST API responds:

   curl -sS http://127.0.0.1:5440/info
   

3. Use a Workflow license with modifyConfiguration permission when the client must create or change flows. Read-only discovery still works without that permission.

4. Configure Workflow's Cloud connection and proxy normally. MCP clients do not provide an MIS key or Cloud authentication headers; Workflow's proxy injects them.

The MCP endpoint is: http://127.0.0.1:5440/mcp

No MCP username, password, token, or OAuth flow is required. The loopback address is the security boundary, so only clients on the same computer can connect.

Choose a transport

Streamable HTTP is not remote access. Although it uses HTTP, Workflow binds only to 127.0.0.1, validates the peer address, and rejects non-local browser origins.

Connect Codex

Codex desktop, Codex CLI, and the Codex IDE extension share MCP configuration on the same Codex host.

Add Streamable HTTP from the CLI

codex mcp add printFactoryWorkflow --url http://127.0.0.1:5440/mcp

Verify the saved configuration:

codex mcp list

Start or restart Codex after adding the server. In an interactive Codex session, use /mcp to check that printFactoryWorkflow is connected.

Add it in the Codex UI

1. Open Settings and select MCP servers.
2. Select Add server.
3. Name it printFactoryWorkflow.
4. Choose Streamable HTTP.
5. Enter http://127.0.0.1:5440/mcp.
6. Save and restart Codex or the IDE extension.

Configure Codex with TOML

For a personal configuration, add this to ~/.codex/config.toml. A trusted repository can instead use .codex/config.toml to scope the connection to that repository.

[mcp_servers.printFactoryWorkflow]
url = "http://127.0.0.1:5440/mcp"
required = false
default_tools_approval_mode = "writes"
tool_timeout_sec = 120

required = false lets Codex start when Workflow is closed. The optional writes approval mode asks before tools that change Workflow while allowing read-only discovery without a prompt.

Configure Codex stdio

Use the installed Workflow executable path. For a local macOS Debug build:

codex mcp add printFactoryWorkflow -- /Users/{user}/Applications/PrintFactory/Workflow.app/Contents/MacOS/Workflow --mcp

For a packaged installation, replace the executable with its absolute installed path. On Windows, use the absolute path to Workflow.exe with the same --mcp argument.

Do not configure both transports under the same name. Remove the existing entry before switching:

codex mcp remove printFactoryWorkflow

Official Codex MCP configuration reference: Connect Codex to MCP servers.

Connect Claude Code

The instructions in this section apply to Claude Code running locally on the same computer as Workflow.

Add Streamable HTTP

Workflow is a machine-wide application, so user scope is usually the most convenient:

claude mcp add --transport http printFactoryWorkflow --scope user http://127.0.0.1:5440/mcp

Use --scope local instead when the connection should be private to the current project, or --scope project to write a shared .mcp.json entry for the repository. Every developer using a shared entry must run Workflow locally.

Verify the connection:

claude mcp list
claude mcp get printFactoryWorkflow

Inside Claude Code, run /mcp and confirm that the server is connected. A project-scoped .mcp.json server requires explicit approval when the repository is first trusted.

The equivalent project-scoped .mcp.json entry is:

{
  "mcpServers": {
    "printFactoryWorkflow": {
      "type": "http",
      "url": "http://127.0.0.1:5440/mcp"
    }
  }
}

Configure Claude Code stdio

For a local macOS Debug build:

claude mcp add --transport stdio printFactoryWorkflow --scope user -- /Users/{user}/Applications/PrintFactory/Workflow.app/Contents/MacOS/Workflow --mcp

Again, replace the executable with the absolute installed path for packaged builds. The stdio child is only a proxy; it does not replace the running Workflow UI.

To switch transports:

claude mcp remove printFactoryWorkflow

Claude Code defers MCP tool schemas and discovers them on demand. Workflow's 57-tool catalog therefore does not need to be loaded into every prompt. If a client appears not to find a tool, mention the server and capability explicitly, for example: “Use the PrintFactory Workflow MCP tools to inspect this flow.”

Claude Code warns when a tool response exceeds 10,000 tokens and has a configurable maximum output size. Prefer Workflow resources for large Job XML, processed documents, and thumbnails instead of asking the client to repeat binary or verbose data inline.

Official Claude Code references:

• Connect Claude Code to tools via MCP
• Claude Code CLI reference

Claude Desktop and Claude.ai

The Workflow endpoint is intentionally local-only:

• Claude.ai in a web browser cannot connect to 127.0.0.1 on the Workflow computer.
• A Claude remote custom connector is also unsuitable because the remote connector service cannot reach this loopback endpoint.
• Claude Desktop local servers are now packaged as Desktop Extensions. Workflow does not currently ship a .dxt extension, so Claude Code is the supported Claude client for this integration.

A future Workflow Desktop Extension could package the stdio launcher. It would still need the Workflow UI application running locally.

First connection test

Begin with a read-only request:

Use the PrintFactory Workflow MCP server. Call workflow.info, then list the
available flows. Do not change anything. Report the MCP version, whether
configuration changes are licensed, and the flow names.

The expected MCP server version is 1.10.0. While an HTTP session is active, Workflow shows the connected icon beside the thumbnail-size slider. The tooltip reports the active session count.

Recommended authoring sequence

Ask the client to follow this order:

1. Call workflow.info.
2. Inspect component_types.list, component_types.get, and component_types.get_schema for every intended component.
3. Discover required Cloud resources, devices, queues, media, PMMs, variants, Cutter tools, markers, and Nest Groups through their dedicated tools.
4. Create a flow or read its complete graph.
5. Stop the flow before changing its graph.
6. Validate the proposed complete graph with flows.validate.
7. Apply it atomically with flows.apply_graph.
8. Start the flow and run a representative sample job.

Example:

Create a Workflow flow named "PDF preflight sample".
Before changing anything:
1. inspect the schemas and user documentation for the required Input,
   Preflight, and Export components;
2. discover the compatible Preflight profile;
3. show me the proposed graph and settings;
4. validate the complete graph.
Only apply the graph after it validates. Then return the created flow resource.

For small edits, use the typed component and connector tools. Normal authoring should not use raw Step or Connector XML. The raw XML tools are retained for compatibility and diagnostics.

Resource and device discovery

Do not invent GUIDs, device IDs, queue IDs, PMM variants, or driver settings.

• Use resources.list_types and resources.list for resource-backed component settings.
• Use devices.list, devices.list_queues, and devices.list_media for production configuration.
• Use devices.get_printer_configuration to combine a Printer DeviceID, PMM ProfileID, variant, ProfileGroup compatibility, and opaque driver defaults.
• Use devices.get_cutter_configuration for Cutter queues, tools, colors, and the default marker.
• Use nest_groups.list for a valid Nester NestID and NestName.

For an alternative CuttingMarks marker, call resources.list with its type and the selected Cutter deviceId. DriverFilter is matched against the Cutter DriverName—the Driver field from configuration/sites/all—not the Cutter Group.

Conditional branches and continuation

Every outgoing connector is evaluated independently:

• An unconditional connector accepts the job.
• A conditional connector accepts it only when its JavaScript condition returns true.
• The original job follows the first accepted connector.
• Every additional accepted connector receives a duplicate.
• If outgoing connectors exist but none accepts, the job enters Error.

An Output component is not automatically terminal. Any non-Error result socket may continue to another component. A job becomes Done only when its result has no outgoing connector.

Workflow intentionally does not enforce a universal component-order blacklist. flows.validate proves structural and schema correctness, but device-, media-, resource-, document-, and setting-dependent combinations still require a real sample.

Debug a flow with a sample job

Sample-job tools use Workflow's real processor queue; they are not a simulation.

Debug flow "<flow name>" with the local document
"/absolute/path/to/sample.pdf".

Enable flow debugging, start the flow, submit the document through the intended
Input component, and inspect the job every time it reaches Hold, Error, or Done.
At each Hold, report the completed component, connector result, journal changes,
root Keys, document metadata, and the next component. Do not continue until I
approve. Delete the disposable job when we finish.

The client should:

1. Enable flows.set_debugging.
2. Start the flow.
3. Call jobs.submit_sample.
4. Poll jobs.get until Hold, Error, or Done.
5. Use linked MCP resources to inspect Job XML, processed documents, or thumbnails.
6. Optionally change root Keys while the job is on Hold; changes affect only future Steps and connector decisions.
7. Call jobs.continue only for Hold jobs.
8. Delete disposable samples with jobs.delete.

Local input paths are copied into the retained job workspace. Workflow does not move or delete the caller's original file.

Recover an Error job through the API

Normal user recovery is to correct the flow or external cause and submit a new job. MCP additionally supports controlled API retry:

1. Read the Error job and its journal.
2. Call jobs.get_step_settings.
3. Inspect the associated component schema.
4. Correct the failed job's embedded current Step with jobs.update_step_settings.
5. Correct any external dependency that caused the failure.
6. Call jobs.retry.

Do not retry unchanged instructions; the same error is expected to occur again. The embedded Step change affects only that retained job, not the source flow component.

Operational constraints

• Input components must be the start of a flow and cannot have incoming connectors.
• The JavaScript processing component is partial and cannot be used for new authoring.
• JDF input is partial and should be treated as compatibility-dependent.
• Generic XML, JSON, and JDF files must use their specialized Input components rather than Hotfolder.
• Legacy <Job> and <NestParts> Hotfolder XML is compatibility-only and must not be generated by MCP clients.
• A flow must be stopped before graph mutation.
• A flow open in UI edit mode may reject mutations with 409 Conflict.
• Missing modifyConfiguration permission produces 403 Forbidden.
• Done and Error jobs, journals, Job XML, and documents remain until Workflow's configured cleanup window. Delete disposable sample jobs explicitly.

Connection and session behavior

Streamable HTTP initialization creates an MCP session. Some clients explicitly terminate it; others close without sending DELETE /mcp. Workflow expires abandoned sessions after five minutes of inactivity.

HTTP resource subscriptions use finite SSE batches. After an update or a 15-second keep-alive, the client reconnects for the next batch. A temporary disconnect therefore does not imply that the MCP server stopped.

Troubleshooting

Connection refused

• Confirm that the Workflow UI is running.
• Check curl -sS http://127.0.0.1:5440/info.
• Confirm that the client runs on the same computer.
• Confirm that the MCP URL ends with /mcp, not /api/v2.
• Restart the client after changing its MCP configuration.

Server is configured but tools are missing

• In Codex, run codex mcp list and /mcp.
• In Claude Code, run claude mcp get printFactoryWorkflow and /mcp.
• Approve a project-scoped Claude .mcp.json server after trusting the repository.
• Ask the client explicitly to use the PrintFactory Workflow MCP server; Claude Code may defer tool definitions until they are needed.

A write returns 403

The current Workflow license does not grant modifyConfiguration.

A graph change returns 409

Stop the flow and close its active FlowDesignCanvas edit session, then retry.

Cloud resources or devices fail to load

Check Workflow's Cloud sign-in and proxy connection. Do not add credentials to the MCP configuration.

A local sample path is rejected

Use an absolute path visible to the Workflow computer. The path is interpreted by Workflow, not by a remote model service.

The connected icon remains briefly after closing a client

The client probably closed without terminating its HTTP session. The count clears when the five-minute idle timeout expires.

Appendix: interoperability verification

Workflow exposes the same 57 flow-authoring and job-debugging tools through local Streamable HTTP and stdio. It also exposes flow, schema, job, Job XML, processed document, and thumbnail resources.

Verified client matrix

The Claude Code transport checks do not require an authenticated model request. They verify the real client transport, initialization sequence, negotiated server identity, tool/resource capabilities, and clean shutdown independently of a Claude account.

Streamable HTTP lifecycle

initialize returns MCP-Session-Id. Clients include it and the negotiated MCP-Protocol-Version on later requests. DELETE /mcp terminates it immediately. Workflow expires abandoned sessions after five minutes because Inspector and Claude Code may close their transport without explicitly terminating the server session.

GET /mcp returns finite text/event-stream batches. A subscribed idle request can wait up to 15 seconds; an event or keep-alive response then closes and the client reconnects. Resource changes use standard notifications/resources/updated and notifications/resources/list_changed messages.