Installation Guide

This guide covers installing Orchex and configuring it as an MCP server for Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients.

Prerequisites

  • Node.js 18 or higher
  • npm package manager
  • An LLM API key (Anthropic, OpenAI, Gemini, DeepSeek, or Ollama)
  • An MCP-compatible client (Claude Desktop, Cursor, Windsurf, Claude Code, etc.)

Quick Start

1. Install Orchex

npm install -g @wundam/orchex

Or install locally in your project:

npm install @wundam/orchex

2. Verify Installation

orchex --version

You should see the current version number (e.g., 1.0.0-rc.1).

3. Set Up Your API Key

Set an environment variable for your LLM provider:

# Pick one:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export DEEPSEEK_API_KEY=sk-...

Important: Never commit API keys to version control.

MCP Server Configuration

Orchex can be used as an MCP (Model Context Protocol) server, allowing AI assistants to orchestrate complex multi-step workflows.

Claude Desktop

  1. Locate your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add Orchex to the MCP servers section:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}

  1. Restart Claude Desktop

  2. Verify: Start a new conversation and ask Claude to list available Orchex tools. You should see tools like init, execute, status, learn, etc.

Cursor

  1. Open Cursor Settings (Cmd/Ctrl + ,)

  2. Navigate to Features → Model Context Protocol

  3. Add a new MCP server:

{
  "orchex": {
    "command": "npx",
    "args": ["-y", "@wundam/orchex"]
  }
}
  1. Restart Cursor

Windsurf

  1. Open Windsurf Settings

  2. Navigate to MCP Servers configuration

  3. Add Orchex:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}
  1. Restart Windsurf

Using a Local Installation

If you installed Orchex locally in your project:

{
  "mcpServers": {
    "orchex": {
      "command": "node",
      "args": ["./node_modules/@wundam/orchex/bin/orchex.js"]
    }
  }
}

Environment Variables

Orchex auto-detects your LLM provider from environment variables. Set one of:

  • ANTHROPIC_API_KEY — Anthropic Claude
  • OPENAI_API_KEY — OpenAI (GPT-4, GPT-4.1)
  • GEMINI_API_KEY — Google Gemini
  • DEEPSEEK_API_KEY — DeepSeek
  • OLLAMA_HOST — Ollama (local models)

You can pass these via the MCP config env field:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-key-here"
  }
}

To switch providers, use orchex config --provider <name>.

Verification Steps

Test CLI Installation

# Check version
orchex --version

# View current config
orchex config --show

Test MCP Server

  1. In Claude Desktop/Cursor/Windsurf, start a new conversation

  2. Ask: "Can you list the available Orchex tools?"

  3. You should see tools like:

    • init — Initialize an orchestration
    • execute — Run the orchestration
    • status — Check progress
    • learn — Parse a plan into streams
    • complete — Archive orchestration

  4. Try a test orchestration:

    Use orchex.init to create a simple orchestration with one stream
that creates a hello.ts file, then execute it.

Troubleshooting

"orchex: command not found"

  • Ensure Node.js and npm are installed: node --version && npm --version
  • If globally installed, check npm global bin path: npm bin -g
  • Add npm global bin to PATH or install locally instead

"API key not found" or Authentication Errors

  • Verify your ANTHROPIC_API_KEY is set correctly
  • Check for typos in your API key
  • Ensure the environment variable is accessible in your MCP config
  • Test your API key directly: curl https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY"

MCP Server Not Appearing in Client

  • Verify the config file path is correct for your OS
  • Check JSON syntax (use a JSON validator)
  • Ensure npx is available: npx --version
  • Check client logs for error messages
  • Restart the client application completely

"Module not found" Errors

  • Clear npm cache: npm cache clean --force
  • Reinstall: npm uninstall -g @wundam/orchex && npm install -g @wundam/orchex
  • Check Node.js version: node --version (must be 18+)

Workflow Execution Failures

  • Validate your manifest: orchex validate manifest.yaml
  • Check logs with DEBUG=orchex:* orchex execute manifest.yaml
  • Verify all required tools/commands are installed
  • Check file permissions for read/write operations

Enable Debug Logging

For detailed troubleshooting:

# CLI
DEBUG=orchex:* orchex execute manifest.yaml

# MCP Server - add to env in config:
{
  "env": {
    "DEBUG": "orchex:*",
    "ANTHROPIC_API_KEY": "..."
  }
}

Next Steps

Updating Orchex

# Global installation
npm update -g @wundam/orchex

# Local installation
npm update @wundam/orchex

# Check for updates
npm outdated -g @wundam/orchex

Uninstallation

# Global installation
npm uninstall -g @wundam/orchex

# Local installation
npm uninstall @wundam/orchex

# Remove MCP server config from your client
# (edit the claude_desktop_config.json or equivalent)

Getting Help

Need help? If you encounter any issues during installation, please check our troubleshooting section or reach out for support.