# Agility CMS MCP MCP

> Agility CMS MCP manages and queries your content structure through AI. It gives you programmatic access to nested sitemaps, specific page layouts, and entire reference lists within the Agility CMS environment. You can list article entries, search for keywords across content types, or track incremental updates directly via natural language prompts.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** api-first, content-architecture, sitemap-management, digital-experience, content-delivery

## Description

Connecting this MCP lets your agent treat the Agility CMS like a direct database interface—but without writing complex API calls. Instead of manually navigating sitemap APIs or digging through page ID documentation, you simply ask your AI client for what you need. You can map out how all your digital channels are structured using nested tree views, or pull up specific module definitions for any given page layout. Need to audit content? Your agent handles that too; it can count total entries in a list of authors or products, search those lists by keyword, and even fetch the full payload for an article body if you know its ID. When working with complex CMS data like this, Vinkius makes sure your AI client gets access to all these architectural tools through one unified connection.

## Tools

### get_page_layout
Pulls the structural modules and layout definitions for one given page ID.

### get_site_flat_router
Gets the complete and exact flat list of all available CMS routes/pages.

### count_reference_items
Gets the total item count for any defined CMS reference list.

### get_media_gallery
Retrieves a specific media asset group mapping containing photos and galleries.

### get_single_item
Retrieves a full content item payload, such as an article body, using its unique content ID.

### get_site_tree
Retrieves the nested sitemap architecture for a specified digital channel name.

### list_content_items
Lists multiple content items, pulling them from an Agility CMS Reference list (e.g., blog posts).

### search_content_reference
Searches for specific keywords inside a designated Content Reference List.

### sync_incremental_items
Retrieves content items that have been updated since the last synchronization token, starting with 0 for a full backup.

### sync_incremental_pages
Gets all pages that were modified since the last sync token; start with 0 to fetch everything.

## Prompt Examples

**Prompt:** 
```
Get the flat sitemap for our website to see all registered routes.
```

**Response:** 
```
I've fetched the flat router map. You currently run 42 routes on your primary 'website' channel. The latest pages registered are '/about/team' (Page ID 108) and '/products/new-launch' (Page ID 109).
```

**Prompt:** 
```
Search the 'blog_posts' reference list for the keyword 'announcement'.
```

**Response:** 
```
I found 3 matching items in 'blog_posts' containing 'announcement'. The most recent one is 'Q3 Product Announcement' (Item ID 4512). Would you like me to fetch the full content payload for this article?
```

**Prompt:** 
```
Retrieve the full page layout and modules for page ID 12.
```

**Response:** 
```
Here is the layout breakdown for Page ID 12 (Home Page). It uses the 'StandardTemplate'. There are 4 UI modules mapped in the 'MainContentZone': Hero Banner, Features Grid, Testimonials, and Call to Action.
```

## Capabilities

### Map Site Structure
Fetch the full nested sitemap tree or generate a complete flat list of every CMS route.

### Audit Content Counts
Determine the total number of items in specific content reference lists, such as articles or authors.

### Fetch Page Blueprints
Retrieve the exact structural modules and layout definitions used on a single page ID.

### Search Content Archives
Filter large content lists by specific keywords or criteria within the Headless CMS environment.

### Sync Content Changes
Get only the pages or items that have been updated since your last sync token, minimizing data transfer.

## Use Cases

### Checking Site Coverage
An SEO specialist needs to know if a new product category was correctly linked into the main site structure. They run get_site_flat_router and immediately see all registered routes, confirming that no necessary pages were missed.

### Debugging Page Components
A frontend developer is integrating a custom page template but can't figure out the module mapping. They run get_page_layout for the target page ID and get a clear list of available UI components to use.

### Finding Specific Content
A content manager needs to find all articles mentioning 'Q3 pricing' across 500 blog posts. They run search_content_reference on the 'blog_posts' list, narrowing down the results instantly.

### Updating Data Pipelines
A data engineer is building a content ingestion pipeline and only wants to process records modified since yesterday. Running sync_incremental_items ensures the job runs quickly without downloading gigabytes of old data.

## Benefits

- Stop guessing how deep your sitemap goes. Use get_site_tree to visualize the nested architecture of any channel, so you always know where a route lives.
- When building frontends, don't waste time on documentation. Call get_page_layout to immediately see the exact UI modules mapped to a page ID.
- Need to audit content volume? Instead of manually counting records, call count_reference_items to instantly get the total size of any list (like authors or products).
- When changes happen frequently, don't pull everything. Use sync_incremental_pages or sync_incremental_items to fetch only what’s changed since your last run.
- If you need a specific article body, use get_single_item with the content ID. It gives you the full payload without needing context about where it lives.

## How It Works

The bottom line is you don't write code to query the CMS; your agent does it on your behalf using this MCP.

1. Provide the MCP with your Agility GUID, target Locale, and API Key credentials.
2. Your AI agent issues a natural language command (e.g., 'Show me all routes for the primary channel').
3. The connection executes the necessary content operation tool and returns structured data describing sitemaps, layouts, or content payloads.

## Frequently Asked Questions

**How do I check if content exists in Agility CMS using list_content_items?**
You use list_content_items to fetch multiple records from a specific reference list. This retrieves the basic metadata for items like blog posts or authors, letting you see what's there.

**What is the purpose of get_site_flat_router?**
get_site_flat_router provides a single, exhaustive list of every CMS route on your site. This is useful for SEO audits when you need to ensure no path has been forgotten.

**How do I find out the total number of product entries?**
Run count_reference_items and specify 'products' as the reference type. It gives you a clean, immediate count without listing every single entry first.

**Can get_site_tree help me understand channel structure?**
Yes, get_site_tree requires you to provide a target channel name and returns the nested sitemap architecture for that specific digital channel.

**How do I use sync_incremental_pages to keep content fresh?**
It fetches pages that have changed since your last token. This mechanism prevents huge data dumps and keeps synchronization fast, which is perfect for large sites with frequent updates.

**What specific details does get_page_layout retrieve for a page ID?**
It maps the entire structural framework of that page. You'll get to know exactly what UI modules are used, which template is running, and how many components fill out key zones.

**How does get_media_gallery help me with site imagery?**
It retrieves specific media asset groups or galleries. Instead of listing every single photo, this tool gives you the mapping details for an entire collection, keeping your queries organized and focused on assets.

**Can I use search_content_reference to narrow down my keyword searches?**
You specify the exact reference list first (like 'authors' or 'products'). The search runs only within that defined content pool, giving you highly accurate and targeted results immediately.

**Can my agent keep track of incremental updates to my CMS items?**
Yes. The agent has tools specifically designed to fetch incremental updates using a sync token. It can request only the CMS items or pages that have changed (created, updated, or deleted) since the last automated sync, optimizing fetch latency.

**How do I find the correct Reference Name to query content?**
Reference Names match the identifiers predefined in your Agility CMS Models architecture (such as 'articles', 'authors', or 'posts'). If you are unsure, ask the agent to scan common variables based on your company's naming conventions.

**Can my agent preview unpublished drafting content?**
That depends on the API Token you supply during the integration. If you provide a Preview API Key, the agent will have read-access to the staging and drafted documents. If you provide a Fetch API key, it will only see published items.