Skip to content

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 with generated secrets
  • Initializes shared infrastructure (Docker network, PostgreSQL, team directories)

The config is created at /etc/oduflow/oduflow.toml when that directory is writable, otherwise at ~/.oduflow/conf/oduflow.toml. Oduflow searches for the config in this order:

  1. ODUFLOW_TOML environment variable (explicit file path)
  2. /etc/oduflow/oduflow.toml
  3. ~/.oduflow/conf/oduflow.toml

Fresh configs include generated values for:

  • [database].password — PostgreSQL superuser password
  • [team.1].auth_token — HTTP MCP Bearer token and OAuth client secret
  • [team.1].ui_password — Web Dashboard password

The config file is created with mode 0600. The generated secrets are never printed to the log — read them from the file itself:

sudo grep -E 'auth_token|ui_password' /etc/oduflow/oduflow.toml 2>/dev/null \
  || grep -E 'auth_token|ui_password' ~/.oduflow/conf/oduflow.toml

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
uvx oduflow -t http
# or, if installed:
oduflow --transport http
oduflow -t 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

Fresh HTTP installs already have a generated Bearer token for MCP and a separate generated password for the Web Dashboard. Read them from oduflow.toml:

[team.1]
hostname = "localhost"
auth_token = "..."     # Bearer token for MCP clients
ui_password = "..."    # Web Dashboard login password

To sign in to the Web Dashboard, open http://<host>:8000/, use username admin, and enter the ui_password value. To connect an HTTP MCP client, use http://<host>:8000/mcp with:

Authorization: Bearer <auth_token>

MCP auth and Web Dashboard auth are independent — they use different credentials and different mechanisms (Bearer vs form/session auth).

Self-hosted OAuth (Claude.ai)

Some MCP clients (e.g. Claude.ai Remote MCP) require an OAuth flow instead of a static Bearer token. Oduflow can act as its own OAuth 2.1 Authorization Server — no external identity provider needed. It is enabled automatically whenever a team has an auth_token and runs on that team's own hostname in both port and traefik mode, so no separate OAuth URL is normally required:

[team.1]
hostname = "oduflow.example.com"
auth_token = "..."

Behind Cloudflare Tunnel, publish that same hostname and forward it to port 8000; use split DNS if LAN clients should reach it directly. The OAuth client_id is the non-secret team_<id> (e.g. team_1); each team's auth_token is the client_secret, and OAuth mints an independent expiring access token. See Authentication & Security for the full setup and how to connect from Claude.ai.

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"
      }
    }
  }
}

Claude Desktop (remote server via mcp-remote)

Claude Desktop only launches MCP servers as local processes — it cannot call a remote HTTP endpoint with a custom Authorization header on its own. Use the mcp-remote bridge: Claude Desktop starts it over stdio, and it forwards everything to Oduflow's /mcp endpoint with the Bearer token attached. Node.js (which provides npx) must be installed.

Edit claude_desktop_config.json — Settings → Developer → Edit Config opens it directly:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "oduflow": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://your.oduflow.server/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--transport",
        "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "oduflow": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your.oduflow.server/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--transport",
        "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer TOKEN"
      }
    }
  }
}

Replace:

  • https://your.oduflow.server/mcp — your Oduflow MCP endpoint (in traefik mode, the team's own hostname; in port mode, http://<host>:8000/mcp).
  • TOKEN — the team's auth_token from oduflow.toml. Keep the Bearer prefix: the header value must read Bearer <auth_token>.

Why the token lives in env

mcp-remote substitutes ${AUTH_HEADER} into the --header value at startup. Keeping the secret in env instead of inline in args avoids both the shell-quoting problems of a space inside an argument and leaking the token into process listings and logs.

--transport http-only pins the bridge to Streamable HTTP, which is what Oduflow serves; without it mcp-remote first probes for an SSE endpoint and the connection can fail. Do not use the OAuth setup from Authentication & Security here — that flow is for Claude.ai custom connectors; Claude Desktop authenticates with the static Bearer token above.

To scope the connection to a single environment, point the URL at https://your.oduflow.server/mcp/<env> and use that environment's Secret Key as the token instead — see Scoped single-environment access.

After saving the file, quit Claude Desktop completely (not just close the window) and start it again. The Oduflow tools then appear in the tools menu.

Web Dashboard

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

Next steps