Loonflow 3.2: A Django Workflow Engine With an MCP Ticket Server

The problem Loonflow targets: approval flows that outgrow a ticket table

Most teams start with a ticket table and a status column. That works until the second department wants its own approval chain, until a branch depends on a form field, or until someone asks who approved what and when. Loonflow is aimed at that point. The README describes it as an enterprise-grade unified workflow solution and lists IT operations, HR approvals, financial reimbursements and customer service as the process types it is meant to carry. The audience is the internal platform team that has already been asked to build a second and third approval flow and does not want to write a fourth one from scratch. It is not a general-purpose BPMN engine for modelling arbitrary business processes. The feature list is organised around tickets: creation, routing, assignment, handling, closure, and an audit log covering each step. If your process does not end in a ticket that a named person handles, the fit is weaker than the marketing suggests.

How the engine is put together: Django services, a React designer, and permission-aware tools

The stack is stated plainly in the badges: Python 3.12, Django 5.2, React 18.x, MUI 5.x. The repository's primary language is listed as TypeScript, which is consistent with a React front end sitting on top of a Python back end rather than a Node service. Two design surfaces are described. The process designer is drag-and-drop, and the README says it supports conditional branches, parallel tasks and hooks. The form designer provides field types including text, numbers, dropdowns, personnel selection and attachments. Process logic validation runs during design, and multiple versions of a process can be configured and switched, which is the mechanism that lets you test a change without disturbing the running definition. The extension story is a plugin architecture covering what the README calls almost all key nodes: custom actions, permission validation, notification methods. The permission model is described as fine-grained, based on roles, departments or business conditions. The MCP server is the piece worth reading closely. The advertised server name is loonflow-ticket, and the README states that its tools use the same permission-aware ticket services as the web UI. That is the architectural claim that matters: the AI-facing surface is not a separate code path with its own access rules, it is the same ticket service behind a different transport.

Getting it running: two wget commands, one .env, one compose up

The documented self-hosted path is four steps. First, download the compose file and the environment file from the docker_compose_deploy directory on master. Second, edit .env, where the README says to modify at least the password section. Third, run docker-compose up -d from the directory containing the compose file. Fourth, log in with the email and password you set in .env. That is the whole documented install. There is no build step described, no migration command, and no separate front-end build, which implies the compose file handles both. The README does not state which services the compose file starts or which ports it exposes, so if you need to place this behind an existing reverse proxy you will be reading the compose file itself rather than the README. For the MCP server, the SaaS endpoint is given as https://mcp.loonflow.com/mcp. Self-hosted, the README says the MCP process serves Streamable HTTP on path /mcp by default, with host, port and transport adjustable through environment variables described in the documentation rather than in the README. Authentication is either a personal access token, recommended, whose values start with lfpat., or a JWT issued by Loonflow. The token is created under Personal Information, then Personal Access Token in the product UI. Registered tools are ticket_list, ticket_detail, ticket_prepare_handle, ticket_handle and user_list. ticket_handle supports a dry_run parameter for validation, and user_list is a paginated user search scoped to the authenticated tenant.

Where the documentation stops and you start guessing

The README is a landing page, not an operations manual, and the gaps are in the places that cost time. It does not say what the compose file contains, which ports are published, or how the database is provisioned. It does not list the environment variables that control the MCP host, port and transport; it points at the documentation instead. The MCP section names the tools and their parameters only in passing, and defers JSON client examples and supported parameters to the Read the Docs page. The plugin architecture is described in one sentence and one guide reference, with no list of hook points in the README. The multi-tenant feature is marked optional and requires additional authorization, without saying what that authorization is or how it is obtained. None of this is unusual for a project that keeps its real documentation on Read the Docs, and the README does link there. But it means the README alone is not enough to plan a deployment. If you are evaluating this for a regulated environment, the audit log claim and the permission model claim both need to be checked against the actual documentation and the UI, because the README asserts them without describing the mechanism.

The AGPL-3.0 boundary and the commercial edition beside it

