Configure MCP

orchex runs as an MCP (Model Context Protocol) server inside your AI coding assistant. This page walks you through configuring orchex for your editor of choice.

How It Works

Your AI assistant communicates with orchex through MCP. When you ask your assistant to "orchestrate a feature," it calls orchex's MCP tools (init, execute, status, etc.) behind the scenes. You don't invoke orchex directly — your assistant does.

You ──→ AI Assistant ──→ MCP Protocol ──→ orchex server ──→ LLM API
              ↑                                    │
              └────── results ─────────────────────┘

Prerequisites

Before configuring MCP, ensure you have:

  • Node.js 18+ installed (download)
  • orchex installed — npm install -g @wundam/orchex or use npx
  • An LLM API key from at least one provider (see Providers)

Claude Code

Claude Code uses a .mcp.json file for MCP server configuration.

Project-Level Configuration

Create .mcp.json in your project root:

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

Global Configuration

To make orchex available in all projects, create ~/.mcp.json:

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

Verify

Start a new Claude Code session and ask:

"List the available orchex tools"

You should see tools like init, execute, status, complete, learn, and recover.

Cursor

Cursor reads MCP configuration from its settings UI.

Steps

  1. Open Settings (Cmd/Ctrl + ,)
  2. Navigate to Features > Model Context Protocol
  3. Add a new MCP server with this configuration:
{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}
  1. Restart Cursor to pick up the change.

Verify

Open the Composer (Cmd/Ctrl + I) and ask Cursor to list available orchex tools.

Windsurf

Windsurf uses a similar MCP configuration format.

Steps

  1. Open Windsurf Settings
  2. Navigate to the MCP Servers configuration section
  3. Add orchex:
{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}
  1. Restart Windsurf.

Verify

Start a conversation and ask your assistant to list orchex tools.

Environment Variables

orchex auto-detects your LLM provider from environment variables. Set one (or more) of these:

# Pick your provider(s):
export ANTHROPIC_API_KEY="sk-ant-..."    # Anthropic Claude
export OPENAI_API_KEY="sk-..."           # OpenAI GPT-4
export GOOGLE_API_KEY="AI..."            # Google Gemini
export DEEPSEEK_API_KEY="sk-..."         # DeepSeek
# Ollama needs no key — just ensure it's running

Passing Keys via MCP Config

You can also pass API keys directly in the MCP configuration:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

This is useful when your shell environment doesn't propagate to the MCP server process.

Optional Variables

Variable Default Description
ORCHEX_PROVIDER auto-detected Force a specific provider (anthropic, openai, gemini, deepseek, ollama)
ORCHEX_LOG_LEVEL info Log verbosity: debug, info, warn, error
ORCHEX_ARTIFACTS_DIR .orchex Directory for orchestration state and artifacts

Using a Local Installation

If you installed orchex locally in your project (npm install @wundam/orchex), point the MCP config to the local binary:

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

This avoids the npx download step and locks orchex to your project's version.

Multi-Provider Setup

You can register multiple orchex instances with different providers:

{
  "mcpServers": {
    "orchex-claude": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": { "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    },
    "orchex-gpt": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }
    }
  }
}

This lets you switch providers by choosing which MCP server to invoke.

Troubleshooting

"orchex tools not available"

  • Verify .mcp.json exists and has valid JSON syntax
  • Ensure npx @wundam/orchex works from the command line
  • Restart your editor/CLI session
  • Check that Node.js 18+ is installed: node --version

"API key not found"

  • Confirm your API key environment variable is set: echo $ANTHROPIC_API_KEY
  • If using MCP env config, check for typos
  • Verify the key is valid by testing directly with curl

"Module not found" errors

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

Next Steps