MCP Workflow Orchestration Server

Enables AI agents to discover, create, and execute complex, multi-step workflows defined in simple YAML files.

Store, query, and create YAML workflow playbooks for LLM agents via MCP. STDIO or Streamable HTTP.

Five tools covering the full workflow library lifecycle — discovery, retrieval, creation, and deletion for both permanent and temporary workflows:

List permanent workflows from the in-memory index.

- Optional keywordqueryfilter (case-insensitive substring across workflow name and description)
- Optional category filter (case-insensitive substring match)
- Optional tag filter (AND match — all listed tags must be present)
- SetincludeTools: trueto surface the uniqueserver/toolpairs used across each workflow's steps
- Temporary workflows are excluded; results sorted by name then version descending
- Empty results echo the applied filters with a hint to broaden

Retrieve a complete workflow by name, including the global instructions document.

- Semver-aware: omitversionto get the highest available match; specify a version for an exact lookup
- Returns the full workflow YAML structure with all steps and metadata
- Injects theglobal_instructions.mdcontent asglobalInstructions— apply these when executing the workflow;nullwhen the file is absent
- Temporary workflows are accessible here even though excluded fromworkflow_list
- Template placeholders ({{input.foo}},{{steps.X.output.Y}}) are returned verbatim — the server never interpolates them

Write a new permanent workflow to the library.

- Workflow stored atcategories/<slugified-category>/<slugified-name>-<slugified-version>-workflow.yaml— one file pername@version, so multiple versions coexist
- Rejects ifname@versionalready exists — bump the version to create a new revision
- Server stampscreated_dateandlast_updated_dateautomatically
- Index and snapshot rebuilt after write; filesystem watcher also fires (idempotent, debounced)

Write a throwaway workflow to thetemp/directory.

- No conflict check — temp workflows are intentionally ephemeral and overwriteable
- Indexed and accessible viaworkflow_getbut excluded fromworkflow_listresults
- Useful for one-shot plans, short-lived scaffolding, or session-specific orchestration steps

Permanently remove a permanent workflow from the library.

- Semver-aware: omitversionto delete the highest available match; specify a version to target one exactly
- Only permanent workflows can be deleted — temporary workflows are rejected (they expire on their own)
- Irreversible: the file is removed and the workflow no longer appears inworkflow_listorworkflow_get

- Declarative tool definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth:none,jwt,oauth
- Swappable storage backends:in-memory,filesystem,Supabase,Cloudflare KV/R2/D1
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

- In-memory index keyed byname@version, built at startup fromworkflows-yaml/categories/recursively
- Semver-aware lookup — latest version returned when version is omitted
- Filesystem watcher (Node.jsfs.watchrecursive) rebuilds the index on any add/change/remove; debounced to avoid thrash
- YAML validated at index time — invalid files are skipped and logged, never crash the server
- _index.jsonsnapshot written on every rebuild for external tooling and debugging
- ConfigurableWORKFLOWS_DIR,GLOBAL_INSTRUCTIONS_PATH, and debounce interval

- workflow_getalways includesglobalInstructionsalongside the workflow — no second call needed
- Discriminatedsourcefield (permanent|temp) on everyworkflow_getresponse
- Typed error contracts with structuredreasoncodes (not_found,version_not_found,already_exists,temp_not_allowed,index_unavailable) so callers can branch on error type rather than parsing messages
- workflow_listwithincludeTools: truesurfaces all MCP server/tool dependencies at a glance

No API keys required. The server reads from a localworkflows-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" } } } }

{ "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" } } } }

{ "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

The repository ships aworkflows-yaml/directory with example workflows organized undercategories/. These are ready to use as a starting point. Theworkflows-yaml/global_instructions.mdfile contains instructions the server prepends to everyworkflow_getresponse — edit it to set global guidance for your agent.

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

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

cp .env.example .env # edit .env if needed — most settings have defaults

See.env.examplefor the full list of optional overrides.

# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http

bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec

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

SeeCLAUDE.mdfor development guidelines and architectural rules. The short version:

Keep teams & agents coordinated automatically