Getting started

Install the server, set up .engineering in your project, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need Node.js 18+ and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see The pieces on the home page.

1. Install and build

# Clone and install
git clone https://github.com/m2ux/workflow-server.git
cd workflow-server
npm install

# Set up workflow data (worktree for the orphan `workflows` branch)
git worktree add ./workflows workflows

# Build the server
npm run build

The workflow definitions live on a separate workflows branch — an orphan branch with no shared history with main — checked out as a worktree beside the server code. Server releases and workflow edits change on different cadences; separate histories let you pin each side independently and keep content pull requests out of server review.

2. Deploy .engineering to your project

Session state lives under your project’s .engineering/artifacts/planning/ tree. From the root of the project you will use as your workspace — not the workflow-server clone — run:

curl -O https://raw.githubusercontent.com/m2ux/workflow-server/main/scripts/deploy.sh
chmod +x deploy.sh
./deploy.sh

The script creates .engineering/ with the artifact directories and workflow submodules the server expects. Commit the submodule entry when it finishes. For deploy modes, options, and updating submodules, see SETUP.md (source).

3. Configure your MCP client

Register the server in your client's MCP configuration. For Cursor this is ~/.cursor/mcp.json; for Claude Desktop it is claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

{
  "mcpServers": {
    "workflow-server": {
      "command": "node",
      "args": ["/path/to/workflow-server/dist/index.js"],
      "env": {
        "WORKFLOW_DIR": "/path/to/workflow-server/workflows",
        "WORKFLOW_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Set WORKFLOW_WORKSPACE to the project root from step 2. It points at the repository whose .engineering/artifacts/planning/ folder holds session state. It is required: the server refuses to start without a workspace (you can pass --workspace=PATH as a command-line argument instead). Restart your MCP client after editing the configuration.

4. Add the bootstrap rule

Add this to your IDE's always-applied rule set (a Cursor rule, a Claude Code project rule, or the equivalent in your client):

For any start workflow, create work package, or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure. Complete the procedure before any other action.

If the user provides a `session_token`, pass it to subsequent workflow-server calls per their instructions.

Restart your MCP client after adding the rule.

5. Verify

Ask your agent:

Use the workflow server to list available workflows

The agent should call list_workflows and return the workflow inventory.

Then ask it to start a work-package workflow. It should call discover first, then proceed through list_workflows, start_session, and get_workflow. If it skips discover, the rule is not applied — recheck your IDE rule configuration.

6. Run and resume

Drive workflows in natural language — no tool names, no tokens to copy. A work package is the bundled workflow for planning and implementing one unit of work (for example a feature or issue).

Start a workflow by naming the goal:

Start a new work-package workflow for implementing user authentication

Begin a work-package workflow for issue #42

Resume one — sessions live on disk, so this works across restarts and even across chat conversations:

Resume the work-package workflow we were working on

Continue the authentication work package from where we left off

Finish or wind one down:

End the current work-package workflow

Next steps

• Browse the definitions — a glossary of terms you will encounter across the docs and in workflow runs.