Quick Start

Install

The fastest way — run directly without installing (requires uv):

uvx oduflow

Or install permanently:

uv tool install oduflow

On first launch, Oduflow automatically:

  • Creates a default oduflow.toml config (in /etc/oduflow/ or ~/.oduflow/conf/)
  • Initializes shared infrastructure (Docker network, PostgreSQL, team directories)

Single-user mode (stdio)

Stdio is the default transport — Oduflow communicates with the MCP client over stdin/stdout. The client starts and manages the Oduflow process directly. No network port is needed.

# These are all equivalent:
uvx oduflow
oduflow
oduflow --transport stdio

Add to your MCP client config (Claude Desktop, Windsurf, etc.):

{
  "mcpServers": {
    "oduflow": {
      "command": "uvx",
      "args": ["oduflow"]
    }
  }
}

If Oduflow is installed globally (uv tool install oduflow), you can use the shorter form:

{
  "mcpServers": {
    "oduflow": {
      "command": "oduflow"
    }
  }
}

Server mode (HTTP)

HTTP transport starts a persistent server with Streamable HTTP, a Web Dashboard, and a REST API. Suitable for remote and multi-user deployments.

# Start the HTTP server:
uvx oduflow --transport http
# or, if installed:
oduflow --transport http

The server starts on http://0.0.0.0:8000 by default (configurable via [server] section in oduflow.toml). The MCP endpoint is at /mcp.

Authentication

In HTTP mode it is recommended to set a Bearer token for MCP and a password for the Web Dashboard. Add to your oduflow.toml:

[team.1]
hostname = "localhost"
auth_token = "my-secret-mcp-token"      # Bearer token for MCP clients
ui_password = "my-dashboard-password"    # Basic auth for Web Dashboard (user: admin)

MCP auth and Web Dashboard auth are independent — they use different tokens and different mechanisms (Bearer vs Basic).

MCP client configuration

Point your MCP client (Cursor, Cline, Amp, etc.) to the server with the Authorization header:

{
  "mcpServers": {
    "oduflow": {
      "type": "http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-mcp-token"
      }
    }
  }
}

If the server is behind a reverse proxy with HTTPS (see Traefik Routing):

{
  "mcpServers": {
    "oduflow": {
      "type": "http",
      "url": "https://oduflow.example.com/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-mcp-token"
      }
    }
  }
}

Web Dashboard

When running in HTTP mode, a web dashboard is available at the root URL (http://your-server:8000/). It provides environment management, service controls, a WebSocket terminal, and more. See Web Dashboard & REST API for details.

Next steps