Directus: a SQL database wrapped in REST, GraphQL and a policy layer

What Directus does that a hand-written admin panel does not

The project describes itself as a collaborative backend: you connect an existing SQL database and get REST and GraphQL APIs, a visual Studio, and an MCP server for AI agents. The distinction that matters is direction. Most headless CMS products own the schema and generate the database; Directus reads a schema that already exists. If your tables are in Postgres, MySQL, MariaDB, MS SQL, SQLite, OracleDB or CockroachDB, the README states the APIs are generated from that schema with no configuration.

The audience is split. Engineers keep control of schema and access rules. Non-technical teammates get the Studio instead of filing tickets for content edits. The README also positions AI agents as a third kind of user, operating under the same role-based permissions as human accounts rather than a separate credential path. That last point is the design decision worth noting: agent access is not a bolt-on, it is the same policy system.

It is not a fit for every project. If you have no schema yet and want the tool to design one for you, the value proposition inverts. Directus is at its best when the database is the source of truth and the API layer is the thing you would otherwise write by hand.

How the API layer, Studio and MCP server fit together

The mechanism is a wrapper, not a migration. Directus sits in front of your database and derives endpoints from its structure. The README states that REST and GraphQL APIs are automatically generated from the database schema, and that permissions are policy-based and granular down to the field level.

That field-level granularity is what makes the MCP story coherent. The README says AI agents operate under the same role-based permissions as human users, and that the same access policies apply to AI. So an agent connected through the MCP server sees a filtered view of the data, not the raw tables. The Studio, the APIs and the agent all read through the same permission layer.

Two constraints follow from this architecture. First, schema changes are database changes; the API surface moves when the schema moves, which is a different operational rhythm from a CMS that versions its own content model. Second, the repository is a pnpm monorepo with separate top-level directories for api/, app/, sdk/ and packages/, so the API server, the Studio and the client SDK ship as distinct artifacts from one workspace. The root package.json sets engines to node 22 and pnpm between 10 and 11, and pins packageManager to [email protected]. Anyone building from source inherits those constraints.

Installing Directus locally with Docker

The repository ships a Dockerfile and a docker-compose.yml, but the compose file carries an explicit warning: it is meant to spin up database vendors, Redis, S3 and a fake SMTP server for debugging, and is not intended for production. The file points to the documentation for production compose examples. The runtime image sets DB_CLIENT to sqlite3 as a default, which is the quickest path to a running instance.

For a local trial, the documented route is the published image. The repository's compose file lists the ports and credentials for the vendors it starts, including Postgres on 5100 with the user postgres and password secret, MySQL on 5101, MariaDB on 5102, MS SQL on 5103, Oracle on 5104, Redis on 5105, RustFS on 5106 and CockroachDB on 5113. Those are throwaway values for local testing only.

To run the API directly against a database you already have, set DB_CLIENT to the matching vendor and supply the connection details for that vendor. The README does not document rollback for a failed migration, so treat schema changes as you would any other database change.

If you would rather not manage the database, storage and scaling yourself, the README points to Directus Cloud, which it says provisions a fully managed project in under 90 seconds, and to a one-click Railway deployment that comes provisioned with PostgreSQL, Redis and S3-compatible storage connected over Railway's private network.

The licensing boundary is the real adoption decision

Directus is not open source in the OSI sense. The README states it is licensed under the Monospace Sustainable Core License (MSCL) 1.0, described as a source-available license derived from the Fair Core License. The repository's license field on the hosting platform reads NOASSERTION, which is consistent with a custom license rather than a standard identifier.

The practical terms, as the README states them: organizations under $5M in annual revenue and 50 employees can use Directus for free under the Open Innovation Grant, and a key can be requested through a linked form. A free core tier exists for everyone to explore and build without a commercial license. Organizations above those thresholds using advanced or enterprise features require a commercial license.

Two things are worth separating. The revenue and headcount test is a licensing question, not a technical one, and it is the first thing a legal or finance reviewer will ask. The second is that "advanced or enterprise features" is not enumerated in the README, so which capabilities fall on which side of that line has to be checked against the pricing page before you build a dependency on a specific feature. This is not legal advice; the license text governs.

