Workflows MCP Server

@cyanheads/workflows-mcp-server Store, query, and create YAML workflow playbooks for LLM agents via MCP. STDIO or Streamable HTTP. 5 Tools

---

Overview

A declarative workflow library for LLM agents, backed by local YAML files. Store, list, and retrieve named, versioned multi-step playbooks — each a sequence of MCP server/tool calls — for permanent reuse or one-shot temporary runs. Edits to the YAML files are picked up automatically.

Tools

Capability reference

workflow_list tool

• Optional query (name and description), category (substring), and tags (all must match) filters, case-insensitive; temporary drafts are never listed
• Sorted by name, then highest version first; an empty result carries a notice echoing the applied filters
• includeTools: true adds each workflow's unique server/tool pairs

---

workflow_get tool

• name plus an optional semver version; omit version for the highest available, drafts included
• Returns the full workflow, its source (permanent or temp), and globalInstructions from global_instructions.md (null when absent); fails with not_found or version_not_found
• Template placeholders such as {{input.foo}} come back verbatim — the server never interpolates them

---

workflow_create tool

• name, semver version, description, author, category, and steps (plus optional tags); stored as one file per name@version under categories/ /, with created and updated dates stamped
• Returns the key (name@version) and filePath; fails with already_exists when a permanent workflow or a draft holds the key, invalid_input, or write_failed

---

workflow_create_temp tool

• The workflow_create fields minus category; stored under temp/, retrievable with workflow_get, never listed, and kept until workflow_delete removes it
• status is created, or overwritten when it replaced the draft of the same key (keeping that draft's created_date); a key held by a permanent workflow fails with already_exists

---

workflow_delete tool

• name plus an optional version (omitted: the highest across permanent workflows and drafts); the user confirms the resolved name@version, source, and file before anything is deleted, so a client without elicitation cannot delete
• Returns the deleted workflow's source, plus a notice when another file declaring the same key now takes its place; fails with cancelled, confirmation_invalid (a prompt never issued, already answered, older than 10 minutes, or issued to another caller), target_changed (the file or its content changed after the user saw it), or not_found

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Workflow library:

• YAML files under categories/ and temp/ are validated at index time; an invalid file is skipped and logged, never crashes the server
• In-memory index keyed by name@version, read from each file's content rather than its name and kept fresh by a debounced recursive watcher; a permanent workflow outranks a draft with the same key
• Versions are canonical semver everywhere: a leading v, surrounding whitespace, and build metadata are dropped, so v1.0.0+build.5 is stored, keyed, and looked up as 1.0.0
• Creates and deletes run one at a time, so each existence check holds until its write lands; filenames carry a hash of name@version, so keys whose slugs coincide never share a file
• An _index.json snapshot is written on every rebuild for external tooling and debugging

Agent-friendly output:

• Discriminated output — source: "permanent" | "temp" on every workflow_get response and typed reason codes (not_found, version_not_found, already_exists, cancelled, confirmation_invalid, target_changed, index_unavailable, …) on failures, so callers branch on data instead of parsing error strings
• No extra round trip — workflow_get always returns globalInstructions alongside the workflow definition in the same response
• Response shaping — workflow_list's optional includeTools flag pre-derives the unique server/tool pairs used by a workflow, and an empty result echoes the applied filters with a broadening hint instead of returning nothing

---

Getting started

No API keys required. The server reads from a local workflows-yaml/ directory by default.

Add the following to your MCP client configuration file:

{

"mcpServers": { "workflows-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/workflows-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml" } } } }

Or with npx (no Bun required):

{

"mcpServers": { "workflows-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/workflows-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml" } } } }

Or with Docker:

{

"mcpServers": { "workflows-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-v", "/absolute/path/to/your/workflows-yaml:/workflows-yaml", "-e", "WORKFLOWS_DIR=/workflows-yaml", "ghcr.io/cyanheads/workflows-mcp-server:latest" ] } } }

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http

Server listens at http://localhost:3010/mcp

Seed workflows

The repository ships a workflows-yaml/ directory with example workflows organized under categories/. These are ready to use as a starting point. The workflows-yaml/global_instructions.md file contains instructions the server includes in every workflow_get response (the globalInstructions field) — edit it to set global guidance for your agent.

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A local directory containing YAML workflow files (or use the bundled workflows-yaml/ seed).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/workflows-mcp-server.git

1. Navigate into the directory:

cd workflows-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env

edit .env if needed — most settings have defaults

---

Configuration

See .env.example for the full list of optional overrides.

---

Running the server

Local development

• Build and run:

  # One-time build

bun run rebuild

Run the built server

bun run start:stdio

or

bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security

bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec

Docker

docker build -t workflows-mcp-server .

docker run --rm \ -v /path/to/workflows-yaml:/workflows-yaml \ -e WORKFLOWS_DIR=/workflows-yaml \ -p 3010:3010 \ workflows-mcp-server

The Docker