Go from AI that Assists to AI that Acts

You need Node.js 20 or later and a dotCMS user and password. Open a terminal, change to the root folder of your project, and run:

npx dotcms agent setup

Answer three questions:

1. Your dotCMS instance URL

2. How to authenticate

3. Which code editors to connect.

Setup validates the token, adds the dotCMS MCP server to each code editor's configuration, installs the dotCMS skills, and starts the server to confirm it responds. It works with Claude Code, Cursor, VS Code with Copilot, Codex, Antigravity, Devin and OpenCode. No dotCMS instance handy? Try the public demo site at demo.dotcms.com with the user: admin@dotcms.com and password: admin.

Then prompt the agent a first task: "Give me a summary of all the assets in the dotcms instance, then create a content type called Event with a title, a start date and a location."

What you'll learn in this article

• Why agents are multiplying, and what the analysts say about agents that act across systems.

• How the dotCMS MCP Server works: two tools, a sandbox, and dedicated tools for the jobs that need care.

• How to configure an agent for a project, and where to find the READMEs.

• Four personas and the use cases that matter to each: front-end developers, full-stack developers building cross-system agents, administrators and marketing operations, and content authors who work from an agent harness.

• How agent access is governed, and where dotCMS is headed next.

From AI that assists to AI that acts

Developers used to ask AI for one step at a time and review each. Now they hand an agent the end goal and let it plan the steps across several systems. That is where the MCP server comes in, a standard way for an agent to operate a system.

Forrester predicts 30% of enterprise app vendors will launch their own in 2026. The risk is access without control. Forrester's 2026 State of Agentic AI finds more than half of leaders report agents multiplying faster than their governance, and Gartner expects over 40% of agentic AI projects to be canceled by the end of 2027 over costs, unclear value and inadequate risk controls.

dotCMS gives customers the ability to use AI in two ways.

1. dotAI works from inside the CMS, assisting people who create and manage content.

2. The MCP Server and Agent Toolkit let external AI agents operate the CMS under the same API, permissions and workflows your people use.

This article covers the second, mainly for developers. For the first, and the governance behind both, read AI You Can Actually Turn On. For more details on our overall approach, read From AI Assisted to Agent-Ready.

How it works

Two tools instead of a long menu

dotCMS has hundreds of API endpoints, and a tool for each would fill an agent’s context before it started work. So the MCP Server gives the agent two tools. search lets it explore the API specification and read only the endpoints and schemas the task needs. execute runs the script the agent writes in an isolated sandbox, as the user behind your API token. The token stays on the server, out of the agent’s reach, and dotCMS allows only what that user’s role allows.

To streamline complex jobs we built specific tools handle them. page_create, page_place_content and page_verify build a page and check that it actually renders correctly. upload_assets and download_assets move themes and files without passing file contents through the model.

Skills that teach the agent dotCMS

The Agent Toolkit packages what an agent needs to know. It ships two skills. dotcms-best-practices is a reference indexed by intent: create a content type, a page, a template or a container, place content, write VTL, wire a headless Next.js front end, or debug a page that renders blank. dotcms-create-sites plans and builds a complete site in two phases. It interviews you and writes a PLAN.md and a DESIGN.md, then builds and keeps fixing until every page type verifies. Both support VTL-rendered and headless delivery.

Four people, four jobs

The same tool set serves very different people. What follows is what each one does with it, and why that matters.

1. Front-end developers: build, migrate and componentize

The job. You build sites and web applications on dotCMS, or you are moving a site to dotCMS, or you are building components that render dotCMS content. You already work with an AI coding agent in your editor. The problem has been that the agent can’t efficiently do operations in dotCMS. It guesses field names, invents endpoints and produces a page that returns HTTP 200 and renders nothing.

What changes. The agent now knows the platform. The skills carry dotCMS conventions for content types, templates, containers, VTL and headless Next.js. The two MCP tools let it read your actual content model instead of imagining one. And page_verify closes the loop: the agent does not declare victory until the page renders.

