MCP
Navigation integrates with Craft’s Model Context Protocol (MCP) server so an AI client can inspect menus, create and edit links, and rearrange nodes. For example, you can ask a connected client to inspect your header menu, add a Contact link, and place it after About.
This integration requires Craft 5.12 or later. Navigation still works on earlier supported Craft versions, but its MCP tools aren’t available there.
Connecting a Client
Follow Craft’s MCP setup instructions (opens new window) to connect a client through the authenticated HTTP server or the local mcp/serve command. Navigation registers its tools automatically; there is no separate Navigation server to install or enable. These tools aren’t exposed through Craft’s public MCP server.
The client acts as the signed-in user and follows Navigation’s menu and site permissions. An HTTP connection authorised for read-only access can inspect menus; editing also requires write access. Menu access doesn’t grant permission to read the contents of linked entries or assets.
Changes made over MCP save immediately. They do not go through the menu builder’s staged changes. Save or discard your builder changes before editing the same menu through a client, then reload the builder afterwards. Existing ownership restrictions still apply to staged nodes.
Working with Nodes
Start with navigation.menus.list to find menu IDs, handles and the sites you can manage. Then use navigation.menus.tree to inspect a menu’s hierarchy, or Craft’s elements.* tools with the type navigation-nodes. The node reference handle also works.
| Tool | Purpose |
|---|---|
elements.schema | Describes supported query criteria and writable node attributes. |
elements.list | Finds nodes using criteria such as handle (menu handle), menuId, type, elementId and level. |
elements.get | Reads an individual node. |
elements.field-schema | Describes the custom field values a node accepts. For a new node, pass its menuId and optional siteId in context. |
elements.create | Creates a node using type and either menuHandle or menuId in attributes. |
elements.update | Changes an existing node’s supported attributes or custom fields. |
elements.validate | Checks proposed changes to an existing node without saving them. |
elements.delete | Deletes a node. |
elements.restore | Restores a soft-deleted node, subject to the user’s permissions. |
The outer type identifies Navigation nodes. The type inside attributes identifies the kind of link, such as verbb\navigation\nodetypes\Entry or verbb\navigation\nodetypes\Custom. Call elements.schema to discover the registered node types and accepted attributes. Node types requiring additional provider settings may need to be configured in the control panel.
For example, if your menu handle is header, these arguments to elements.create add a custom Contact link:
{
"type": "navigation-nodes",
"attributes": {
"menuHandle": "header",
"type": "verbb\\navigation\\nodetypes\\Custom",
"title": "Contact",
"url": "/contact"
}
}Element links use linkedElementId instead of url. Set parentId to nest a new node beneath an existing node in the same menu. To change an existing node’s parent, use navigation.nodes.move. New nodes default to the primary site; pass siteId explicitly when working in another site. Discover custom fields with elements.field-schema, then pass their values in the separate fields argument to create or update a node.
Navigation nodes are saved directly. Creating unpublished drafts and duplicating nodes through Craft’s generic MCP tools are not supported.
Menu Tools
| Tool | Purpose |
|---|---|
navigation.menus.list | Lists accessible menus with their IDs, handles, permitted site IDs and limits. |
navigation.menus.tree | Returns a menu’s hierarchy, including disabled nodes and children generated by dynamic nodes. Accepts a menu handle or ID, an optional siteId, and withLinkedElements. Linked content is included only when the user can view it, using Craft’s MCP field serialization. |
navigation.nodes.move | Moves a node before or after a sibling, or uses prepend or append to place it under a parent. Omit targetNodeId for the menu’s top level with prepend or append. Descendants move with the node, and menu limits and permissions apply. |
The tree and move tools default to the primary site. Use the IDs returned by the menu tools when moving nodes. A target must be in the same menu and cannot be the moving node itself or an invalid descendant target. Children generated by dynamic nodes are read-only projections; edit their source content or the dynamic node’s settings instead.
Craft’s structures.move-element tool only moves entries. Use navigation.nodes.move to reorder Navigation nodes.