Skip to content

Configuration

Jump to bottom
lacause edited this page Mar 29, 2026 · 3 revisions

Configuration

Environment Variables

Variable Default Description
REST_PORT 4242 HTTP server port
REST_HOST 0.0.0.0 HTTP server bind address
CHAINS_DIR ../chains Directory containing chain YAML files
PIPELINES_DIR ../pipelines Directory containing pipeline YAML files
WORKSPACE_DIR — Additional allowed directory for /download endpoint
EXECUTIONS_FILE <tmpdir>/occ-executions.json Execution history file path
EXECUTION_MAX_AGE_DAYS 7 Auto-purge executions older than N days
CLAUDE_TIMEOUT_MS 1800000 (30 min) Default per-step timeout
CLAUDE_BIN claude Path to Claude CLI binary
CLAUDE_CLI claude Alternative path for Claude CLI (used by chain generator)
MAX_CONCURRENT_EXECUTIONS 5 Max simultaneous chain executions
CANVAS_DIST ../canvas/dist Frontend static files directory
SCHEDULES_FILE <chains_dir>/../schedules.json Schedule persistence file
NO_COLOR — Disable ANSI colors in Claude output

.mcp.json

The MCP configuration file tells Claude Code where to find the OCC server:

{
  "mcpServers": {
    "chain-orchestrator": {
      "command": "node",
      "args": ["/absolute/path/to/OCC/mcp-server/dist/index.js"],
      "env": {
        "CHAINS_DIR": "/absolute/path/to/OCC/chains",
        "PIPELINES_DIR": "/absolute/path/to/OCC/pipelines",
        "REST_PORT": "4242"
      }
    }
  }
}

Important: Paths must be absolute. Relative paths resolve from the Claude Code working directory, which may not be what you expect.

.env File

Copy .env.example to .env for local development:

cp .env.example .env

The server reads environment variables from the shell. If you want to use a .env file, use a tool like dotenv-cli:

npx dotenv-cli -- npm run rest

Running Modes

MCP Server (default)

npm start

Runs as MCP server over stdio. Used by Claude Code / Claude Desktop. Also starts the REST API on the configured port.

REST-only

npm run rest

Runs only the REST API server. No MCP. Useful for programmatic access or when Claude CLI calls are made externally.

Development

npm run dev

Watches for file changes and restarts automatically. Uses node --watch.

Deployment

systemd (Linux)

[Unit]
Description=OCC Chain Orchestrator
After=network.target

[Service]
Type=simple
User=occ
WorkingDirectory=/opt/occ/mcp-server
ExecStart=/usr/bin/node dist/rest.js
Restart=always
Environment=CHAINS_DIR=/opt/occ/chains
Environment=REST_PORT=4242

[Install]
WantedBy=multi-user.target

Docker

FROM node:20-slim
WORKDIR /app
COPY mcp-server/package*.json ./mcp-server/
RUN cd mcp-server && npm ci --production
COPY mcp-server/dist ./mcp-server/dist
COPY chains ./chains
COPY pipelines ./pipelines
ENV CHAINS_DIR=/app/chains
ENV PIPELINES_DIR=/app/pipelines
ENV REST_PORT=4242
EXPOSE 4242
CMD ["node", "mcp-server/dist/rest.js"]

PM2

pm2 start mcp-server/dist/rest.js --name occ \
  --env CHAINS_DIR=./chains \
  --env REST_PORT=4242

See Also

Clone this wiki locally