steamharness mcp

steamharness 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

steamharness 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 steamharness bin, use a generic stdio definition:

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

Options

Option	Description
--data-dir <absolute-dir>	Root for local workflow data; defaults to ~/.steamharness.
--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.
--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 STEAMHARNESS_SERVER_URL / STEAMHARNESS_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.

KV, PersistentValue, Knowledge, and managed files use the command's supplied or default data directories.

Project configurations

All three project types expose fields, named profiles and complete import/export. Studio and local CLI share local storage; Server values are per project and account. Studio Control can query and manage configurations even when the panel is closed. See Project configurations for the JSON actions, version checks and execution snapshot rules.