Workflows MCP Server

What workflows-mcp-server does

workflows-mcp-server provides an MCP interface to a local YAML workflow library. Each playbook has a name, semantic version, description, author, category, optional tags, and a sequence of steps that identify MCP server/tool calls. Permanent workflows live in category directories and are available through listing and retrieval operations. Temporary drafts are stored separately for one-shot plans or unfinished work.

The server also returns global execution guidance from global_instructions.md with each workflow retrieval. Template expressions such as {{input.foo}} remain literal text; the server stores and returns them without resolving their values.

How it works

Workflow files are validated while the library index is built. Invalid files are skipped and logged rather than stopping the server. A recursive watcher refreshes the in-memory index after file changes, and an _index.json snapshot is written after rebuilds. Permanent workflows take precedence when a permanent file and a temporary draft declare the same name and version.

Versions use canonical semantic-version formatting. Leading v, surrounding whitespace, and build metadata are removed when keys are stored and looked up. Writes and deletes are serialized so existence checks remain valid through the filesystem operation. The server can run over STDIO or Streamable HTTP and is built on @cyanheads/mcp-ts-core.

Setup and configuration

The default storage location is a local workflows-yaml/ directory. Set WORKFLOWS_DIR to use another location. A client can launch the package with bunx or npx; Docker is also supported when the workflow directory is mounted into the container.

For an HTTP deployment, set MCP_TRANSPORT_TYPE=http and choose a port with MCP_HTTP_PORT; the MCP endpoint is served at /mcp. STDIO configurations set MCP_TRANSPORT_TYPE=stdio. No API key is required for the basic local setup.

Claude Desktop, Cursor, and VS Code have installation or configuration paths provided for the package. Example workflows can be used as a starting point, and global_instructions.md can define guidance included in every workflow_get response.

Tools and capabilities

• workflow_list searches permanent workflows by name or description, category substring, and tags. Filters combine with AND logic. An includeTools option adds unique server/tool pairs used by each result.
• workflow_get returns the complete definition for a requested name and optional version. Omitting the version selects the highest available version, including temporary drafts.
• workflow_create writes a new permanent workflow and stamps creation and update dates. Existing name/version keys are rejected.
• workflow_create_temp writes a draft outside list results. Reusing an existing draft key replaces that draft while preserving its creation date.
• workflow_delete removes a permanent workflow or draft after client confirmation. The confirmation identifies the resolved key, source, and file, and is valid for one response within ten minutes.

Responses include whether a retrieved workflow is permanent or temporary, while failures use typed reason codes such as not_found, already_exists, cancelled, and target_changed.

Limitations and notes

Temporary drafts do not expire automatically and remain on disk until deleted. They cannot be returned by workflow_list, although workflow_get can retrieve them. Workflow deletion is irreversible, requires a client capable of showing the confirmation prompt, and is refused if the target file changes after confirmation. Name/version collisions are rejected for permanent creation, while a temporary creation can overwrite only a draft with the same key. Workflow steps are not executed by this server, and template placeholders are not interpolated.