Grav 2: the flat-file CMS that offers AI agents Markdown and MCP

Grav 2 checked at the source: history, the new stack, Markdown for agents, the MCP server and where the marketing promises more than the code.

by ·

I'm a big fan of Grav. The CMS stores everything as files, content in Markdown, settings in YAML (an easy-to-read text format for configuration), and needs no database server for it. I run a knowledge base on Grav myself, served through FrankenPHP. What the Caddy configuration for that looks like is in the article on FrankenPHP and Caddy. With version 2, Grav now advertises itself as ready for AI and MCP (Model Context Protocol, a standard through which AI assistants call tools), and that's exactly the direction I find exciting. It's the reason for this article.

For me, being a fan doesn't mean copying the marketing. For this article, the docs, changelogs, the source code of the MCP server and the security advisories were evaluated, and in a few places the website promises more than the code delivers. That's discussed openly here. If you don't know Grav yet: every section starts simple and then goes deeper.

The short version

Question Answer
What is Grav? A flat-file CMS in PHP: pages are folders with a Markdown file, configuration is YAML, templates are Twig, and no database server is needed
What's new in Grav 2? A new stack (PHP 8.3+, Twig 3, Symfony 7.4), a new admin as an app on top of a REST API and a sandbox for Twig in page content
What does "AI ready" mean? Since 2.1.0, every page delivers Markdown instead of HTML on request, on by default. On top of that comes an API through which agents work with real user permissions
Is the MCP server built in? No. The official server is the separate npm package grav-mcp 0.1.5 for Node.js, according to the docs "not a Grav plugin". An MCP endpoint directly in the site so far only comes as a plugin by an outside author
What permissions does an agent have? Those of the Grav user who owns its API key. That's a real advantage over solutions with fixed super-admin rights
What about security? 219 advisories (security notices) in the Grav repository, 184 of them from 2026. Fixes come quickly, but you have to update just as quickly
Can I simply upgrade from 1.7? No. Grav 2 comes as a fresh installation next to the old site, and a migration plugin helps with the move

I wrote this article as of 12 November 2026. On 20 November I brought it up to Grav 2.2.31, the API plugin 1.1.22, grav-mcp 0.1.5 and the mcp-server plugin 1.11.3 by Sandy McArthur; what has changed since is in the update of 20 November. The stack table, the default values and the download package still refer to Grav 2.2.29; according to a comparison of the two versions, dependencies and default values are unchanged up to 2.2.31. "According to the docs" and "according to the source" mean read there. I didn't put the agent features into operation for this article; what's said about them here comes from docs, changelogs and code. Performance figures come from the vendor and appear with their test conditions.

Update of 20 November

Since the reference date, Grav 2.2.30 and 2.2.31 have come out, mostly with bug fixes, along with 1.7.53.11. According to a comparison, dependencies, default values and the Markdown output are unchanged, and so are grav-mcp, the MCP docs and the claims on the website. What's new are security fixes in two releases exactly where agents connect:

  • API plugin 1.1.21 closes GHSA-fqv4-9pm4-v2q2 (opens in a new tab) from 19 November, rated critical. Up to 1.1.20, anyone could trigger a genuine password reset email via POST /api/v1/auth/forgot-password without logging in, and its link sent the token to a host controlled by the attacker. Anyone who knew an account's email address, including a super-admin's, could take the account over this way as soon as the victim clicked the link in the genuine email. According to the advisory, the flaw gets past a check that had been added after CVE-2026-61839. The current version is 1.1.22.
  • mcp-server 1.11.3 from 12 November closes two flaws in the plugin's OAuth code, according to the release notes (opens in a new tab): through the redirect URI check, authorization codes could reach hosts outside the allowed list, and refused registrations could anonymously write any text into grav.log, which the get_logs tool hands to AI clients. Connectors registered before 1.11.3 may get an error page. In that case, remove them and add them again.

I've updated figures and versions in the text and added the new security fixes where they belong; the agent setup now lists minimum versions.

What Grav is

A classic CMS like WordPress stores content in a database. Every page is built by PHP fetching data from MySQL and filling it into a template. Grav leaves the database out. Every page is a folder under user/pages/ containing a Markdown file with a YAML header (frontmatter, meaning the metadata such as title and date at the top of the file). The configuration lives in YAML files under user/config/. The name of the Markdown file selects the template: default.md becomes default.html.twig. Twig is a widely used template language from the world of the PHP framework Symfony.

The README (opens in a new tab) describes Grav as a "file-based Web-platform" with no installation: "Just extract the ZIP archive, and you are already up and running." For me, the real appeal lies elsewhere. Because everything is a file, you can version your site with Git, back it up with rsync and edit it in any editor, with no export and no database dump.

Multilingual content works through files as well. According to the docs (opens in a new tab), default.de.md and default.en.md sit in the same folder, with a fallback to default.md. For everyday work there are three command-line tools: bin/grav for cache, backups and the scheduler, bin/gpm for plugins and themes, and bin/plugin for commands that plugins bring along. The most important commands are in the Grav cheat sheet.

Under the hood

Flat-file doesn't mean static. Grav renders every page with PHP, and the speed comes from several cache layers: compiled YAML configuration, page cache, Twig cache and image cache. With Grav 2, the project replaced almost the entire foundation. The table compares the composer.json (the dependency list for Composer, PHP's package manager) of 1.7.53.10 (opens in a new tab) with that of 2.2.29 (opens in a new tab) and its lockfile (opens in a new tab), which records the exact installed versions:

Component Grav 1.7 Grav 2.2.29
PHP 7.3.6 or later 8.3 or later
Twig 1.44 3.x, own fork
Symfony 4.4 7.4
Monolog 1.25 3.12
Cache Doctrine Cache Symfony Cache
Markdown Parsedown 1.7 Parsedown 2.0.2, plus league/html-to-markdown

A detail for experts: in the lockfile, Twig appears as 3.x-dev from the getgrav/Twig repository, a fork (a separate copy of the project), and the developer guide calls it "forked for Defer". So a stable release depends on a development branch of its own fork. According to the lockfile, Parsedown 2.0.2 and Parsedown Extra also come from Grav forks (getgrav/parsedown, getgrav/parsedown-extra). That's not a mistake, but you should know it if you write Twig extensions.

On the PHP minimum, code and docs contradict each other slightly. According to defines.php, the code checks for 8.3.0, while the requirements (opens in a new tab) say "PHP 8.3.11 or higher". I'd go with the docs, especially since only a current PHP makes sense anyway. The features page (opens in a new tab) lists PHP 8.3, 8.4 and 8.5 as supported.

Twelve years in brief

Grav appeared in the summer of 2014. The GitHub repository was created on 2 August 2014, the changelog (opens in a new tab) lists version 0.8.0 from 13 August as the "Initial Release", while Wikipedia (opens in a new tab) gives 30 July. The GPM package manager arrived as early as 0.9.3 in October 2014. Grav 1.0 followed on 11 December 2015, 1.6 brought the first entries for the Flex API in April 2019 (a layer for structured data objects such as users or custom data types), and 1.7 came out on 19 January 2021.

The timeline on the about page (opens in a new tab) differs from that. It gives "Sep 2015" for 1.0, 2016 for GPM and 2018 for Flex Objects, while the changelog entries say something else. For dates, I'd therefore stick to the changelog.

After that, things took a long time. Grav 1.8 went into beta on 23 October 2024 and never reached a stable release in thirty betas. On 16 April 2026 the changelog notes: "Rebranded 1.8-beta as 2.0-beta." According to the release blog post (opens in a new tab), the upgrade approach was the main problem, that is, the attempt to lay everything over an existing installation as an update. Grav 2.0.0 came out on 20 June 2026, and the GitHub release is dated the 21st. After that, things moved fast. According to the changelog, 2.1.0 came out on 11 September, 2.2.0 on 24 September and 2.2.29 on 10 November 2026, with the GitHub release dated the 11th. Up to 2.2.31 from 18 November, the changelog lists 72 stable releases since 2.0.0 in 151 days, so on average about one every two days.

Who's behind it

The founder and lead is Andy Miller. The about page says Grav is "designed, built, and maintained by Andy". In the comparison with WordPress (opens in a new tab) he writes about himself: "I co-founded Joomla, I created Grav". Wikipedia also names Djamil Legato and Matias Griese as developers; what role the two play today, I haven't established. The company behind Grav is Trilby Media, founded by the core team according to a 2016 review (opens in a new tab) to offer professional services around Grav. The core is MIT-licensed, and it's funded through Open Collective with Adyen as platinum sponsor, through premium plugins and through services. There's no documented governance model and no foundation. The SECURITY.md (opens in a new tab) says it itself: "Grav is maintained by a very small team."

In my view, that's both a strength and a risk. A small team decides quickly and holds its course, and the pace since 2.0 shows it. But a lot also depends on a few people. The GitHub repository has around 15,700 stars, and Grav won several CMS Critic Awards between 2016 and 2021.

What changes with Grav 2

If you're coming from 1.7, you won't see the biggest differences in the frontend, but in administration and templates. According to the migration overview (opens in a new tab), your page content keeps working without conversion. Everything around it is new.

The classic admin is gone. According to the developer guide (opens in a new tab), it was "removed from Grav 2.0 entirely". Its place is taken by Admin 2, also called "Admin Next". The Admin 2 README (opens in a new tab) describes it as a "SvelteKit single-page application that communicates with Grav exclusively through the Grav API plugin". A single-page application is an app in the browser that fetches its data only through interfaces. For plugin developers this means: the onAdmin* events (points where plugins hook into the process) become onApi*, and your own extensions for the old admin have to be rewritten.

Twig in page content runs in a sandbox with an allowlist. A sandbox is a sealed-off area, an allowlist the list of functions explicitly permitted inside it. Since 2.0.19 it's switched on by default for new installations (security.twig_content.process_enabled: true), and you can turn it off site-wide with that switch. The migration overview still says it no longer runs by default, which according to the changelog is out of date. The undefined_functions option has been removed, and PHP functions for templates are now only available as an opt-in (only if you explicitly enable them) through safe_functions. For old templates there's the twig3_compat switch, which is on in 2.2.29 and rewrites old Twig 1 syntax. The developer guide still advises: "update templates permanently rather than rely on the transforms". I'd give you the same advice: a compatibility switch is a bridge, not a permanent fix.

Markdown now follows GitHub. GitHub Flavored Markdown is the standard, and the old Markdown Notices become GitHub Alerts, the callout boxes with > [!NOTE].

Migration instead of upgrade

This is the point you should know before any switch. The developer guide is clear: "Grav 2.0 is not delivered as an in-place upgrade." Instead there's the "Migrate to Grav 2.0" plugin. According to the docs, it puts a fresh Grav 2 installation into a subfolder next to your site, copies the user/ folder into it, checks your plugins for compatibility and lets you test the new version under /grav-2/. Then you choose "Promote", and it backs up the old version as a ZIP and swaps them, or "Reset", and everything stays as it was. According to the docs, the path is tested with Apache; for nginx and Caddy you have to adapt the rules yourself.

I like the approach. Your live site stays reachable until you switch over, and while you're testing, a failure only costs you a subfolder. During "Promote" itself, however, the wizard deletes the files in the web root and moves the new version up. If that breaks off halfway, according to the README (opens in a new tab) the live site is partly gone and the backup ZIP is your rescue. The compatibility check, though, relies on information that many plugins don't provide; more on that in the section on the ecosystem.

On the 1.7 line, the docs contradict themselves. The migration overview calls 1.7.51 "the final stable release in the 1.7 series", but in fact 1.7.52, 1.7.53 and four-part patch releases up to 1.7.53.11 from 18 November 2026 followed. According to the blog (opens in a new tab), 1.7 only gets critical security fixes from now on, and the SECURITY.md is even narrower: only what can be exploited without a publisher or admin account gets backported. I'd therefore treat 1.7 as being phased out, even if there's no fixed deadline. In practice, though, the project goes further: 1.7.53.11 also brings the fix for GHSA-qgmc-p8w7-7x5p (opens in a new tab), rated high, which requires an admin account with the admin.users permission.

Speed with version 2.2

According to the release notes (opens in a new tab), Grav 2.2 was a performance release. The most important change for large sites concerns lazy_index, available as an opt-in since 2.0.7 and set to auto by default since 2.2.0. Instead of loading all pages, routes and taxonomies (groupings such as categories and tags) as one big cache block, Grav reads them on demand from a per-page index. The comment in system.yaml names "SQLite/YetiSQL" for this and says the auto mode switches on from 1,000 pages. Without the pdo_sqlite PHP extension, according to composer.json, the pure-PHP engine YetiSQL from the database-yetisql plugin steps in. So since 2.2 at the latest, "no database" more precisely means: no database server. If no database engine is available, Grav falls back to the old cache block, according to the same comment.

# user/config/system.yaml (defaults as shipped in 2.2.29)
pages:
  lazy_index: auto   # true, false, or auto (on from 1,000 pages)
session:
  lazy: false        # opt-in: no session cookie for anonymous page views

The second new feature is session.lazy. With it, Grav sets no session cookie for anonymous page views, and a proxy or CDN (a network of servers that caches and delivers pages) can cache the responses. The switch is an opt-in, and the comments warn that plugins writing directly to $_SESSION can lose data with it. So I'd test that before switching it on.

The blog post on 2.2 (opens in a new tab) shows the vendor's measurements: the first uncached request (cold start) on a test site with 1,081 pages dropped from 1,047 to 526 ms (median time to first byte, home page, first request after clearing the cache, compared with 2.1.10), with 10,321 pages from 4,633 to 2,326 ms, and the memory use of the large site from 241.8 to 9.6 MB. It was measured on an Apple M4 Max with PHP 8.3, OPcache and Apache, using curl on the same machine, so without network time. The large site was the same site with its 770-page docs section copied twelve times, in the author's words "a size test, not a real 10,000-page site". The improvement is clear. The "Sub-100ms page loads" on the features page, however, apply to a warm cache; after a cache rebuild, a large site still takes seconds.

"AI and MCP ready": what's behind it

Grav 2 promises three things for AI: content in a form agents can read well, an interface through which they're allowed to write, and an MCP server to go with it. MCP, the Model Context Protocol, is an open standard through which AI assistants such as Claude Code or Cursor call tools of external systems. An MCP server describes these tools, and the assistant decides when to use them. The three promises are at different stages, so I'll take them one at a time.

Markdown for agents, right in the core

For me this is the strongest piece, and it feels very familiar. Since Grav 2.1.0 (opens in a new tab), every page delivers Markdown instead of HTML on request: "Add .md to any page URL, or send an Accept: text/markdown request header". The response contains the rendered main content, a YAML header with title, URL, date, description and taxonomy, and at the end links to parent, sibling and child pages, again as .md URLs. On top of that come a <link rel="alternate" type="text/markdown"> in the HTML, a Vary: Accept and an X-Markdown-Tokens header with an estimate of the token count, according to the release notes "matching Cloudflare's Markdown for Agents". It's switched on by default.

# Per the 2.1.0 release notes, both requests return the page as Markdown
curl https://example.com/blog/my-post.md
curl -H "Accept: text/markdown" https://example.com/blog/my-post

This knowledge base uses almost the same pattern, just by a different route. Here the Markdown twins are created at build time, as described in Why 11ty, and Apache negotiates via Accept: text/markdown (there's an example in the article Redesign by AI). With Grav, PHP renders the Markdown at runtime. The blog post on 2.1 (opens in a new tab) sums up the advantage well: "Grav doesn't have to guess. It wrote the page." A CMS that builds its pages from Markdown doesn't have to translate the HTML back first.

If you want to fine-tune it, according to system.yaml you'll find the switches under pages.markdown_output, such as frontmatter, links, max_links, absolute_urls and token_header. Custom templates are possible with files like default.md.twig. What belongs in that kind of Markdown so AI systems can make good use of it, I describe in Writing for AI.

The llms.txt, an index file for language models, on the other hand isn't part of the core. According to the 2.1 announcement (opens in a new tab), it comes through the sitemap plugin 5.3.0, where an llms-full.txt with all content is optional and off by default.

The API as a shared foundation

The second promise is an interface for writing. For that, Grav 2 ships the API plugin, a REST API (a programming interface that works over ordinary HTTP requests) under /api/v1. Admin 2 talks exclusively to it, and agents do too. The MCP docs (opens in a new tab) put it this way: "Admin2 is the client for humans, the MCP server is the client for AI, and both go through the same API." I find that the cleanest idea in Grav 2's entire AI package. There's no special path for agents, just the same interface with the same checks.

An agent authenticates with an API key in the X-API-Key header. The key belongs to a Grav user and inherits that user's permissions. The MCP docs say: "A key can never exceed the permissions of the user it belongs to, so the user account is your security boundary." According to the API plugin (opens in a new tab), the permissions are finely divided, for example api.pages.read and api.pages.write, api.media, api.config, api.users, api.gpm and api.system.backup. Backups have their own permission because they contain password hashes and secrets. Every call additionally needs the base permission api.access. Super-admin rights in the API run through api.super. The README still claims that a classic admin.super bypasses all permission checks. According to the source, though, the super-admin shortcut only applies to api.super, and together with api.access, admin.super merely opens the endpoints that require super rights.

One detail matters for everyday work with agents: writes use ETag and If-Match, so the agent sends along the version tag of the page it last read. If a human has changed a page in the meantime, the agent gets a 409 Conflict instead of silently overwriting the change, and conversely Admin 2 reports "Page was modified elsewhere". On top of that come HMAC-signed webhooks (notifications to other systems whose authenticity a signature proves) and per-user rate limits (caps on the number of requests).

There's a contradiction around key scopes, meaning restrictions that narrow a key below its user's permissions. The MCP docs still say: "Per-key permission scoping is not yet enforced independently of the user." According to the advisory for CVE-2026-62667 (opens in a new tab), however, scopes have been enforced since API 1.0.6, and according to the changelog several more security fixes followed on exactly that from 1.0.13 onwards. I consider that passage in the docs out of date. According to the source, the CLI command keys:generate has no option for scopes. Restricted keys come from Admin 2 or from the consent dialog of the mcp-server plugin (see below).

The official MCP server: grav-mcp

The third promise is the MCP server. The features page says: "Built-in Model Context Protocol server exposes the Grav API to agentic AI." It isn't built in. The official server is the npm package grav-mcp, according to the MCP docs explicitly "not a Grav plugin: it runs inside your AI client". You need Node.js 18 or newer on the machine your AI client runs on, and from there the server talks over HTTP to your site's API plugin. The Grav 2.2.29 download package with Admin 2 contains no MCP server; it includes the plugins admin2, api, email, error, flex-objects, form, github-markdown-alerts, login, problems and shortcode-core, plus the Quark 2 theme.

According to the docs, setup is short. First you create a key on the site:

# As in the docs; use a dedicated least-privilege user instead of admin (key shown only once)
bin/plugin api keys:generate --user=admin --name="Claude MCP"

Then you add the server to your client, with URL and key as environment variables:

json
{
  "mcpServers": {
    "grav": {
      "command": "npx",
      "args": ["-y", "grav-mcp"],
      "env": {
        "GRAV_API_URL": "https://my-site.example/api",
        "GRAV_API_KEY": "grav_..."
      }
    }
  }
}

The example uses --user=admin because that's how the docs show it. Right after that, the same docs advise: "Create a dedicated, least-privilege user for AI access rather than reusing your primary admin account." That's exactly what I'd do too.

According to the docs, the server offers "70 semantic tools across 11 domains". The 0.1.5 source contains 70 tools plus refresh_plugin_tools, spread across pages, multilingual content, media, configuration, users, package management, system, dashboard, webhooks, blueprints and plugin tools. On top of that come five resources and six ready-made prompts such as create_blog_post and site_health_check. The tools reach far: under package management you'll find install_package, update_all_packages and upgrade_grav. Only seven tools carry the destructiveHint annotation in the code, which a client can use to warn before risky actions. upgrade_grav, update_all_packages and update_config aren't among them. So I wouldn't rely on warnings from the client, but on the user's permissions.

Interesting for plugin developers: since grav-mcp 0.1.2, a plugin can describe its API routes in an mcp.yaml file. The API plugin delivers the list filtered by the caller's permissions, and grav-mcp turns it into tools named <plugin>_<name>. The first plugin to use this is the KahunaCart shop. I find the declarative approach elegant, because it means a plugin needs no MCP code of its own.

The version number is part of the maturity picture. grav-mcp is at 0.1.5 from 4 November 2026; according to npm, the first version appeared on 5 July, so after the announcement post (opens in a new tab) from 31 May. The server knows two transports: stdio, where the client starts the server as a local process, and HTTP on port 3100. According to the source, HTTP mode binds without a host setting and without its own authentication, and the API key applies to the whole process. So anyone who can reach the port acts with that key's permissions. I've only read that, not tested it, and I'm not claiming a vulnerability with it. Before 0.1.5, HTTP mode also broke on the second request; that was only fixed in 0.1.5. A plan by Andy Miller in the repository from July, status "Proposed, not started", lists further open items and a future native MCP endpoint in the API plugin. I'd therefore only use grav-mcp via stdio on my own machine and not expose HTTP mode openly to the network.

The in-site alternative: the mcp-server plugin

Hosted assistants such as claude.ai or ChatGPT can't start a local process; they need an MCP endpoint on the network. That's the route taken by the mcp-server (opens in a new tab) plugin by Sandy McArthur, installable with bin/gpm install mcp-server, currently 1.11.3 from 12 November 2026, MIT-licensed. It runs as a real Grav plugin and provides the endpoint under /mcp. According to the README, it brings an OAuth 2.1 server (OAuth is a standard for login and access authorisation) with dynamic client registration, as hosted connectors expect, and a consent dialog in which you can deselect individual permissions before the key is created. It requires Grav 2.1.5 and API plugin 1.1.12 or newer. This article doesn't include a security assessment of the plugin. It comes from a single outside author, its OAuth server adds its own publicly reachable login code, and it moves fast: between 3 and 12 November 2026, six versions appeared, from 1.9.0 to 1.11.3. Version 1.11.3 brought two more security fixes in exactly this OAuth code, and according to the changelog 1.4.1 had already fixed one in the refresh flow. More on that in the update of 20 November. If you use it, keep it as up to date as the API plugin and leave only the permissions the assistant really needs ticked in the consent dialog.

The plugin doesn't live under getgrav/ but in the author's own account. Whether Sandy McArthur is part of the Grav team, I couldn't establish. Grav's /ai page (opens in a new tab) advertises a "Built-in MCP Server" with "One click to enable, no sidecar service to babysit" and states "The MCP server ships with Grav." Its "How the MCP server works" link, however, leads to the grav-mcp announcement, in other words to exactly the separate Node package.

Marketing and reality

Side by side, this is how it looks to me:

Website claim What docs and code say
"Built-in Model Context Protocol server" (features page) Separate npm package for Node.js, version 0.1.5, not in the Grav package
"The MCP server ships with Grav." (/ai) The 2.2.29 download package contains no MCP server, and the docs call grav-mcp "not a Grav plugin"
"One click to enable, no sidecar service to babysit" (/ai) grav-mcp needs Node.js and a client configuration. According to the source, there's no MCP switch in Admin 2, the core or the API plugin
"Agents inherit exactly the permissions of the user account" (features page) True according to docs and code, but it depends on the API plugin, which received many security fixes in 2026
"full audit trail via Revisions Pro" (features page) Revisions Pro is a premium plugin. According to the MCP docs, "The MCP server does not add its own audit log"; the API plugin has an optional audit trail, off by default
Markdown for agents True, in the core since 2.1.0, on by default

My verdict: "AI ready" fully applies to the Markdown output and the API. "MCP ready" is true in the sense that there's an official server. "Built-in" isn't true, and I'd like the website to say so as clearly as its own docs do.

Compared with WordPress

In the article on Oxygen 6.2 I described how WordPress solves this: the Abilities API and wordpress/mcp-adapter, the MCP server runs inside WordPress, and the Agent Connector works there with fixed super-admin rights. Grav goes the opposite way. The official server runs outside, but in return the agent really only gets the permissions of a user you create. For me, that difference weighs more than the missing one-click solution. Letting an agent with tightly limited permissions onto a real site is something I can imagine with Grav; with fixed super-admin rights, only on staging.

Security

A security notice for a piece of software is called an advisory, and the CVE number is its globally unique identifier. A great many such notices about Grav appeared in 2026. I'm putting them in context here because they matter for any decision about Grav 2, and for agents all the more.

The numbers

On 20 November, the getgrav/grav (opens in a new tab) repository lists 219 advisories for core and plugins, 11 of them critical and 119 high. 184 of them are from 2026. Dozens concern the API plugin alone, which is exactly the interface agents work through, most recently the critical GHSA-fqv4-9pm4-v2q2 on 19 November (see the update of 20 November).

Among them are notices that hit the permission model directly. CVE-2026-62667 is titled "API Key 'scopes' Never Enforced", rated high and fixed in API 1.0.6, and as recently as 5 November 2026 GHSA-9g3m-8mr9-78vr appeared, rated moderate: from API 1.0.16 up to 1.1.10, a restricted key could bypass a page's permission rules, fixed in 1.1.11. Both were fixed. My takeaway: the statement "agents inherit exactly the user's permissions" only holds with a current API plugin.

From denylist to sandbox

Server-side template injection (SSTI), where someone uses Twig in page content to execute PHP code on the server, has a long history. In 1.7, a denylist protected against it, meaning a list of forbidden functions. In June 2023 came CVE-2023-34251, critical, with a proof of concept in which a page editor executed system commands through Twig, fixed in 1.7.42. In March 2024, CVE-2024-28116 to -28119 followed, fixed in 1.7.45. In December 2025, CVE-2025-66299 (opens in a new tab) explicitly described a way around the fix for CVE-2024-28116. Every round added to the list, and the next one found a way around it.

That's why Grav 2 switches to a sandbox with an allowlist that only permits explicitly allowed functions. The SECURITY.md calls it "the actual boundary" and makes clear that the older checks are only heuristics. This sandbox has had escapes too, for example via sort() before 2.0.18, or via a filter that dumped the complete configuration up to 2.0.24, and others that were only fixed in 2.2.18. Because Twig in content has run by default since 2.0.19, such escapes affected default installations as well. I still think the switch to an allowlist is right. An allowlist can be tightened without missing yet another way around it every time.

AI on both sides

At the end of October 2026, Grav took part in Anthropic's OSS Scanner, a program in which AI searches open-source code for vulnerabilities. According to Andy Miller's blog post (opens in a new tab), it produced "99 findings, with 1 rated critical and 35 rated high", and after review "22 security advisories: 1 critical, 18 high and 3 moderate" remained. Grav 2.2.18 and 1.7.53.7 came out on 31 October, and 2.2.19 and 1.7.53.8 the same evening. According to the post, AI agents took on a lot of the review work, while the decisions were his: "every call on what to fix and what to publish was mine."

I have to disclose here that I also work with AI from Anthropic. What I find remarkable is how open the post is. It admits that an advisory from August had reported a fix in 2.0.16, and says: "It wasn't." It warns that the stricter sandbox can break existing pages, and that sites on nginx, Caddy, lighttpd or IIS have to apply the new rules from webserver-configs/ "by hand". If you run Grav with Caddy, as described in the FrankenPHP article, you should check that after every release. According to the post, the one critical advisory in this round allowed anonymous visitors to read server files, including accounts and secrets, through a public form and media metadata files.

An earlier case had already shown how important the server rules are. In September 2026, GHSA-5vx9-x8f2-f55w (opens in a new tab) appeared, also critical: several of the bundled server configurations only blocked .git in the web root, so a repository like user/.git was readable anonymously. It's fixed in 2.1.7. For 1.7, the fix only arrived a good five weeks later, in 1.7.53.8 on 31 October.

The project's rules

The SECURITY.md rates reports by trust boundary, not by CVSS score (a widely used severity scale): according to the policy, a publisher running Twig in their own pages is doing exactly what they're allowed to do. There are no bug bounties (rewards for reported vulnerabilities), and the project doesn't request CVEs itself. The support table there still lists "2.0.x" as active, although 2.2 is current. That looks more like it wasn't updated than like a deliberate choice.

The pitch in the comparison with WordPress (opens in a new tab) reads: "There's no database, so there's no SQL injection and no database password to leak." For the core, that's true. The optional database plugin, however, had CVE-2026-58492, an SQL injection. Without a database, the attack surface shifts to Twig, YAML, uploads and file paths; it hasn't disappeared.

PHP2Shell affects Grav like any PHP site

Grav is a PHP application, so everything from the article on PHP2Shell applies to it. The vendor published a post of its own (opens in a new tab) on it: update and restart PHP and, as a stopgap, set session.upload_progress.enabled = 0, because "Grav doesn't use upload progress, so turning it off won't break your site". The post also recommends PHP-FPM (PHP as a separate service) over mod_php (PHP as a module inside Apache). Flat-file simply doesn't mean static: PHP runs on every uncached request.

How I'd set up an agent

All of this adds up to a short list for me. It's an assessment based on docs, code and advisories, not a tried-and-tested recipe:

  1. A dedicated user for the agent, with exactly the permissions the task needs, for example api.access (the base permission for every API call) plus api.pages.read and api.pages.write, and api.media as well for images. No api.gpm, no api.system.backup, neither api.super nor admin.super.
  2. A separate key per agent, with an expiry date. According to the API plugin, keys:generate offers the --expiry option for that, taking a number of days.
  3. grav-mcp only via stdio on your own machine. I wouldn't make HTTP mode openly reachable.
  4. Keep the API off the open internet where you can. Even via stdio, grav-mcp talks to your site's /api over HTTP. I'd restrict that path to known IPs or a VPN at the web server, because dozens of 2026 advisories hit exactly the API plugin, most recently one that could be exploited without logging in.
  5. Always keep the API plugin (at least 1.1.21), Grav and, if used, mcp-server (at least 1.11.3) up to date. At this release pace, that means checking several times a week.
  6. Staging or local first, and back up content in Git beforehand. With Grav that's easy, because everything is a file.

Ecosystem and costs

The website counts 548 plugins, 140 themes and 56 skeletons, meaning ready-made starter packages. The GPM index for Grav 2 lists 542 plugins. But listed doesn't mean tested: 312 of them state nothing about compatibility, and 287 had no release in 2026. The check in the migration plugin relies mainly on that information. Without it, according to the source, a plugin counts as 1.7-only in the recommended "Strict" mode and isn't carried over. Only in "Permissive" mode does the wizard also take over plugins without that information, unchecked. So the error goes in the cautious direction: you're more likely to lose a plugin than to have an untested one slip through. Before a switch, I'd therefore look at every plugin I need individually.

A few key points for Grav 2:

  • Admin: The classic admin only exists for 1.7; for Grav 2 there's Admin 2.
  • Theme: The default is Quark 2. According to its README (opens in a new tab), it's built on Blades CSS v2, the maintained successor to Pico CSS, while the features page still says Pico CSS v2. The old Quark is only listed for 1.7.
  • Git Sync by Trilby Media syncs the user/ folder with GitHub, GitLab or your own Git and supports 1.7 and 2.0. According to an advisory in the Grav repository (GHSA-c89w-55m3-fmf7), it had a command injection via commit authors in September 2026, fixed in 3.4.13. Here's the repository (opens in a new tab).
  • Static export: The Static Generator plugin had its last release in 2023 and states nothing for Grav 2. For a static export under Grav 2, I wouldn't rely on it.

The core is free. According to the premium page (opens in a new tab), you buy premium plugins once per site, and development and staging environments don't count. There are two for AI: AI Pro (opens in a new tab) for 75 US dollars, a connection to OpenAI, Claude, Gemini, OpenRouter and custom providers with an assistant in the admin, and AI Translate (opens in a new tab), also for 75 US dollars, translation via DeepL, Google or the providers from AI Pro. Neither has anything to do with MCP. New since 6 November 2026 is Grav Guard (opens in a new tab), a service for updates, backups and monitoring. Guard is free for up to three sites, with updates you run yourself (a backup first, undone automatically if something fails), backups on your own server, integrity scans and an uptime check. Automatic updates, rollback on demand, rescue for broken sites and external backups (Guard Vault) only come with Premium at 2 US dollars per site per month, with a minimum of three sites, and cheaper from the eleventh site.

Who Grav suits and who it doesn't

In my view, documentation, knowledge bases, company and project sites, blogs and smaller multilingual sites work well with Grav, in other words anywhere content lives in Markdown and Git is the natural workplace. If you want AI agents to read and maintain content, Grav 2, with its Markdown output and a real permission model, is in my view one of the more interesting candidates.

When it doesn't fit, Andy Miller himself says surprisingly openly in the comparison with WordPress: "A large newsroom or multi-author publication with a heavy editorial workflow", "A site that depends on a specific WordPress plugin with no Grav equivalent" and "A client who will hire a different agency next year, and needs a platform any freelancer can pick up". He adds: "There's no one-click WordPress importer for Grav today, and I'd rather be upfront about that." I'd add one point: Grav 2 doesn't fit if nobody applies updates promptly. With 72 releases in roughly five months and this many advisories, that's no side issue.

And if you don't need PHP at runtime at all, a static generator with a Git-based CMS can also be the answer. What that looks like with 11ty is shown in the article on Sveltia CMS.

FAQ

Does Grav 2 have a built-in MCP server?

No. The official server is the npm package grav-mcp 0.1.5, which runs under Node.js next to your AI client and talks to the site through the API. An endpoint directly in the site is offered by the mcp-server plugin by Sandy McArthur, which doesn't live in the getgrav account.

Do I need a plugin for the Markdown output?

No. Since Grav 2.1.0, the core answers .md URLs and requests with Accept: text/markdown, on by default. Only for the llms.txt do you need the sitemap plugin 5.3.0 or later.

What permissions does an AI agent have in Grav?

Those of the user who owns its API key. According to the docs, a key can never do more than that user. Create a dedicated user with few permissions for it and keep the API plugin up to date, at least at 1.1.21, because that's exactly where several fixes for key permissions landed in 2026, and most recently a critical one against account takeover.

Can I update Grav 1.7 directly to 2.0?

Not as an update over the existing installation. The "Migrate to Grav 2.0" plugin builds a fresh version in a subfolder, copies your user/ folder and lets you test before you switch over. Your Markdown content needs no conversion; templates and plugins you have to check.

Does Grav really need no database?

Grav doesn't need a database server. Since 2.2, however, it creates a page index by default for sites with 1,000 pages or more, in SQLite via pdo_sqlite. As a substitute, it runs with the pure-PHP engine YetiSQL from the database-yetisql plugin. If both are missing, Grav uses the old cache.

Does Grav run with FrankenPHP?

Yes. Which changes to the bundled Caddyfile and which PHP extensions it takes is in the article on FrankenPHP and Caddy. What was checked there is only Grav core without the admin, in classic mode.

Conclusion

In my view, Grav 2 is the project's biggest step since version 1.0: a new stack, a new admin on top of a real API, and a template sandbox that draws the right lesson from years of denylist fixes. For AI, the Markdown output in the core is the piece that already fully delivers today, and I like the API's permission model better than the fixed super-admin rights I described in the Oxygen article. The MCP server is official, but young, external and not as built in as the website says.

I remain a fan. If you want to work with Grav 2 and agents, my advice would be: take the Markdown output right away, give agents their own tightly limited users, and plan updates as a fixed part of operations.

For this article, Claude Code supported me with creation, correction and verification. The direction and the editorial responsibility are mine. There's more on that on the AI transparency page.

Further reading

How Grav runs with FrankenPHP and Caddy is in the article on FrankenPHP and Caddy, the commands for bin/grav and bin/gpm are in the Grav cheat sheet, and the directives in the cheat sheet on FrankenPHP. What an MCP server with super-admin rights looks like in WordPress is shown in Oxygen 6.2. What belongs in Markdown for AI systems is described in Writing for AI, and why this site runs statically with Markdown twins in Why 11ty. What to do about PHP2Shell is explained in the article on it.