Skip to content

Configuration

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

Configuration

Environment Variables

Variable Default Description
Server
REST_PORT 4242 HTTP server port
REST_HOST 0.0.0.0 HTTP server bind address
Paths
CHAINS_DIR ../chains Directory containing chain YAML files
PIPELINES_DIR ../pipelines Directory containing pipeline YAML files
WORKSPACE_DIR — Additional allowed directory for /download endpoint
Execution
CLAUDE_CLI claude Path to Claude CLI binary
CLAUDE_BIN claude Alternative Claude binary path (used by executor)
CLAUDE_TIMEOUT_MS 1800000 Default per-step timeout (30 min)
MAX_CONCURRENT_EXECUTIONS 5 Max simultaneous chain executions (queue worker pool size)
EXECUTION_MAX_AGE_DAYS 7 Auto-purge executions older than N days
Storage (SQLite)
OCC_DB <auto> SQLite database for executions + step checkpoints
OCC_QUEUE_DB <auto> SQLite database for the job queue
SCHEDULES_FILE <auto> Schedule persistence file path
External MCP
MCP_SERVERS_CONFIG <auto> Path to occ-mcp-servers.json (external MCP server config)
Display
NO_COLOR — Disable ANSI colors in Claude output

<auto> means OCC auto-resolves the path based on CHAINS_DIR (next to the chains directory). Override with an explicit path if needed.

.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