Agility CMS MCP Server | Agility Docs

The Agility CMS MCP Server connects AI assistants directly to your Agility CMS instances, letting you manage content through natural-language conversations. It implements the Model Context Protocol (MCP) — an open standard supported by Claude, ChatGPT, GitHub Copilot, Cursor, Windsurf, Gemini, and other MCP-compatible clients.

Ask your AI assistant to model content, create pages, bulk-edit items, audit your schema, publish updates, or run a multilingual migration — and it calls the right Agility Management APIs on your behalf, always within your existing permissions.

Endpoint: https://mcp.agilitycms.com/api/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.0
Status: Generally Available — v2.0.0
Docs & one-click install: mcp.agilitycms.com

What's new in 2.0

Version 2.0 grows the toolset from 20 to 27 tools and adds full authoring and publishing workflows — with a human-in-the-loop confirmation model for anything destructive.

Publishing & workflow — new manage_content_workflow and manage_page_workflow tools publish, unpublish, approve, decline, or request approval for content items and pages.
Delete support — new delete_content_item, delete_page, and delete_media tools, each gated behind explicit confirmation.
Media library browsing — list_media lists assets (paged) and returns the Edge (CDN) URL; pairs with the existing upload flow and the new delete_media.
Identity check — get_current_user is a read-only "whoami" that confirms which user the active token authenticates as (it never returns credentials).
Human-in-the-loop confirmation — publish, unpublish, and delete actions are confirmed before they run. On clients that support MCP elicitation, you get a real "Are you sure?" / "type DELETE" prompt in your own UI.
Safer authoring — save_page now validates zone names against the page template (instead of silently dropping mismatched modules), linked-content reference names are normalized to their canonical case, and permission denials surface as clear messages without ever leaking your token.

There are no breaking changes to the tools that existed in 1.0. Existing setups keep working — you simply gain the new tools.

Available tools

The server exposes 27 tools across five categories. Each tool is annotated so MCP clients know whether it only reads data or can modify your instance. Destructive actions (publish, unpublish, delete) ask for confirmation before they run — see Confirmation for destructive actions.

Discovery & setup

Tool	What it does
`get_available_instances`	Lists the Agility instances you can access
`get_current_user`	Identifies the user the current token authenticates as (read-only whoami)
`get_locales`	Returns the locale codes configured for an instance
`get_containers`	Lists content containers (content lists and single items)

Models & schema

Tool	What it does
`get_content_models`	Lists content model definitions
`get_component_models`	Lists component (page module) model definitions, including Agility's built-in components
`get_content_model_details`	Returns the full field schema for a content model
`get_component_model_details`	Returns the full field schema for a component model (always includes the numeric model ID)
`save_content_model`	Creates or updates a content model
`save_component_model`	Creates or updates a component model
`save_container`	Creates or updates a container

Content

Tool	What it does
`get_content_items`	Retrieves a list of items from a container, with filtering and pagination
`get_content_item`	Fetches one or more items by ID (batch supported)
`save_content_items`	Creates or updates one or more content items in a single batch. Returns each item's `contentID` and a ready-made editor URL.
`manage_content_workflow`	Publishes, unpublishes, approves, declines, or requests approval for items (publish/unpublish are confirmed)
`delete_content_item`	Deletes one or more content items (confirmed — type `DELETE`)

Pages & sitemaps

Tool	What it does
`get_sitemaps`	Lists all sitemaps (channels) for an instance
`get_sitemap`	Retrieves a specific sitemap, with depth/path filtering and flat mode
`get_page`	Retrieves a page by ID, including zones, SEO, and dynamic config
`get_page_models`	Lists available page models (templates), with zone definitions
`save_page`	Creates or updates a page — static, dynamic, folder, or link (validates zone names)
`reorder_page_modules`	Reorders the modules within a page zone
`manage_page_workflow`	Publishes, unpublishes, approves, declines, or requests approval for pages (publish/unpublish are confirmed)
`delete_page`	Deletes one or more pages (confirmed — type `DELETE`)

Media

Tool	What it does
`initialize_media_upload`	Starts a media upload and returns a temporary signed URL to POST the file to
`list_media`	Lists assets in the media library (paged), returning the Edge (CDN) URL — find a `mediaID`, spot duplicates
`delete_media`	Deletes a media asset by `mediaID` (confirmed — type `DELETE`)

Confirmation for destructive actions

Actions that change what's live or remove data are gated:

Action	Confirmation
`delete_content_item`, `delete_media`, `delete_page`	Type `DELETE` to proceed
`manage_content_workflow` / `manage_page_workflow` — `publish` / `unpublish`	A yes/no "Are you sure?" prompt
`approve` / `decline` / `request-approval`	Not gated (low risk)

How an action is confirmed depends on what your MCP client supports (negotiated at connection):

Client permission prompt. These tools are annotated as destructive, so MCP clients prompt before running them ("Allow this tool to run?"). Choosing "always allow" in your client opts out of that prompt for that tool — that's a client-side setting, not something the server can override.
Server elicitation (true human gate). On clients that support MCP elicitation (e.g. Claude Code), the server renders the confirmation form (yes/no, or "type DELETE") in your own UI — a gate the AI assistant can't satisfy on its own.
No elicitation → your Agility permissions enforce. On clients that don't support elicitation, the action runs with your own OAuth token and the Agility Management API enforces your permissions — if your account can't publish or delete, the API denies it. The response notes that no interactive prompt was shown (humanConfirmed: false).

