Visit Agility Academy to take courses and earn certifications. It's free, and you can learn at your own pace. Learn More

Agility CMS MCP Server

The Agility CMS MCP Server provides a bridge between AI assistants and your Agility CMS environment, enabling content management through natural language conversations. Built on the Model Context Protocol standard, it allows developers and content teams to work with their CMS directly from tools like Claude, GitHub Copilot, ChatGPT, Cursor, and Windsurf.

You can keep reading more below, or you can explore it directly here: https://mcp.agilitycms.com/

Overview

The MCP server exposes 14 tools that give AI assistants authenticated access to your Agility CMS instances. You can discover available instances, explore content models and component schemas, retrieve and manage content items, work with multilingual content across different locales, and upload media assets—all through conversational prompts rather than writing API code.

Key Features

Discovery & Setup: List available instances, locales, and containers
Schema Management: Inspect and manage content and component models
Content Operations: Retrieve, create, and update content items
Media Management: Upload assets from base64 data URIs
Multi-Instance Support: Work across different Agility CMS instances
Locale Support: Manage multilingual content seamlessly

How It Works

The server acts as an intermediary between your AI assistant and the Agility CMS Management API. When you make a request in natural language, your AI assistant:

Identifies the appropriate MCP tool to use
Authenticates using your OAuth credentials
Executes the operation against your Agility CMS instance
Returns the results in a readable format

All operations are performed securely using OAuth 2.0 authentication, ensuring your content remains protected within your established permission boundaries.

Getting Started

Prerequisites

An active Agility CMS account
An AI assistant that supports the Model Context Protocol (Claude Desktop, Cursor, Windsurf, ChatGPT, etc.)

Installation

Claude Desktop

Open your Claude Desktop configuration file:
Add the Agility CMS MCP server:

{
  "mcpServers": {
    "agility-cms": {
      "transport": {
        "type": "http",
        "url": "https://mcp.agilitycms.com/api/mcp"
      }
    }
  }
}

Restart Claude Desktop
Look for the 🔨 icon to confirm the server is connected

Claude Code (CLI)

Run the following command in your terminal:

claude mcp add --transport http "Agility-CMS" https://mcp.agilitycms.com/api/mcp

Cursor

Open Cursor Settings → Features → Model Context Protocol
Add a new server with:

Windsurf

Open Windsurf Settings → MCP Servers
Add a new configuration:

{
  "mcpServers": {
    "agility-cms": {
      "transport": {
        "type": "http",
        "url": "https://mcp.agilitycms.com/api/mcp"
      }
    }
  }
}

Authentication

On first use, the MCP server will redirect you to authenticate with your Agility CMS account:

Click the OAuth authorization link provided by your AI assistant
Log in to your Agility CMS account
Authorize the MCP server to access your instances
Copy the success token back to your AI assistant

Your authentication token is stored securely and will be used for all subsequent requests.

Available Tools

Discovery & Setup

get_available_instances

Lists all Agility CMS instances accessible to your account.

Parameters: None

Returns: Array of instances with guid, name, and defaultLocale

Example Usage:

"Show me all my Agility CMS instances"

get_locales

Retrieves available locales for a specific instance.

Parameters:

instanceGuid

Returns: Array of locale codes (e.g., ["en-us", "fr-fr"])

Example Usage:

"What locales are available for instance abc-123?"

get_containers

Lists all content containers (both list and single item containers) for an instance and locale.

Parameters:

instanceGuid
locale

Returns: Array of containers with referenceName, type, and contentDefinition

Example Usage:

"Show me all containers for my blog instance in English"

Modeling & Schema

get_content_models

Lists all content type definitions for an instance.

Parameters:

instanceGuid

Returns: Array of content models with id and referenceName

Example Usage:

"List all content models in my instance"

get_component_models

Lists all page module (component) definitions for an instance.

Parameters:

instanceGuid

Returns: Array of component models with id and referenceName

Example Usage:

"What page modules are available?"

get_content_model_details

Retrieves detailed information about a specific content model, including all field definitions.

Parameters:

instanceGuid
modelId

Returns: Complete model schema with fields, labels, descriptions, and settings

Example Usage:

"Show me the full schema for the BlogPost content model"

get_component_model_details

Retrieves detailed information about a specific component model, including all field definitions.

Parameters:

instanceGuid
modelId

Returns: Complete component schema with fields, labels, descriptions, and settings

Example Usage:

"Get details for the Hero component"

save_content_model

Creates a new content model or updates an existing one.

Parameters:

instanceGuid
model

Returns: Created/updated model with id and referenceName

Example Usage:

"Create a new content model called 'Product' with fields for name, price, and description"

Notes:

Supports all 20+ Agility CMS field types
Include field validation, help text, and default values as needed
Reference names must be unique within the instance

save_component_model

Creates a new component model or updates an existing one.

Parameters:

instanceGuid
model

Returns: Created/updated component with id and referenceName

Example Usage:

"Create a Hero component with headline, subheadline, and background image fields"

Content Retrieval

get_content_items

Retrieves multiple content items from a container with optional filtering and pagination.

Parameters:

instanceGuid
locale
containerReferenceName
take
skip
filter
sort

Returns: Array of content items with all field values

Example Usage:

"Get the first 10 blog posts from the 'posts' container" "Fetch all products where category equals 'Electronics'"

get_content_item

Retrieves a single content item by its ID.

Parameters:

instanceGuid
locale
contentID

Returns: Complete content item with all field values

Example Usage:

"Get content item 12345 from the English locale"

Content Management

save_container

Creates a new container or updates an existing one.

Parameters:

instanceGuid
container