Typical work:

• Build a new section from a brief. Describe a content type, a listing page, and a detail page. The agent creates the type, builds the pages, places content, and runs page_verify. If a detail page reports an empty slot because a container template is missing a file, the agent fixes it and re-checks before you open a browser.

• Apply a design system. Point the agent at your design tokens or a DESIGN.md. The site-building skill interviews you, writes a plan, builds the site, uploads the theme with upload_assets and loops until every page type verifies. It works for VTL-rendered sites and for headless front ends.

• Migrate an existing site. You pass the agent a site URL or a screen shot, or both. The agent inspects the source site, proposes a content model, creates the content types, loads content and assets, and builds components to match the existing pages. You review the model and the results at each stage and make the calls that need judgment. The agent handles the repetitive work. You drive the plan: migration is a guided process, not a button.

• Build components for a headless app. The agent reads your real content types and generates components and queries that match them, then creates sample content so you can preview the result right away.

• Check the result. The agent renders each page with page_verify and checks every slot, so an empty page that returns a 200 is caught and explained: nothing placed, a template error, or a stale cache. The accessibility and geo page-scanner endpoints are among those the server surfaces, so the agent can also run a page check as part of the build and report what it finds.

Why it matters. The constraint on AI coding tools is context, and the CMS is where the most important context lives. An agent that can read the content model, create the pieces and verify the output turns the CMS from a black box into part of the build loop. Your team reviews and refines instead of typing out boilerplate.

2. Full-stack developers: build agents that work across systems

The job. You are building an agent, not using one. The agent runs a business process across several systems, and the CMS is one of them. This is where most of the enterprise attention on agentic AI is going: not a chatbot, but a process that used to need people to move information from one tool to the next.

What the dotCMS MCP Server adds. Your agent can talk to the PIM's MCP server, the DAM's MCP server and the dotCMS MCP Server in the same run. In dotCMS it can discover the content type, create or update the record, attach assets, and fire a workflow action that puts the item into review.

An illustrative flow. A product team approves a new product in the PIM. Your agent receives the event, reads the product record, pulls approved images from the DAM, and calls dotCMS to find the Product content type. It creates the product item with the PIM fields mapped to the dotCMS fields, adds the images, drafts marketing copy for the fields the PIM does not supply, and starts the product workflow so a marketer reviews it. A regional editor approves. The publish step stays with the people the workflow names. If the agent's confidence on a field mapping is low, it stops and flags the item instead of saving a guess.

3. Administrators and marketing operations: configure and run the platform

The job. You run dotCMS rather than build on it. You set up sites and languages, manage users and roles, keep tags and categories clean, and keep content types and workflows in good shape as the business changes. Most of this work is high in volume and low in glamour, and it is done through admin screens one record at a time.

What changes. The agent can do the setup and the sweeps, and you review. The MCP Server steers the agent to the administrative surface: sites, languages, users, roles, categories, tags, content types and their fields, workflows, personas and rules, templates, containers and themes.

Typical work:

• Stand up a site. Create a site, set its languages, create its folder structure and a first set of pages from a plan, then verify them.

• Manage people. Create users, assign them to roles, and report on who has which role. Ask the agent which users have not been assigned to any role, then fix them in bulk.

• Clean up taxonomy. Tags and categories drift. Ask the agent to find near-duplicate tags, propose a merge list, and apply the list you approve. Build or reorganize a category tree from a spreadsheet.

• Evolve the content model. Add a field to a content type, or a new content type for a campaign, without clicking through the field editor.

• Run content audits. Find stale content, items with missing metadata, or references to a retired product. Use the page-scanner endpoints to check pages for accessibility issues.

• Set up personalization. Different audiences should see different experiences, but the personas and rules behind that are tedious to set up and easy to leave inconsistent. The agent builds them from a description of who the audience is and what they should see.

