A Model Context Protocol (MCP) server for AI agent workflow orchestration. Create structured, fidelity-enforced workflows that agents discover, navigate, and execute to fulfill user goals.
Quick Start • Architecture • Schemas • API • Workflow Fidelity • Development • Workflows • Engineering
Workflow Server guides AI agents through structured, multi-step workflows. A single always-applied IDE rule bootstraps the agent — from there, the server handles workflow discovery, session management, and step-by-step navigation.
- Discover — The agent calls
discoverto learn available workflows and the bootstrap procedure - Start session —
start_sessionreturns a session token;get_workflowreturns the workflow structure, the workflow'stechniques.workflowbundled undertechniquesandrules, and theinitialActivityID - Navigate —
next_activityadvances the session to the next activity;get_activityreturns the activity's full definition (steps, checkpoints, transitions) along with the activity's bundled techniques — the workflow's inheritedtechniques.activityplus the activity's owntechniques[]— undertechniquesandrules.get_resourcelazy-loads reference material referenced by a technique - Execute — The agent works through activities, with checkpoints for user decisions and transitions governing the flow between activities
User Goal → Workflow → Activities → Techniques → Tools
- Workflows define the overall process (e.g., implement a feature from issue to merged PR)
- Activities are phases within a workflow (e.g., plan, implement, review, validate)
- Techniques are markdown definitions of a capability, with optional rules
- Tools are the operations the agent invokes
The server registers 16 MCP tools across five concerns. See docs/api-reference.md for full signatures.
| Concern | Tools |
|---|---|
| Bootstrap (no session token) | discover, list_workflows, health_check |
| Session | start_session, get_workflow_status, dispatch_child |
| Workflow / activity navigation | get_workflow, next_activity, get_activity |
| Checkpoint flow | yield_checkpoint, resume_checkpoint, present_checkpoint, respond_checkpoint |
| Techniques, resources | get_technique, get_resource |
| Trace | get_trace |
- Node.js 18+
- MCP Client (Cursor or Claude Desktop)
# Clone and build
git clone https://github.com/m2ux/workflow-server.git
cd workflow-server
npm install
# Set up workflow data (worktree for orphan branch)
git worktree add ./workflows workflows
# Build the server
npm run buildCursor (~/.cursor/mcp.json):
{
"mcpServers": {
"workflow-server": {
"command": "node",
"args": ["/path/to/workflow-server/dist/index.js"],
"env": {
"WORKFLOW_DIR": "/path/to/workflow-server/workflows"
}
}
}
}Restart your MCP client. See SETUP.md for other IDEs.
To set up the engineering branch pattern in your own project:
curl -O https://raw.githubusercontent.com/m2ux/workflow-server/main/scripts/deploy.sh
chmod +x deploy.sh && ./deploy.shThis creates a .engineering/ folder with workflows and artifact directories. See SETUP.md for options and details.
Add the bootstrap rule from docs/ide-setup.md to your IDE's 'always-applied' rule set. The rule tells the agent to call discover on every workflow request so the bootstrap procedure stays in sync with the server.
Tell the agent what you want to do using natural language:
Start a workflow:
Start a new work-package workflow for implementing user authentication
Begin a work-package workflow for issue #42
Resume a workflow:
Resume the work-package workflow we were working on
Continue the authentication work package from where we left off
End a workflow:
End the current work-package workflow
Complete the work package and clean up
The agent matches your request to the appropriate activity and guides you through the structured phases.
The .engineering/ directory holds engineering artifacts and workflow-related assets.
artifacts/planning/— Work package plans and specificationshistory/— Project history and change logsscripts/— Utility scripts
MIT License - see LICENSE for details.