Loonflow is licensed AGPL-3.0. That licence reaches network use: if you run a modified Loonflow and let users interact with it over a network, the AGPL's source-availability obligation is generally understood to apply to your modified version. This is the single most consequential fact for anyone considering embedding Loonflow in a product. If your plan is to take the engine, extend it with proprietary hooks, and offer it as part of a hosted service without publishing your changes, the AGPL is the wrong licence for that plan. The README also advertises a managed SaaS edition at loonflow.com with a two-week free trial and no self-hosting, and offers commercial support and customization by email. That combination, an AGPL core plus a hosted edition plus paid customization, is the standard shape for this kind of project, and it means the licence question and the support question have the same answer: if the AGPL does not fit, the commercial route is the intended alternative. None of this is legal advice; the plugin boundary in particular is worth a lawyer's read before you ship.

What Loonflow does not do, and what to use instead

The clearest limitation is scope. Loonflow is a ticket and approval engine. It is not a general workflow orchestrator for infrastructure tasks, and it is not a BPMN modelling tool with the full notation set. The README's node list is conditional branches, parallel tasks and hooks, which is a practical subset rather than a complete standard. If your requirement is to model a process that a business analyst drew in BPMN, or to orchestrate long-running jobs across services with retries and compensation, Loonflow is the wrong tool and you will fight the ticket-centric data model. For that class of problem, a BPMN engine such as Camunda or Flowable is the more natural fit: those projects model processes as BPMN 2.0 XML with an explicit execution semantics, gateways and boundary events defined by the standard, and they are designed to be embedded in a Java application rather than reached through a ticket API. The difference in approach is not cosmetic. Loonflow's unit of work is a ticket with an assignee and an audit trail, and its designer is a UI that produces a process definition. A BPMN engine's unit of work is a process instance, and its definition is a portable XML document that other BPMN tools can read. If portability of the process definition between tools matters to you, Loonflow's visual designer is a liability rather than a feature. If what you actually need is an approval queue with forms, routing and a clean audit log, the BPMN engines will feel like a large amount of machinery for a small job.

The MCP surface is the differentiator, and the least proven part

The MCP ticket server is what separates Loonflow from a decade of Django approval tools. The design choice worth noting is that the MCP tools reuse the same permission-aware ticket services as the web UI, so a personal access token should not grant more than the user who created it. That is the right decision, and it is also the claim you should test before trusting it. The README names five tools, and the presence of dry_run on ticket_handle suggests the authors expect agents to attempt writes and want a validation path. The token prefix lfpat. makes leaked tokens greppable, which is a small but real operational convenience. Against that, the MCP documentation lives off-repo, the transport environment variables are not in the README, and there is no statement about token expiry, rotation or revocation. If you are putting an AI client in front of a system that can prepare and handle tickets, those are the questions to answer first, and the README does not answer them.

Maintenance cost: three releases in three weeks, and a version you must track

The release cadence visible in the material is r3.2.0 on 2026-05-04, r3.2.1 on 2026-05-13, and r3.2.2 on 2026-05-25. Three patch releases inside a month on a 3.2 line means you should plan to track versions rather than pin once and forget. The README's multi-version process configuration helps here: you can keep a running process definition and a test definition side by side, which is the mechanism that makes an upgrade less frightening. The upgrade procedure itself is not documented in the README. With a Docker Compose deployment, the practical question is whether a new image tag requires a database migration and whether the compose file changes between releases, and neither is stated. Budget for reading the compose file and the release notes on each bump rather than assuming docker-compose pull is sufficient. The plugin layer adds a second maintenance surface: any custom action, permission check or notification method you write against a hook point is code you own, and the README gives no compatibility statement about hook stability across minor versions. Treat the hooks as an internal API and keep your plugin code in a separate repository so an upstream change is visible in a diff.

Editorial conclusion

Adopt Loonflow if you need a self-hosted Django workflow engine with a visual designer and you are prepared to read the Hook Development Guide before your first custom node, because the plugin surface is where your business logic will actually live. Do not adopt it if you need a permissively licensed engine you can embed in a closed product, or if you cannot accept that multi-tenant data isolation is gated behind additional authorization. Verify three things first: that the .env values you set produce a working login, that a personal access token beginning with lfpat. can reach the /mcp endpoint on your own host, and that the plugin hook points you need are documented for your version rather than inferred from the demo video.

Official sources

1. blackholll/loonflow on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases