Quick Start

Get Workflow MCP running in your project in just a few minutes.

Prerequisites

Node.js 18 or later
pnpm, npm, or yarn
Claude Desktop or another MCP client

Installation

Install the stdio package globally:

npm install -g @blackmesa/workflow-mcp-stdio

Configure Claude Desktop by adding to .mcp.json:

{
  "mcpServers": {
    "workflow": {
      "command": "npx",
      "args": ["@blackmesa/workflow-mcp-stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

Restart Claude Desktop to load the new server.

Use the hosted service - no deployment needed:
```
https://api.workflow-mcp.blackmesa.live/mcp
```

Configure your MCP client to use this HTTP endpoint in your .mcp.json:

{
  "mcpServers": {
    "workflow": {
      "url": "https://api.workflow-mcp.blackmesa.live/mcp"
    }
  }
}

Your First Workflow

Once installed, you can start using workflow commands with Claude:

Start a Research Session

/workflow:research MY-TOPIC

Claude will:

Create a session log file
Begin gathering information
Log findings with Entry-IDs
Generate a handoff for the next phase

Log Entries

During a session, Claude uses the MCP tools to log structured entries:

mcp__workflow__log_entry({
  tag: "finding",
  fields: {
    title: "Key Architecture Decision",
    type: "Technical",
    content: "The system uses event sourcing...",
    evidence: "src/events/store.ts:42"
  }
})

End a Session

/workflow:end

This generates a summary and handoff message for the next phase.

Workflow Commands

Command	Purpose	Default DPS
`/workflow:research`	Gather information	4 (flexible)
`/workflow:plan`	Design implementation	1 (strict)
`/workflow:implement`	Write code	1 (strict)
`/workflow:review`	Identify gaps	3 (moderate)
`/workflow:debug`	Root cause analysis	4 (flexible)

Next Steps

Installation Guide - Detailed setup instructions
Sessions & Entries - Understanding session management
Tools Reference - Complete tool documentation

Quick Start

On this page