• Create or adjust workflows. Approval paths change as the business, the regulations and the teams change. The agent drafts a new or stricter path for a content type, or adjusts an existing one, and you review it before anything uses it.

Where the boundaries are. The server guides the agent to the endpoints that cover common work, but it does not wall off the rest of the API. What the agent can actually do in any area is decided by the role you give it, and dotCMS refuses anything that role is not permitted to do. For administrative work, give the agent a role with the administrative permissions the task needs and no more.

Why it matters. The principle is the same one that applies everywhere else in this article. The agent acts as a user with a role. Give your operations agent a role that can manage tags, categories and users but cannot publish. It gets the speed of automation within a boundary you set the same way you set it for a colleague, and every change shows up in the same history.

4. Content authors who work from an agent harness

The job. You are a content author or content lead who already works in Claude Code, Codex or a similar harness, because that is where your drafting, research and editing happen. The friction is the last mile: copying finished content into dotCMS, filling fields, setting categories, and moving items through approval.

Typical work:

• Move or sync content into dotCMS. Most authors draft in Word or Google Docs, or in the harness itself. The agent takes the finished draft and creates it in dotCMS as the right content type, with the fields, categories and tags filled in, so nobody re-keys it.

• Augment existing content. Find items that need new summaries, metadata or translations and update them.

• Move content through workflows. Submit for review, and, if your role allows it, publish or unpublish.

• Bulk edits. A product was renamed. Find every page and content item that mentions the old name, review the list, and update them through the workflow actions your role has.

• Audit content. Find duplicate, stale and outdated content, such as old pages or a retired product name, and get a ranked list to update, merge or archive.

Governed the way your people are

The first question every technical evaluator and security team asks is what the agent is allowed to do. The answer in dotCMS is the same as for a person.

• Every call runs as the user the API token belongs to. If that user's role cannot publish, neither can the agent. If a role needs approval to publish, the agent's role does too. There is no separate agent policy to maintain.

• The token stays on the MCP server. It is never exposed to the code the agent writes, and sandboxed code has no network access of its own.

• The role is the boundary. The server steers the agent to a curated set of endpoints so it finds the right calls quickly, but it is the permissions of the user behind the token that decide what the agent can do, on every endpoint.

• Changes land in version history. AI-assisted changes carry the identity of the user or token that made them, and any version can be restored.

For any real project, create a dedicated user and role for the agent with only the permissions the project needs, and issue its token. That is how you give a partner team access to one site without exposing others, and how you keep an operations agent away from publishing. This is the "governed identity with a named owner" that Forrester recommends, using controls you already run.

For the full seven-control framework, including model choice, data locality and audit, see AI You Can Actually Turn On.

Is this another tool to learn?

Running an agent well is a skill, and that is true of every MCP server. The toolkit exists to shorten the curve: the setup command removes the configuration work, and the skills carry dotCMS conventions so you do not have to prompt them in every session. Today this is aimed at developers, administrators and technical content teams who already use agents. Marketing teams benefit when a developer or partner builds an agent for them on top of this, and dotAI remains the path for authors who want AI inside the editor.

Where this is going

Models will commoditize. Agent harnesses will change every few months. What lasts is a content platform with explicit schemas, stable APIs, enforceable permissions and a record of what happened, because those are what any capable agent will need. That is the bet behind the dotCMS composable spine, and it is why the MCP Server runs on the same API and the same permissions as everything else.

More skills and agents are on the way, built on the same governed runtime. Planned dotAI capabilities, including admin observability and governance, workflow visibility and feedback, and a content quality agent, are described in From AI Assisted to Agent-Ready. Roadmap items are good-faith estimates, not commitments.

Try it

npx dotcms agent setup

Point it at your instance or at demo.dotcms.com, and ask your agent to create a content type. If you are building your own agent, start with the @dotcms/ai package on npm.

FAQ