MCP Reference - Accent CMS

Accent CMS exposes a Model Context Protocol (MCP) server for AI-assisted content management. This page is a complete reference of every tool, resource, configuration field, and CLI flag.

For setup instructions and client integration guides, see the MCP Server integration page.

CLI

`accent mcp`

Start the MCP server in stdio mode (JSON-RPC over stdin/stdout).

accent mcp [OPTIONS]

Flag	Type	Default	Description
`-c, --config`	path	`config.yaml`	Path to the site configuration file
`--site-dir`	path	–	Project root directory (derives content and theme directories)
`--content-dir`	path	–	Content directory override
`--theme-dir`	path	–	Theme directory override
`--theme`	string	–	Theme name override

A valid Pro license key is required. Set it via the ACCENTCMS_LICENSE environment variable or the license.key field in config.yaml.

Configuration

All MCP settings live under the mcp: section in config.yaml. Every field has a sensible default, so the entire section can be omitted.

mcp:
  transport: stdio
  http:
    path: /_mcp/
  tools:
    write_enabled: false
    allowed_paths: []

`mcp.transport`

Value	Description
`stdio`	JSON-RPC over stdin/stdout (default). Used by Claude Desktop, Claude Code, Cursor, VS Code.
`http`	SSE transport on an HTTP endpoint (future).

`mcp.http`

Field	Type	Default	Description
`path`	string	`/_mcp/`	URL path for the HTTP/SSE transport endpoint

`mcp.tools`

Field	Type	Default	Description
`write_enabled`	bool	`false`	Enable mutation tools (`update_frontmatter`, `create_page`, `move_page`). Disabled by default for safety.
`allowed_paths`	list of strings	`[]` (all)	Restrict tool access to pages under these URL prefixes. Empty means all paths are accessible. Applies to both read and write tools.

Example – restrict access to /blog and /docs:

mcp:
  tools:
    allowed_paths:
      - /blog
      - /docs

Requests for pages outside these prefixes (e.g., /admin/secret) are rejected with an invalid_params error.

Tools

Read Tools

`read_page`

Read a single page by URL path. Returns page metadata, hierarchy, translations, and optionally the raw markdown body.

Parameter	Type	Required	Default	Description
`url`	string	yes	–	URL path of the page (e.g., `/blog/my-post`)
`include_content`	bool	no	`false`	Include the raw markdown body in the response

Response fields: title, date, author, tags, template, status, lead, url, parent, children, breadcrumbs, translations, custom (passthrough frontmatter fields), and content (when include_content is true).

Errors: invalid_params if the page is not found or the path is not in allowed_paths.

`list_pages`

List pages matching filter criteria with sorting and pagination.

Parameter	Type	Required	Default	Description
`path_glob`	string	no	–	Glob pattern to match page URLs (e.g., `/blog/**`)
`tag`	string	no	–	Filter to pages with this tag
`author`	string	no	–	Filter to pages by this author
`status`	string	no	–	Filter by status: `published`, `draft`, `review`, `archived`
`template`	string	no	–	Filter by template name
`sort`	string	no	`date`	Sort field: `date`, `title`, `url`, `modified`
`order`	string	no	`desc`	Sort order: `asc` or `desc`
`limit`	integer	no	`50`	Maximum number of pages to return
`offset`	integer	no	`0`	Number of pages to skip

Response: Array of page summary objects (same fields as read_page minus content).

`search_content`

Full-text search across page content. Returns matching pages ranked by relevance.

Parameter	Type	Required	Default	Description
`query`	string	yes	–	The search query string
`fields`	list of strings	no	all	Fields to search in (see below)
`limit`	integer	no	`20`	Maximum number of results

Searchable fields:

Field value	Searches
`title`	Page titles
`content`	Markdown body text
`tags`	Tag names
`lead`	Lead/summary text
`frontmatter`	All custom frontmatter fields

When fields is omitted or empty, all fields are searched.

`get_tags`

Get all taxonomy tags with page counts.

Parameter	Type	Required	Default	Description
`include_pages`	bool	no	`false`	Include the list of page URLs for each tag
`tag`	string	no	–	Glob pattern to filter tag names

