@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.
| Tool | Description |
|---|
workflow_list | List all permanent workflows in the index, with optional keyword, category, and tag filters. |
workflow_get | Retrieve a complete workflow definition by name, with the library's global instructions included. |
workflow_create | Write a new permanent workflow YAML to the library. |
workflow_create_temp | Write a temporary workflow draft, indexed but excluded from list results, kept until deleted. |
workflow_delete | Remove a permanent workflow or a temporary draft by name and optional version, after the user confirms the resolved target. |
Capability reference
- 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
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
name, semver version, description, author, category, and steps (plus optional tags); stored as one file per name@version under categories/<category>/, 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
- 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
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
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
- Clone the repository:
git clone https://github.com/cyanheads/workflows-mcp-server.git
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
| Variable | Description | Default |
|---|
WORKFLOWS_DIR | Absolute or relative path to the workflows root directory. | ./workflows-yaml |
GLOBAL_INSTRUCTIONS_PATH | Path to the global instructions markdown file. Derives from WORKFLOWS_DIR when not set. | <WORKFLOWS_DIR>/global_instructions.md |
WATCHER_DEBOUNCE_MS | Integer milliseconds (0โ2147483647) to debounce filesystem change events before rebuilding the index. | 500 |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | Port for HTTP server. | 3010 |
MCP_SESSION_MODE | HTTP sessions: auto or stateful. workflow_delete's confirmation prompt needs a live session, so HTTP startup with stateless fails with a configuration error. Ignored over stdio. | stateful, declared in src/index.ts |
MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
MCP_REQUEST_STATE_KEY | Seals the requestState a confirmation round carries (โฅ 32 bytes, the same on every instance, e.g. openssl rand -base64 32); any state the server did not seal is rejected before the handler runs. workflow_delete's round carries its confirmation id, so set it for HTTP deployments. | unset |
MCP_LOG_LEVEL | Log level (RFC 5424). | info |
LOG_TOOL_FAILURE_PAYLOADS | Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted. | false |
OTEL_ENABLED | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | false |
See .env.example for the full list of optional overrides.
Running the server
Local development
-
Build and run:
bun run rebuild
bun run start:stdio
bun run start:http
-
Run checks and tests:
bun run devcheck
bun run test
bun run lint:mcp
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 Dockerfile defaults to HTTP transport, stateful session mode (required โ see MCP_SESSION_MODE above), and logs to /var/log/workflows-mcp-server. OpenTelemetry peer dependencies are installed by default โ build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
| Directory | Purpose |
|---|
src/index.ts | createApp() entry point โ registers tools and inits the workflow index service. |
src/config/ | Server-specific environment variable parsing and validation with Zod. |
src/mcp-server/tools/ | Tool definitions (*.tool.ts). |
src/services/workflow-index/ | WorkflowIndexService โ YAML parsing, index build, watcher, semver lookup, write helpers. |
tests/ | Unit and integration tests mirroring src/. |
workflows-yaml/ | Seed workflow library โ categories/ for permanent workflows, temp/ for temporary drafts, global_instructions.md for agent-global guidance. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches โ no
try/catch in tool logic
- Use
ctx.log for request-scoped logging
- Register new tools via the barrel in
src/mcp-server/tools/definitions/index.ts
- Filesystem operations go through
WorkflowIndexService, not directly in tool handlers
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run test
License
Apache-2.0 โ see LICENSE for details.