workflows-mcp-server

MCP Workflow Orchestration Server

Empower your AI agents with a powerful, declarative workflow engine.

An MCP (Model Context Protocol) server that allows a Large Language Model (LLM) to discover, understand, and execute complex, multi-step workflows defined in simple YAML files.

Built on the cyanheads/mcp-ts-template, this server follows a modular architecture with robust error handling, logging, and security features.

🚀 Core Capabilities: Workflow Tools 🛠️

This server equips your AI with specialized tools to interact with the workflow engine:

Table of Contents

| Overview | Features | Installation | | Configuration | Project Structure | | Tools | Development | License |

Overview

The Workflow MCP Server acts as a powerful orchestration layer that helps your LLM agents manage complex workflows. This provides a structured way to perform 'short' multi-step tasks that would otherwise require hard-coded logic or extensive manual intervention.

It's as easy as telling your LLM "Use the workflows-mcp-server to create a new workflow that does X, Y, and Z, using the current tools you currently have access to" or "Find me a workflow that can help with task A". The server will handle the rest, allowing your agents to focus on higher-level reasoning and decision-making. The temporary workflows can be used to allow your LLM agent to "collect its thoughts" and create a structured temporary plan; even the act of defining a workflow can help the agent clarify its own understanding of the task at hand and improve tool use performance.

Instead of hard-coding multi-step logic, your tools can leverage this server to:

• Automate complex processes: Define a sequence of tool calls in a simple YAML file and execute it with a single command.
• Promote reusability: Create a library of common workflows that can be used across different agents and applications.
• Improve agent reliability: Provide agents with a clear, structured plan to follow, reducing errors and improving predictability.
• Dynamically guide agent behavior: Use global instructions to provide up-to-date, high-level strategy to all workflows without modifying them individually.

Developer Note: This repository includes a file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.

Features

Core Utilities

Leverages the robust utilities provided by the mcp-ts-template:

• Logging: Structured, configurable logging with sensitive data redaction.
• Error Handling: Centralized error processing and standardized error types (McpError).
• Configuration: Environment variable loading (dotenv) with comprehensive validation using Zod.
• Input Validation/Sanitization: Uses zod for schema validation.
• Request Context: Tracking and correlation of operations via unique request IDs.
• Type Safety: Strong typing enforced by TypeScript and Zod schemas.
• HTTP Transport: High-performance HTTP server using Hono, featuring session management and robust authentication.
• Authentication: Modular authentication layer supporting JWT and OAuth 2.1.

Workflow Engine

• YAML-based Workflows: Define complex, multi-step workflows in a simple, human-readable format.
• Dynamic Indexing: Automatically discovers and indexes all workflow files on startup and watches for changes.
• Global Instructions: Dynamically injects a central set of instructions into every workflow, allowing for global strategy updates.
• Temporary Workflows: Create "hidden" workflows on the fly for complex tasks or for passing structured plans between agents.

Installation

Prerequisites

• Node.js (>=20.0.0)
• npm (comes with Node.js)

MCP Client Settings

Add the following to your MCP client's configuration file (e.g., cline_mcp_settings.json). This configuration uses npx to run the server, which will automatically install the package if not already present:

{
  "mcpServers": {
    "workflows-mcp-server": {
      "command": "npx",
      "args": ["workflows-mcp-server"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

If running manually (not via MCP client) for development or testing

Install via npm

npm install workflows-mcp-server

Alternatively Install from Source

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Environment Variables

Configure the server using environment variables. These can be set in a .env file or directly in your shell.

Project Structure

The codebase follows a modular structure within the src/ directory:

src/
├── index.ts              # Entry point: Initializes and starts the server
├── config/               # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/           # Core MCP server logic and capability registration
│   ├── server.ts         # Server setup, capability registration
│   ├── transports/       # Transport handling (stdio, http)
│   └── tools/            # MCP Tool implementations (subdirs per tool)
├── services/             # External service integrations
│   └── workflow-indexer/ # Discovers and indexes workflow YAML files
├── types-global/         # Shared TypeScript type definitions
└── utils/                # Common utility functions (logger, error handler, etc.)

For a detailed file tree, run npm run tree or see .

Tools

The server provides a suite of tools for managing and executing workflows.

Development

Build and Test

# Build the project (compile TS to JS in dist/ and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean build artifacts and then rebuild the project
npm run rebuild

# Format code with Prettier
npm run format

# Start the server using stdio (default)
npm start

# Start the server using HTTP transport
npm run start:http

License

This project is licensed under the Apache License 2.0 - see the file for details.