Response: Array of tag objects with name, count, and optionally pages (list of URLs).

`get_tree`

Get the content hierarchy tree.

Parameter	Type	Required	Default	Description
`root`	string	no	`/`	Root URL to start the tree from
`flat`	bool	no	`false`	Return a flat list with depth information instead of a nested tree

Response: Nested tree of page nodes with url, title, order, and children. With flat: true, a flat array with depth values.

Mutation Tools

All mutation tools require mcp.tools.write_enabled: true in config.yaml. Without it, calls return an invalid_params error. Mutation tools also respect allowed_paths.

After each successful write, the content index is rebuilt from disk so subsequent reads reflect the changes.

`update_frontmatter`

Update frontmatter fields on an existing page.

Parameter	Type	Required	Default	Description
`url`	string	yes	–	URL path of the page to update
`set`	JSON object	no	–	Fields to set (e.g., `{"status": "published", "tags": ["rust"]}`)
`remove`	list of strings	no	–	Field names to remove from frontmatter
`dry_run`	bool	no	`false`	Preview changes without writing to disk

At least one of set or remove must be provided. String values in set are stored as-is; non-string values are serialized to their YAML representation. Field names must be printable text: a name containing a control character other than tab (a line break, DEL, or a C1 control) or the non-characters U+FFFE and U+FFFF is refused with invalid_params naming the key, before the page is read.

Response fields: written (bool), path (file path), before and after (frontmatter snapshots in dry-run mode).

Errors: invalid_params if the page is not found, the path is restricted, or no operations are provided. Requires write_enabled.

`create_page`

Create a new content page.

Parameter	Type	Required	Default	Description
`url`	string	yes	–	Desired URL path (e.g., `/blog/new-post`)
`title`	string	yes	–	Page title
`template`	string	no	`default`	Template name without file extension
`frontmatter`	JSON object	no	–	Additional frontmatter fields
`content`	string	no	–	Markdown body content
`dry_run`	bool	no	`false`	Preview what would be created without writing

The URL is resolved to a filesystem path following Accent CMS conventions (numeric prefixes, slug directories, default.md files). If a page already exists at the URL, an error is returned.

Response fields: created (bool), path (resolved file path), url (canonical URL).

Errors: invalid_params if the path is restricted, a page already exists at the URL, or a frontmatter field name contains a non-printable character (the key is named, as for update_frontmatter). Requires write_enabled.

`move_page`

Move a page to a new URL path.

Parameter	Type	Required	Default	Description
`from_url`	string	yes	–	Current URL path of the page
`to_url`	string	yes	–	Target URL path
`update_references`	bool	no	`false`	Automatically rewrite references to the old URL in other pages
`dry_run`	bool	no	`false`	Preview what would change without moving

The page’s filesystem directory is renamed. All other pages are scanned for markdown links and references to the old URL. With update_references: true, those references are rewritten in place. Both from_url and to_url must pass the allowed_paths check.

Response fields: moved (bool), from_path and to_path (filesystem paths), references (list of pages that reference the old URL).

Errors: invalid_params if either path is restricted, the source page is not found, or the target already exists. Requires write_enabled.

Resources

Resources provide read-only access to site-wide data. They are always available (no write_enabled gate).

Resource	URI	MIME	Description
Content Schema	`accent://schema`	`application/json`	Content model: frontmatter fields, available templates, configured languages
Content Tree	`accent://content/tree`	`application/json`	Full site hierarchy as a nested tree
Taxonomy	`accent://taxonomy`	`application/json`	All tags with page counts and page URLs
Validation Report	`accent://validation`	`application/json`	Content integrity validation results (missing templates, broken references)

Error Codes

MCP tools return standard JSON-RPC error codes:

Code	Name	When
`-32602`	`invalid_params`	Page not found, path restricted, write disabled, missing required parameters, target already exists
`-32603`	`internal_error`	Filesystem error, JSON serialization failure, content index rebuild failure

Server Identity

The MCP server identifies itself as:

Field	Value
Name	`accent-mcp`
Version	Current Accent CMS version
Capabilities	Tools, Resources