workflow-code mcp

workflow-code mcp starts a projectType: "workflow" project as a standard MCP Server. Every entrypoint becomes one tool. Conversation, Kanban, and ordinary folders are not exposed through MCP.

The Server name is workflow-<package.json.id>. Tool names are the entrypoint IDs, while titles, descriptions, and parameters come from the structure report read at startup. The tool catalog remains fixed for the connection; reconnect after changing the project, entrypoints, static parameters, or draft.

Command format

workflow-code mcp <workflow-dir> [options]

workflow-dir is a required Workflow project directory. The project must declare an immutable UUID in package.json.id.

MCP client configuration

After installing the workflow-code bin, use a generic stdio definition:

{
  "mcpServers": {
    "workflow-11111111-1111-4111-8111-111111111111": {
      "command": "workflow-code",
      "args": [
        "mcp",
        "/absolute/path/to/workflow"
      ]
    }
  }
}

The Dock for a local Workflow also includes an MCP tab. It copies a compact client definition instead of the long CLI invocation above. A packaged definition contains only the Workflow Code executable, --workflow-mcp, and the Desktop project ID. The AI client starts a headless Desktop process on demand. The launcher then reads the project and related projects from Desktop's registry and resolves the runtime, data directories, and saved authentication internally. There is no launch command to run manually, and copied definitions contain neither account API keys nor those internal paths. Development definitions add the development app entry and a short profile argument.

{
  "mcpServers": {
    "workflow-<PROJECT_UUID>": {
      "command": "<WORKFLOW_CODE_EXECUTABLE>",
      "args": ["--workflow-mcp", "<DESKTOP_PROJECT_ID>"]
    }
  }
}

The project must remain registered in the Desktop workspace that generated the definition. Reconnect the client after changing project source, entrypoints, static parameters, or related projects.

Options

Option	Description
--data-dir <absolute-dir>	Root for local workflow data; defaults to ~/.workflow-code.
--file-store-dir <absolute-dir>	Managed-file store for imported MCP file parameters.
--kv-store-dir <absolute-dir>	Local KV store for the current project.
--persistent-value-store-dir <absolute-dir>	PersistentValue and local Knowledge storage.
--file-create-store-dir <absolute-dir>	Directory for files generated by the local runtime.
--desktop-config-dir <absolute-dir>	Directory containing saved Desktop connection authentication.
--auth-dir <absolute-dir>	Directory containing the CLI workflow-auth.json.
--related-project <alias>=<absolute-project-dir>	Bind one relationship confirmed by both projects; repeatable.

All directory options except workflow-dir require absolute paths. Core continues to load the project's .env. Explicit WORKFLOW_SERVER_URL / WORKFLOW_SERVER_ADMIN_KEY values take precedence over saved authentication.

Tool arguments

The MCP input schema is generated from each entrypoint's static params with additionalProperties: false:

Workflow parameter	MCP input
string / positional	string
number	number
boolean	boolean
multiple: true / checkboxes	An array of the corresponding type
file	An absolute file path; multiple files use an array of paths

The schema includes required, defaults, descriptions, static options, and date formats. resolveParams never rewrites the MCP schema. Projects with dynamic options still expose static params as their public contract.

Local file parameters do not accept relative paths, URLs, or Base64. The host verifies a regular file and the 50 MB limit before importing it into the current managed-file store.

{
  "prompt": "Analyze the attachments",
  "documents": [
    "/absolute/path/to/spec.pdf",
    "/absolute/path/to/notes.md"
  ]
}

Execution, interactions, and results

The MCP host runs the existing structure / json path in isolated workers. stdio stdout carries JSON-RPC only; project logs and worker diagnostics go to stderr. Cancelling a tool call terminates its worker.

When a workflow enters waiting_for_input or waits for tool approval, clients with form elicitation support resume the same runId across consecutive interactions. A client without elicitation support, a pending form containing a file field, or an arbitrary array field without static options receives an interaction_required tool error with the runId and a field summary. Nothing is automatically approved. Interactive multi-select fields need static options before a standard MCP form can resume them.

Successful calls write the same value to text content and structuredContent:

{
  "runId": "20260828-abcd",
  "status": "success",
  "entrypointId": "main",
  "entrypointTitle": "Main",
  "output": {}
}

output comes only from report.result.data.output. Failure, a nonzero business errCode, cancellation, or timeout adds a compact error and sets isError: true. Full reports, node details, stdout, stderr, and internal credentials are never returned. Invalid argument shapes use MCP InvalidParams.

When the compact definition from the Desktop MCP tab starts the server, the headless launcher writes every tool call to that Desktop workspace's SQLite database. A record contains the original MCP input, converted CLI args, values submitted across consecutive interactions, the complete report, stdout, stderr, and each lifecycle status. running, waiting_for_input, resumed, and final snapshots update one row under the same runId. Calls appear in Home recent tasks and project run history, with Output, Diagram, and Logs available for inspection. An open main window refreshes automatically; otherwise the record appears the next time Desktop starts.

Running the generic workflow-code mcp <workflow-dir> command manually has no Desktop registry or userData context, so it does not automatically write Desktop SQLite. KV, PersistentValue, Knowledge, and managed files continue to use the command's supplied or default data directories.