Skip to main content
Every markdown file managed by the Versuno MCP server (and the CLI) has a YAML frontmatter block at the top with standardised fields. This is how the server tracks which local file corresponds to which cloud asset.

​
Full example

​
Field reference

Fields are written in this order by pull_asset and push_asset. All fields except id, type, and title are optional. push_asset preserves any fields it doesn’t manage.

​
Which fields are writable

When you edit a file locally and run push_asset, only these fields are sent to the API:
  • title
  • Body (everything after the frontmatter)
  • tags
Changes to id, version, created_at, updated_at, or versuno_url are ignored. These are server-owned. To change type, project, importance, or maturity, use the Versuno dashboard or API directly. The MCP currently doesn’t expose tools for those fields.

​
What happens with extra fields

If you add your own fields to the frontmatter, the server doesn’t touch them. They’ll round-trip through pull_asset and push_asset unchanged. This is handy for local-only metadata like review status or owner.

​
Malformed frontmatter

The parser accepts any valid YAML that resolves to a plain object. It rejects:
  • YAML that parses to an array or a scalar (these are treated as “no frontmatter”).
  • Syntactically broken YAML (treated as “no frontmatter”, and the file is treated as a raw body).
Nothing crashes on bad input, but you’ll lose the id-based upsert behaviour if the frontmatter doesn’t parse.

​
Relationship to the CLI

The CLI uses the exact same schema and field ordering. A file pulled via the MCP can be pushed with versuno prompts push, and vice versa. See CLI: versuno prompts push.