Framework Guide · WebMCP · Ghost

WebMCP for Ghost: making a publication agent-native

Ghost is not a page builder and not a framework — it is a publication engine: Express underneath, Handlebars themes on the surface, routes.yaml as the traffic controller, and a membership layer that behaves nothing like server-rendered pages. Fitting WebMCP to that shape requires ignoring the React-shaped advice flooding the topic and working with the grain of how Ghost actually emits HTML. This article, written for theme developers and publication leads, covers the declarative pass on real Ghost templates, the routes-powered agents manifest, the Portal caveat, and the honest boundary between read tools and write access.

Fact-checked and updated on September 2, 2026 (Ghost theme & routing documentation). Primary sources are cited at the end of the article.

The publisher’s question, stated plainly

When an agent arrives on behalf of a reader — “find their piece on the EU AI Act,” “sign me up for the weekly digest” — can it actually do the thing, or does it pattern-match pixels like every scraper before it? WebMCP, the W3C Web Machine Learning Community Group’s standard, lets a page declare its actions as callable tools: an in-browser agent (Gemini in Chrome today, behind the Chrome 149–156 origin trial — [Chrome for Developers](https://developer.chrome.com/docs/ai/webmcp)) invokes them by name with typed parameters instead of simulating a human ([specification](https://webmachinelearning.github.io/webmcp)). For a publication, that converts “indexable” into “usable” — the difference between being cited and being subscribed to.

Ghost’s shape decides the fit. Themes are server-rendered Handlebars; the Content API is a documented JSON surface; membership runs through Portal, a client-side overlay. Two of those three are excellent WebMCP substrate.

Surface 1: annotate what Ghost already renders

Every Ghost theme repeats the same form surfaces across templates: site search, the newsletter prompt, inquiry contacts. The Declarative API — the form-level half of WebMCP, whose HTML-to-JSON-Schema synthesis is dissected in our reference article — turns each into a tool with attributes and no JavaScript:

{{! partials/webmcp-search.hbs — included from header }}
<form action="{{@site.url}}/s/" method="get"
      toolname="search-publication"
      tooldescription="Searches all published posts on this site. Returns a results page listing matching articles.">
  <input type="search" name="q" required>
  <button type="submit">Search</button>
</form>

Two Ghost-specific mechanics make theme-global rollout trivial. First, ghost_head and ghost_foot — the mandatory helpers in default.hbs ([theme structure docs](https://ghost.org/docs/themes/structure/)) — are the injection anchors: the origin-trial <meta http-equiv="origin-trial"> tag belongs inside ghost_head and lands on every rendered page automatically. Second, Ghost’s labs flags and theme-versioning culture mean a WebMCP annotation pass can ship behind a feature flag exactly like any other theme change — which, given a draft specification, is the correct instinct.

Surface 2: imperative tools fed by the {{#get}} helper

Ghost’s functional {{#get}} helper fetches Content API data at render time — posts, authors, tags, pagination metadata ([helper docs](https://ghost.org/docs/helpers/get/)) — and its result can be serialized straight into the client runtime, so tools answer from page state with zero extra fetch:

{{! partials/webmcp-tools.hbs — included before }}
<script type="application/json" id="webmcp-seed">
{
  "site": "{{@site.title}}",
  "total": {{#get "posts" limit="1"}}{{meta.pagination.total}}{{/get}},
  "tags": [{{#get "tags" limit="10"}}{{#if @first}}{{else}},{{/if}}"{{slug}}"{{/get}}]
}
</script>
<script>
(function () {
  var ctx = document.modelContext || navigator.modelContext;
  if (!ctx || !('registerTool' in ctx)) return;
  var seed = JSON.parse(document.getElementById('webmcp-seed').textContent);
  var controller = new AbortController();

  ctx.registerTool({
    name: 'list-recent-posts',
    description: 'Lists the most recent published articles with titles, URLs and dates. Read-only.',
    inputSchema: {
      type: 'object',
      properties: { tag: { type: 'string', description: 'Optional tag slug filter' } },
      additionalProperties: false
    },
    annotations: { readOnlyHint: true },
    async execute({ tag } = {}) {
      var q = tag ? 'tags/' + encodeURIComponent(tag) + '/' : '';
      var res = await fetch('/' + q + 'rss/');            // or the Content API with your public key
      var text = await res.text();
      return { content: [{ type: 'text', text: text.slice(0, 8000) }] };
    }
  }, { signal: controller.signal });
})();
</script>

The ceremonial pieces are all specification-mandated and worth naming once: feature detection on the dual root (document.modelContext || navigator.modelContext) because Chrome’s own guidance documents the migration from the older alias ([modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md)); the MCP content envelope on the return value; and the AbortController signal as the only deregistration mechanism — there is no unregisterTool().

Surface 3: routes.yaml as a machine-readable front door

Ghost’s routing layer maps URLs to templates with arbitrary content types, including application/json ([routing docs](https://ghost.org/docs/themes/routing/)). For agent-readiness that is a small superpower:

# routes.yaml
routes:
  /agents.json:
    template: agents-manifest        # renders agents-manifest.hbs
    content_type: application/json

A Handlebars template seeded by {{#get}} emits a static, cacheable agents manifest — the emerging convention (agents.json, and the broader discovery stack examined in our companion piece, agents.json and WAIS) for declaring what an agent may do on your site — generated entirely inside Ghost, with no middleware, no proxy, no external service. A second route, /api/catalog with content_type: application/json, gives crawlers and headless MCP bridges a clean read-only feed. Server-rendered publishing platforms rarely get this clean an opportunity to speak machine languages natively; Ghost gives it to you in YAML.

The Portal caveat: client overlays and tool boundaries

Membership runs through Portal, a JavaScript overlay mounted at runtime — its signup fields are not in the server-rendered HTML, so declarative synthesis cannot see them. Two honest options: annotate a server-rendered subscribe fallback (accepting the duplication), or register an imperative tool that invokes Portal’s own public API — the portal('subscribe') snippet Ghost ships for buttons — from inside execute. Either way, leave the final click to a human: omit toolautosubmit, per the spec’s default, so billing-adjacent actions keep the confirmation step.

Members-only content: the browser layer mirrors the paywall

Ghost enforces visibility server-side (public / members / tiers), and WebMCP tools execute as the visiting user with their session cookie — so a read-article tool that fetches the post URL returns exactly what that human would see: full text if entitled, teaser if not. There is no privilege path through the browser layer that does not already exist in the site itself, and no way for an agent to read past a wall the reader cannot. Symmetrically, the teaser is the feature: it is what converts an agent-mediated discovery into a signup — the subscribe tool is two calls away.

Testing on a Ghost install

Local: ghost run, Chrome with chrome://flags/#enable-webmcp-testing, DevTools — (await document.modelContext.getTools()).map(t => t.name). Production: register the origin at the Chrome Origin Trials console, drop the token into default.hbs, upload the theme. Validate across contexts — index.hbs, post.hbs, tag.hbs, author pages — because Ghost’s template context differs per route and a seed island exists only where you included it. The Model Context Tool Inspector extension confirms the synthesized schemas; Gemini-in-Chrome simulation confirms routing against your descriptions.

FAQ

Conclusion

Ghost’s community has always optimized for the reader’s next click — newsletters, memberships, the open social web. WebMCP is that instinct, one abstraction level closer to execution: the reader’s agent stops scraping your archive and starts using your publication, within exactly the entitlements you already modelled. Annotate the search, ship the manifest, let the Content API seed your tools, and leave every consequential click to a human. A publication that is agent-usable is, in the end, simply a publication that kept its promises machine-legible.

Primary sources

1. webmachinelearning.github.io/webmcp — W3C CG specification.
2. WebMCP — Declarative API explainer.
3. developer.chrome.com/docs/ai/webmcp — origin trial documentation.
4. ghost.org/docs/themes — structure, helpers, routing.
5. ghost.org/docs/content-api — read API semantics.
6. Model Context Tool Inspector — validation extension.