Installation

The hosted server uses the streamable-HTTP endpoint https://mcp.agilitycms.com/api/mcp. On first connection your client opens a browser window to authenticate with Agility via OAuth — no API keys or passwords to copy around.

Fastest path: visit mcp.agilitycms.com/instructions for one-click install buttons (VS Code, Cursor, and more) and copy-paste setup for every supported client.

One-click install

For supported editors, a single click adds the hosted server and kicks off the OAuth sign-in:

VS Code — vscode:mcp/install deep link
VS Code Insiders — vscode-insiders:mcp/install deep link
Cursor — cursor://anysphere.cursor-deeplink/mcp/install deep link
LM Studio — https://lmstudio.ai/install-mcp deep link

Grab the buttons from mcp.agilitycms.com/instructions. For everything else, use the manual steps below.

Claude (Desktop & Web)

Open Settings → Connectors (or Custom Connectors).
Add a new connector with the URL:
```
https://mcp.agilitycms.com/api/mcp
```
Complete the OAuth sign-in when prompted. The Agility tools appear in your tool menu.

Claude Code (CLI)

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

Gemini CLI

Add the server with a single command:

gemini mcp add --transport http agility-cms https://mcp.agilitycms.com/api/mcp

Or add it manually to ~/.gemini/settings.json:

{
  "mcpServers": {
    "agility-cms": {
      "httpUrl": "https://mcp.agilitycms.com/api/mcp"
    }
  }
}

On first connection, follow the OAuth flow to grant access. Run /mcp inside Gemini CLI to confirm the Agility tools are loaded.

Cursor

Open Settings → MCP → Add new MCP server.
Choose the HTTP transport and enter:
```
https://mcp.agilitycms.com/api/mcp
```
Authenticate via OAuth when prompted.

Windsurf

Open Settings → Cascade → MCP Servers → Add Server.
Use the HTTP/streamable transport with the endpoint:
```
https://mcp.agilitycms.com/api/mcp
```

Google Antigravity

In an Agent session, open the "…" dropdown at the top of the side panel → MCP Servers.
Add a server with the HTTP endpoint:
```
https://mcp.agilitycms.com/api/mcp
```
Complete the OAuth sign-in when prompted.

ChatGPT

In a context that supports MCP connectors, add the server URL:

https://mcp.agilitycms.com/api/mcp

Note: Custom MCP connectors in ChatGPT require a Pro plan or a Business/Enterprise/Education workspace, and are currently usable in Deep Research mode.

Local / stdio (advanced)

For clients that launch a local process instead of connecting over HTTP, the package can be run via npx:

{
  "mcpServers": {
    "agility-cms": {
      "command": "npx",
      "args": ["-y", "agility-mcp-server"]
    }
  }
}

Authentication

The server uses OAuth 2.0 with short-lived access tokens. You sign in through Agility's standard login, and the server acts strictly within your existing permission boundaries — it can only see and change what your account is allowed to. No passwords are ever stored by the MCP server.

Field type support

The model and content tools understand Agility's full field catalog, including:

Basic: text, multi-line text, HTML/rich text, numbers, booleans, dates
Selection: dropdowns, checkbox lists, link fields
Media: image attachments, file attachments, image galleries
Relationships: linked content (shared and nested), with companion text/value fields for searchable lists

When creating or updating models, include all relevant field properties — undefined properties are treated as empty or null.

Working with media

Media uploads use a secure signed-URL flow rather than embedding file bytes in the conversation:

Call initialize_media_upload to receive a temporary uploadUrl (valid for 5 minutes).
POST the file to that URL as multipart form-data (field name file).
Use the returned asset URL in an attachment field when you call save_content_items or save_page.

Use list_media to browse the library (and spot duplicates before re-uploading), and delete_media to remove an asset by its mediaID.

Publishing & workflow

save_content_items always saves to the instance's default workflow state (typically Staging) — a state value passed on save is not honored, and the tool flags this in its response. To take content live or move it through approval, use manage_content_workflow (publish, unpublish, approve, decline, request-approval). Pages follow the same pattern with manage_page_workflow.

For User Selectable linked-content fields, the stored value is the linked container's reference name. The editor matches that name case-sensitively, so the server normalizes whatever case you supply to the container's canonical case from get_containers on save (and returns the canonical case on read) — preventing the "dropdown renders blank" problem.

Example use cases

Content modeling — "Create a BlogPost model with a title, hero image, rich-text body, and author reference."
Page composition — "Build a /pricing landing page with a hero, a 3-up feature grid, and a CTA."
Bulk operations — "Update every BlogPost missing a meta description and set one based on the intro paragraph."
Content auditing — "List all content models and flag fields that aren't used by any container."
Multilingual workflows — "Show me which pages exist in en-us but are missing in fr-ca."
Migration — "Create these 30 product items from the spreadsheet I'm describing."
Publishing — "Publish content items 272 and 273." (you'll be asked to confirm)
Cleanup — "Delete the test articles I just created, and remove any duplicate uploads from the media library."

Support

Documentation & setup: mcp.agilitycms.com
Tool catalog: mcp.agilitycms.com/tools
Help & feedback: support@agilitycms.com
Source: github.com/agility/agility-mcp-server