Tool Overview

Every tool follows the same pattern: send an action parameter to specify what operation to perform, along with action-specific parameters. All tools return a standardized response.

Response Format

{
    "success": true,
    "data": { },
    "meta": {
        "tool": "statamic-blueprints",
        "timestamp": "2026-03-12T12:00:00Z",
        "statamic_version": "6.0.0",
        "laravel_version": "12.0.0"
    }
}

The statamic_version and laravel_version fields in meta are only included when security.expose_versions is enabled (defaults to false).

On error, the response includes an error key with a human-readable message and a code key with a machine-readable error code.

Finding the tools

Only three tools are listed in the catalog a client loads at connect time: statamic-entries, statamic-blueprints and statamic-system-discover. Everything else documented below is reached through two built-in tools:

• search_tools — describe what you want; get back matching tools and their schemas.
• execute_tools — run one or more of them by name.

This keeps roughly 18 KB of JSON schema out of the client's context on every connection. The hidden tools are not restricted in any way: same token scopes, same resource policy, same permissions, same confirmation gate. If your client handles search_tools poorly, set STATAMIC_MCP_SEARCHABLE_CATALOG=false to have all of them listed directly — see the configuration reference.

statamic-system-discover maps an intent to the right tool and tells you which of the two ways to reach it.

Domain Routers

statamic-blueprints

Manage blueprint definitions, field schemas, and type generation.

statamic-entries

Dedicated entry operations with advanced filtering, search, and pagination.

Narrowing a blueprint response

A page builder's format spec is proportional to every set it can hold, so the full response for a large blueprint can exceed the response size limit at any useful depth. Pass field to statamic-blueprints get with a dot path to scope the response to one field or set:

{ "action": "get", "namespace": "collections", "collection_handle": "pages",
  "handle": "pages", "field": "page_builder.ContentSection.media" }

Segments are the handles the spec already reports — allowed_set_types for a set, group_fields for a group. An unresolvable path lists the valid segments at the level it failed, so a client can walk down without guessing.

Setting a template or layout per entry

template and layout are entry data that Statamic reads back itself (Entry::template() falls back to $this->get('template')), but neither has to be a blueprint field. Send either in data on create, update or localize and it is stored:

{ "action": "update", "collection": "pages", "id": "home",
  "data": { "template": "pages/landing" } }

Send null to clear it and fall back to the collection's template. A non-string value is refused. parent is not writable this way — an entry's parent comes from the structure tree, not its data.

Updating one section of a page builder

By default a replicator field in data replaces the stored array outright, so changing one section means resending every other. With merge_sets: true the incoming items are merged into the stored array by their id: an id that already exists is replaced in place, a new one is appended, and stored items you did not send are left untouched.

Every item sent must carry an id. Removing or reordering items still requires sending the full array with merge_sets off, where the intent is unambiguous. Applies to top-level replicator fields only — not bard, whose nodes are not all addressable by id.

statamic-terms

Taxonomy term management with slug conflict prevention and dependency validation.

statamic-globals

Global set structure and values management with multi-site support.

statamic-structures

Manage collections, taxonomies, navigations, and site configuration. Requires a resource_type parameter (collection, taxonomy, navigation, site, globalset).

Navigation trees

get returns a navigation's menus as trees: [{site, items}]. A write accepts that same list back, so the usual edit is: read, change the items, send the list as data.trees. A map of site to items, or a single data.tree with an optional data.site, works too. A tree replaces the whole menu for its site.

Each item is {id?, entry?, url?, title?, data?, children?} and needs at least an entry, a url or a title. Items without an id get one. The whole payload is checked before anything is saved: unknown keys, entries that do not exist, duplicate ids, unknown sites and items deeper than max_depth are refused with the path that failed, e.g. trees.default[1].children[0] is 3 levels deep.

{
  "action": "update",
  "resource_type": "navigation",
  "handle": "main",
  "data": {
    "tree": [
      {"id": "home", "entry": "91fc9bb6-..."},
      {"title": "Contact", "url": "/contact"}
    ]
  }
}

statamic-assets

Asset container and file operations. Requires a resource_type parameter (container, asset).

upload takes the file one of three ways:

• source_url — the server downloads it. This is the way for a remote client such as Claude or ChatGPT to add an image without sending it as base64. Only public http/https hosts on default ports can be fetched, never the server's own network; see security.url_import.
• content with encoding: base64 and a filename — the bytes in the call itself. Fine for small files; a photo of a few megabytes is too much for most clients.
• file_path — a file under storage/app, for local CLI clients.

folder places the file, e.g. uploads/cases. Every upload goes through Statamic's own allowed-extensions check, as a Control Panel upload does; a site widens it with statamic.assets.additional_uploadable_extensions.

For move and copy, destination is the new path with the filename: archive/old-hero.jpg. End it with / to keep the filename. The extension cannot change. copy refuses to overwrite an existing file. | delete | asset | Delete asset | container, path |

statamic-users

User CRUD with role and group management. Requires a resource_type parameter (user, role, group).

statamic-system

System information, health checks, cache management, and configuration access.

statamic-content-facade

High-level analysis workflows that orchestrate multiple router calls.

Schema accepts action (required, enum: content_audit, content_validate, cross_reference) and the parameters listed above.

content_validate

Writes made through this addon are validated on the way in. content_validate is the read-side sweep for everything else — git merges, hand-edited YAML, and blueprints changed after the content was written.

Each record gets two passes: the blueprint's own validation rules, evaluated the same way a Control Panel save evaluates them, plus structural checks the rule engine cannot express.

Parameters:

• scope — all (default), entries, terms, globals, or navigations
• collection / taxonomy — restrict the entry or term sweep to one handle
• severity — return only error or only warning findings
• limit / offset — records scanned per call (default 100, max 500). Records are walked in a fixed order (entries → terms → globals → navigations) and the offset addresses that combined stream, so paging a large site means repeating the call with a rising offset until pagination.has_more is false.
• max_findings — cap on findings returned per call (default 200, max 2000). summary.findings stays accurate when the list is truncated.

Non-blueprint keys at the top level of an entry (template, layout, parent, …) are legitimate and never reported; the unknown_field check applies only inside sets and grid rows.

statamic-system-discover

Intent-based tool discovery. Describe what you want to do and the tool suggests which MCP tool and action to use.

statamic-system-schema

Inspect the full JSON schema of any registered tool. Useful for AI agents to understand available parameters.

Resources

Alongside tools, the server exposes MCP resources — read-only views a client can browse without spending a tool call.

Read statamic://blueprints first to discover the URIs, then read the one you need. Namespaces include the per-collection and per-taxonomy forms Statamic uses for entry and term blueprints, so a URI often looks like statamic://blueprints/collections.pages/article.

Resources enforce the same authorization as the equivalent tool call: the domain must be enabled, the token must carry blueprints:read, the resource policy must allow the handle, and the underlying Statamic user must have permission. A blueprint the resource policy hides does not appear in the index at all.

Tool Annotations

Tools declare behavior annotations:

• #[IsReadOnly] — Tool only reads data and has no side effects
• #[IsIdempotent] — Tool can be called multiple times safely with the same result

Tools also declare a #[Title] — the human-readable name a client shows in its UI, distinct from the protocol name (statamic-entries → "Statamic Entries").