Quick Start

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

Local (stdio)

1. Install the stdio package globally:

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

2. Configure Claude Desktop by adding to .mcp.json:

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

3. Restart Claude Desktop to load the new server.

Remote (HTTP)

1. Use the hosted service - no deployment needed:

   https://api.workflow-mcp.blackmesa.live/mcp

2. 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:

1. Create a session log file
2. Begin gathering information
3. Log findings with Entry-IDs
4. 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