Local Deployment (stdio)

Local Deployment (stdio)

The stdio transport is the simplest way to use Workflow MCP with Claude Desktop or other local MCP clients.

Installation

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

Configuration

Claude Desktop

Add to your .mcp.json:

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

Custom Client

If building your own MCP client:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@blackmesa/workflow-mcp-stdio'],
  cwd: '/path/to/project'
});

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);

// Use the tools
const result = await client.callTool('start_session', {
  command: '/research',
  topic: 'MY-TOPIC'
});

Working Directory

The cwd setting is important - it determines where session files are created:

your-project/
  .claude/
    workflow/
      .session-state.json
  projects/
    research/
      RESEARCH_MY-TOPIC_2026-01-12.md
    plans/
    implementations/

Troubleshooting

Server not starting

Check that Node.js 18+ is installed:

node --version

Tools not showing in Claude

1. Restart Claude Desktop after changing .mcp.json
2. Check the server logs in Claude’s developer console
3. Verify the path to your project is correct

Permission errors

Ensure the project directory is writable:

mkdir -p /path/to/project/projects
chmod 755 /path/to/project/projects