OlonJS MCP manifest structure: fields, schemas, endpoints

The OlonJS MCP manifest system consists of three layers: a master index, per-page manifests, and JSON Schema contracts. Together they give AI agents and integrations a complete, typed view of your site — from the top-level page list down to the exact data shape of every individual section.

Master manifest (`/mcp-manifest.json`)

The master manifest is the entry point for all agent interactions. It lists every page and every collection registered in your OlonJS site.

string

required

The manifest format version. Currently "1.0.0".

string

required

Always "olonjs-mcp-manifest-index". Agents can use this field to confirm they are reading an OlonJS master manifest rather than a per-page manifest or some other JSON document.

string

required

ISO 8601 timestamp recording when this manifest was last produced by a build. Use this value to determine whether the manifest is stale relative to a cached copy.

array

required

An ordered array of page entry objects, one for each page in the site. See Page entry fields for the shape of each object.

array

required

An array of collection entry objects, one for each registered collection (e.g. posts, tags). Each entry contains:

source — the collection name as a string
dataHref — path to the raw JSON data file for the collection
contractHref — path to the JSON Schema that describes the collection record shape

Page entry fields

Each object inside pages[] describes a single page in your site:

string

required

The URL slug that identifies the page. Static pages use a simple string (e.g. "about"). Dynamic collection pages use bracket notation (e.g. "posts/[slug]"), and resolved instances list their concrete slug (e.g. "posts/the-boring-stack").

string

required

The page’s <title> value as set in the page data. Agents can display this to users or use it for indexing without fetching the full page manifest.

string

required

The page’s meta description. Provides a one-sentence summary of the page’s content or purpose.

string

required

Path to the per-page manifest JSON file (e.g. "/mcp-manifests/about.json"). Fetch this URL to get the full content bundle, section instances, transport spec, and tools for this page.

string

required

Path to the JSON Schema contract for this page (e.g. "/schemas/about.schema.json"). Fetch this URL to get the typed schema that describes every field and section on the page.

array

required

An ordered list of section type strings that appear on this page (e.g. ["header", "footer", "page-hero", "content-block"]). Agents can use this to understand page structure without fetching the full manifest.

Per-page manifest (`/mcp-manifests/[slug].json`)

Each page in your site has its own manifest at /mcp-manifests/[slug].json. The per-page manifest provides the complete content and structural description needed to read, validate, or update a page programmatically. Here is a real example from the Inkwell Journal about page:

/mcp-manifests/about.json

{
  "version": "1.0.0",
  "kind": "olonjs-page-mcp-manifest",
  "generatedAt": "2026-07-29T16:37:46.140Z",
  "slug": "about",
  "title": "About Inkwell Journal and this collections demo",
  "description": "Inkwell Journal is a working OlonJS demo: posts and tags live as separate collections, related through keys on the post side and resolved at render time.",
  "contractHref": "/schemas/about.schema.json",
  "transport": {
    "kind": "window-message",
    "requestType": "olonjs:webmcp:tool-call",
    "resultType": "olonjs:webmcp:tool-result",
    "target": "window"
  },
  "capabilities": {
    "resources": [
      {
        "uri": "olon://pages/about",
        "name": "About Inkwell Journal and this collections demo Data",
        "mimeType": "application/json",
        "description": "Structured content for the about page."
      },
      {
        "uri": "olon://pages",
        "name": "Site Map",
        "mimeType": "application/json",
        "description": "Structured content for the map of this site"
      }
    ]
  },
  "sectionTypes": [
    "header",
    "footer",
    "page-hero",
    "content-block",
    "stats-band",
    "cta-banner"
  ],
  "sectionInstances": [
    {
      "id": "global-header",
      "type": "header",
      "scope": "global",
      "label": "header"
    },
    {
      "id": "global-footer",
      "type": "footer",
      "scope": "global",
      "label": "footer"
    },
    {
      "id": "about-hero",
      "type": "page-hero",
      "scope": "local",
      "label": "A journal that is also a diagram"
    },
    {
      "id": "about-story",
      "type": "content-block",
      "scope": "local",
      "label": "One source of truth per relation"
    },
    {
      "id": "about-stats",
      "type": "stats-band",
      "scope": "local",
      "label": "What powers the demo"
    },
    {
      "id": "about-cta",
      "type": "cta-banner",
      "scope": "local",
      "label": "See it in motion"
    }
  ],
  "tools": [
    {
      "name": "update-section",
      "description": "Update a section field in the Studio draft. Does not persist — call save when all updates are complete. Use sectionType to select the matching schema from sectionSchemas."
    },
    {
      "name": "save",
      "description": "Persist all pending draft changes. Call once after all update-section calls are complete."
    }
  ]
}