Upgrade cost is a separate axis. Releases are frequent and versioned, with v12.3.1 on 2026-08-25 following v12.3.0 on 2026-08-18 and v12.2.0 on 2026-07-29. The repository uses changesets for release management, visible as the .changeset directory at the top level. A steady minor cadence means you should expect to track release notes rather than pin once and forget. The last push to the default branch was on 2026-09-10.

Where Directus is the wrong tool

The most common mismatch is expecting Directus to own the content model. It does not. It reflects a schema you maintain. If your team wants to define collections in a UI and have the tool manage migrations for you, that expectation will collide with how Directus actually works, because the database is the source of truth.

A second limitation is the license itself. If your organization is above the $5M revenue or 50 employee thresholds and your use case touches features the README calls advanced or enterprise, you are in commercial territory. Teams that require a permissive OSI-approved license for procurement reasons will not clear that bar regardless of the technical fit.

Third, the AI and MCP features are new enough that the README describes them at a capability level rather than a specification level. It states that an AI Assistant is embedded in the Studio and that a native MCP server connects Claude, Cursor, ChatGPT or any MCP-compatible tool. It does not document the transport details, rate limits or failure modes in the README. If agent access is the reason you are evaluating Directus, budget time to read the AI and MCP documentation before assuming the integration shape.

Finally, the repository's own compose file is not a production artifact, and the file says so. Teams that copy it into production will be running debug credentials. The file explicitly redirects to the documentation's self-hosting deployment examples for production use.

Directus compared with Strapi on schema ownership

Strapi is the comparison people reach for, and the difference is architectural rather than feature-level. Strapi is a headless CMS that owns its content model: you define content types in the CMS, and it manages the underlying storage. Directus inverts that. The README's framing is "bring your own database" with APIs generated from the schema, so the database remains the artifact you version and migrate.

That inversion decides a lot. If your data already lives in a SQL database with business logic, reporting or other applications reading it, Directus layers on top without a data migration. If you are starting from nothing and want the CMS to define structure, Strapi's model is the more direct fit, because you are not maintaining a schema in two places.

The permission model differs in emphasis too. Directus describes policy-based access control down to the field level, applied to both human users and AI agents through the MCP server. Whether that granularity is meaningfully better for your case depends on how many distinct roles touch the data. For a single-editor blog, it is overhead. For a system where a support agent, a marketing contractor and an AI assistant all need different slices of the same tables, it is the reason to pick Directus.

Who should adopt Directus, and what to check first

Adopt it if you have a working SQL database and a recurring need for an admin interface, generated APIs and role-scoped access, and you would rather not write and maintain that layer yourself. The self-hosted path is documented, the Dockerfile builds a production image, and the debugging compose file gives you real database vendors to test against locally.

Do not adopt it if you need an OSI-approved license, if you are above the Open Innovation Grant thresholds and your feature set requires a commercial license you have not budgeted for, or if you want the CMS to own and migrate the schema on your behalf.

Before you commit, verify three concrete things. Check whether your organization qualifies under the $5M revenue and 50 employee thresholds in the README, since that determines whether you need a key at all. Confirm which database vendor you will run in production, because the supported list is broad but the debugging compose ports and credentials are not production values. And if AI agent access is part of the plan, read the AI and MCP documentation first: the README states the capability but not the integration contract.

Editorial conclusion

Adopt Directus if your schema already lives in Postgres, MySQL, SQLite or another supported database and you want generated APIs plus a Studio without copying data into a proprietary store. Skip it if you need a permissive OSI license, or if you want the CMS to own the schema rather than the other way around. Before committing, verify three things: whether your organization falls under the Open Innovation Grant thresholds, which database vendor you will run in production, and whether the AI and MCP features you plan to use are in the free tier or behind a commercial license.

Frequently asked questions

Official sources

1. directus/directus on GitHub
2. Issues
3. Project website
4. README
5. Releases