Returns: Created/updated container details

Example Usage:

"Create a new list container called 'testimonials' using the Testimonial content model"

Notes:

Container types:
Must reference an existing content model

save_content_items

Creates or updates one or more content items in a container.

Parameters:

instanceGuid
locale
containerReferenceName
items

Returns: Array of saved items with their contentID values

Example Usage:

"Create 5 blog posts with titles and content from this CSV data" "Update the featured product with a new price and description"

Notes:

Include
Omit
Validates against the container's content model schema
Supports all field types including attachments, linked content, and nested grids

Media & Assets

upload_media_asset

Uploads a media file to the Agility CMS media library from a base64-encoded data URI.

Parameters:

instanceGuid
dataUri
fileName
groupingId

Returns: Uploaded asset details including mediaID and CDN URL

Example Usage:

"Upload this image to my media library" "Convert this base64 image to a media asset"

Notes:

Supports common image formats (JPEG, PNG, GIF, WebP, SVG)
Supports documents (PDF, DOC, DOCX)
Supports video files (MP4, MOV, AVI)
Maximum file size depends on your Agility CMS plan

Field Type Support

The MCP server supports all Agility CMS field types:

Basic Fields

Text: Single-line text input
Long Text: Multi-line text area
HTML: Rich text editor content
Boolean: True/false checkbox
Integer: Whole numbers
Decimal: Floating-point numbers
Date: Date/time values

Selection Fields

Dropdown List: Single selection from options
Link Field: Page links (internal/external)
Search Listbox: Searchable dropdown
Checkboxes: Multiple selection

Media Fields

Image Attachment: Single image upload
File Attachment: Single file upload
Image Gallery: Multiple images
Attachment List: Multiple files

Content Relationship Fields

Shared Content Link: Reference to shared content
Shared Content Grid: Multiple shared content references
Nested Content Link: Embedded content item
Nested Content Grid: Multiple embedded items

Security

Authentication

All requests require OAuth 2.0 authentication. The MCP server:

Never stores your password
Uses short-lived access tokens
Respects your Agility CMS permission levels
Operates within your established security boundaries

Best Practices

Keep your authentication tokens secure
Use the MCP server only from trusted AI assistants
Regularly review your OAuth authorizations in your Agility CMS account
Revoke access if you suspect unauthorized use

Use Cases

Content Migration

Bulk-migrate content from spreadsheets, databases, or other CMS platforms using natural language instructions.

"Import these 100 products from this CSV file into the products container"

Schema Management

Create and update content models without navigating through the Agility CMS interface.

"Add a 'featured' boolean field to the BlogPost content model"

Content Auditing

Analyze and report on your content structure and data.

"Show me all blog posts published in the last 30 days" "List all content models that have an image field"

Multilingual Content

Manage translations and locale-specific content efficiently.

"Copy all blog posts from en-us to fr-fr and mark them for translation"

Batch Operations

Perform bulk updates across multiple content items.

"Update all products in the 'Electronics' category to set inStock to true"

Content Modeling

Design and iterate on content structures quickly.

"Create a complete e-commerce content model with products, categories, and reviews"

Troubleshooting

Authentication Issues

Problem: "OAuth token expired or invalid"

Solution: Re-authenticate by clicking the OAuth link provided by your AI assistant

Problem: "No instances found"

Solution: Verify you have access to at least one Agility CMS instance in your account

Tool Errors

Problem: "Container not found"

Solution: Verify the container reference name is correct using get_containers

Problem: "Content model validation failed"

Solution: Ensure all required fields are included and field types match the model schema

Problem: "Invalid field type"

Solution: Check that field definitions use supported Agility CMS field types

Performance

Problem: Slow responses for large content sets

Solution: Use pagination with take and skip parameters to limit result size

Limitations

Beta Status: This server is currently in beta and may have breaking changes
Rate Limits: Subject to Agility CMS API rate limits
File Size: Media uploads are limited by your Agility CMS plan
Batch Size: Large batch operations may time out; break into smaller chunks
Field Types: Some advanced field configurations may require manual setup

Support

Documentation

Help

For questions or issues with the MCP server, contact:

Email: support@agilitycms.com
Slack Community

Feedback

This is a beta product and we welcome your feedback:

Report bugs and request features via support@agilitycms.com
Share your use cases and success stories in our Slack Community
Suggest improvements to the tool catalog in our Slack Community

Version History

1.0 Beta Release (Current)

14 MCP tools covering core CMS operations
OAuth 2.0 authentication
Support for all major field types
Model and Content Creation
Multi-instance and multi-locale support

Coming Soon

Page and Component Access and Creation
Custom Field types

In this Article:

Was this article helpful?

Agility CMS MCP Server

Overview

Key Features

How It Works

Getting Started

Prerequisites

Installation

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf

Authentication

Available Tools

Discovery &amp; Setup

get_available_instances

get_locales

get_containers

Modeling &amp; Schema

get_content_models

get_component_models

get_content_model_details

get_component_model_details

save_content_model

save_component_model

Content Retrieval

get_content_items

get_content_item

Content Management

save_container

save_content_items

Media &amp; Assets

upload_media_asset

Field Type Support

Basic Fields

Selection Fields

Media Fields

Content Relationship Fields

Security

Authentication

Best Practices

Use Cases

Content Migration

Schema Management

Content Auditing

Multilingual Content

Batch Operations

Content Modeling

Troubleshooting

Authentication Issues

Tool Errors

Performance

Limitations

Support

Documentation

Help

Feedback

Version History

1.0 Beta Release (Current)

Coming Soon

Discovery & Setup

Modeling & Schema

Media & Assets