Key fields unique to the per-page manifest:

Field	Description
`kind`	Always `"olonjs-page-mcp-manifest"` — distinguishes per-page manifests from the master index
`transport`	Describes how agents communicate with the Studio editor for live updates (`window-message` transport)
`capabilities.resources[]`	MCP resource descriptors — the `olon://` URIs this page exposes
`sectionInstances[]`	The concrete section instances on this page, each with an `id`, `type`, `scope` (`global` or `local`), and human-readable `label`
`tools[]`	MCP tool descriptors the Studio exposes for this page — `update-section` and `save`

JSON Schema contracts (`/schemas/[slug].schema.json`)

Every page has a JSON Schema contract at /schemas/[slug].schema.json. The schema precisely describes the data shape of the entire page bundle — every section, every field, and every type. Agents can use these schemas to:

Validate content before submitting an update via the update-section tool
Generate page content that matches the expected structure
Understand which fields are required, optional, or constrained

Collection schemas follow the same convention at /schemas/collections/[collection].schema.json.

Collection endpoints

Raw collection data is available as static JSON files that agents can read directly:

Collection	Data endpoint	Schema
`posts`	`/collections/posts/posts.json`	`/schemas/collections/posts.schema.json`
`tags`	`/collections/tags/tags.json`	`/schemas/collections/tags.schema.json`

These files contain the full record set for each collection — the same data used to render collection pages at build time. They are useful for agents that need to enumerate all posts, look up a tag by key, or build a cross-collection relation map without navigating individual page manifests.

Example: reading a page

The following sequence shows how an agent reads the about page from scratch using only public endpoints: Step 1 — Discover pages

GET /mcp-manifest.json

Parse the pages[] array to find the entry where slug === "about". Note its manifestHref value: /mcp-manifests/about.json. Step 2 — Fetch the per-page manifest

GET /mcp-manifests/about.json

Read sectionInstances[] to understand the page structure. Each instance has an id, type, scope, and label. Step 3 — Fetch the JSON Schema contract

GET /schemas/about.schema.json

Use the schema to understand the exact fields available on each section, their types, and any constraints before attempting to read or write content. Step 4 — (Optional) Update content via Studio tools If the Studio editor is open and you need to update a section, use the update-section tool described in the per-page manifest’s tools[] array. Call save once all updates are staged.

Get Started

Core Concepts

Building Your Site

Configuration

MCP & AI

OlonJS MCP manifest structure: fields, schemas, endpoints

Master manifest (`/mcp-manifest.json`)

Page entry fields

Per-page manifest (`/mcp-manifests/[slug].json`)

JSON Schema contracts (`/schemas/[slug].schema.json`)

Collection endpoints

Example: reading a page

​Master manifest (/mcp-manifest.json)

​Page entry fields

​Per-page manifest (/mcp-manifests/[slug].json)

​JSON Schema contracts (/schemas/[slug].schema.json)

​Collection endpoints

​Example: reading a page

Master manifest (`/mcp-manifest.json`)

Page entry fields

Per-page manifest (`/mcp-manifests/[slug].json`)

JSON Schema contracts (`/schemas/[slug].schema.json`)

Collection endpoints

Example: reading a page