Umbraco & AI Agents
What Happens When You Give an AI Agent Access to Umbraco?
AI agents can now read, write and publish content in Umbraco through the Model Context Protocol. We have run this in production for months. Here is what works, what breaks, and how Umbraco's new semantic search lets an agent find content by meaning, not just keywords.
Curated by Matt Perry
CTO
What Happens When You Give an AI Agent Access to Umbraco?
When you give an AI agent access to Umbraco, it can read your content structure, create and update documents, and publish pages, all through the Umbraco Management API. The agent works through an MCP server, which is a standard way for AI tools to call into systems. Every action runs under an Umbraco API user, so the agent can only do what that user's permissions allow.
That is the short answer. The longer answer is more interesting, because we have been running this setup on our own website for months. This article covers what actually works, what breaks, and how Umbraco's new semantic search changes what an agent can do.
The Building Blocks: MCP, API Users, and the Management API
MCP (Model Context Protocol) is an open standard for connecting AI agents to external systems. Think of it as a universal adapter. Instead of every AI tool needing a custom Umbraco integration, the CMS exposes one MCP server and any compatible client can use it.
Umbraco HQ announced the Umbraco MCP Server at Codegarden in June 2025 and adopted MCP formally in October 2025. It wraps the Umbraco Management API, which shipped in Umbraco 14, and it authenticates using API users, which shipped in Umbraco 15. Nothing here is bolted on. It reuses the permission model Umbraco already had.
Here is how the pieces fit together:
| Layer | What it does | Shipped in |
|---|---|---|
| Management API | REST endpoints for every backoffice operation | Umbraco 14 |
| API users | Machine accounts with scoped permissions | Umbraco 15 |
| MCP server | Translates agent requests into API calls | Announced June 2025 |
| Agent Skills | Task-specific context so agents stop guessing | From October 2025 |
Umbraco calls this whole track "Umbraco in AI", and describes the result as "the agent-ready CMS". It is open source under the MIT licence.
What an Agent Can Actually Do
With the Developer MCP connected, an AI agent can perform real work in your Umbraco instance:
- Read your content model. The agent inspects document types, element types, compositions, and data types before it writes anything
- Create and update content. Draft a page from a brief, populate properties, and set metadata
- Edit inside blocks. Recent Umbraco 17 releases added a document patch endpoint, so an agent can change one block deep inside a Block List rather than rewriting a whole page
- Publish. Push content live, or schedule it
- Read logs. Surface warnings and deprecated properties during a migration
The precision matters more than it sounds. Early agent work in any CMS tends to fail because the model guesses at the schema. Umbraco added JSON Schema support to the Management API specifically so agents can read the exact shape of your content first. That single change moves the failure rate down sharply.
What We Learned Running This in Production
We manage originalobjective.com on headless Umbraco with a Next.js frontend, and we use an AI agent through the Umbraco MCP for real content work. Here is what experience taught us that the documentation does not.
1. Partial updates can destroy content
This is the big one. The Management API has an update endpoint that expects the complete set of property values. Send it a partial payload with just the two fields you wanted to change, and every other property on that document is wiped. On a blog post, that means the entire BlockGrid content disappears.
We learned this the hard way. The fix is simple once you know: use the dedicated property-update operation for partial changes, or read the full document, change what you need in memory, and send the whole thing back. Never send a partial payload to a full-update endpoint.
This is not an Umbraco bug. It is standard REST PUT semantics. But an AI agent reasoning about "update the heading" will not naturally infer it, which is exactly why guardrails matter.
2. Agents need house rules, not just permissions
Permissions stop an agent doing things it should not be allowed to do. They do not stop it doing allowed things badly. We keep a project instructions file that encodes our conventions: standard property names, which compositions to use instead of inventing custom properties, that all styling lives in Settings elements, and UK English throughout.
Umbraco formalised this pattern as Agent Skills, a structure originally from Anthropic and now under the Linux Foundation's Agent AI initiative. Each Skill is a folder with a description plus supporting files, and agents load only the ones they need. Umbraco ships 66+ Skills covering backoffice extension types, with Skills for implementation patterns and content modelling on the way.
3. Small format details cause most failures
A surprising share of failed agent operations come down to formatting, not logic:
- Media picker entries need a valid UUID in the key field, not a readable slug
- Date properties want
2026-08-24 00:00:00, not the ISO format with a T separator - Single-select dropdowns still expect the value wrapped in an array
None of these are hard. They are just invisible until something fails, which is a good argument for testing agent workflows on a staging environment first.
How Semantic Search Changes the Picture
Content management is only half the story. The other half is whether an agent can find the right content in the first place, and that is where Umbraco's search work becomes relevant.
Umbraco Search: a new provider model
Umbraco Search (the Umbraco.Cms.Search package) is a provider-based search architecture. The abstraction layer reached final release in 2026. It gives developers one consistent way to handle full-text querying, filtering, faceting, sorting, language variants, and results that respect protected-content rules, while letting you plug in whichever search engine you want.
Examine stays the default provider. Umbraco plans to bring Umbraco Search into the CMS core from version 19, eventually replacing the built-in search.
Umbraco AI Search: finding content by meaning
Umbraco AI Search (Umbraco.AI.Search) builds on that abstraction to add semantic vector search. Semantic search finds content by meaning rather than by matching exact words.
It works in four steps. When you publish content, the indexer extracts the text from your fields. That text is split into chunks and sent to an embedding model, which returns a vector: a long list of numbers representing the meaning of the text. Those vectors are stored in your database. When someone searches, their query goes through the same process, and the system finds content with the closest vectors.
The practical difference:
| Search query | Keyword search | Semantic search |
|---|---|---|
| "deployment guide" | Finds it, exact match | Finds it, meaning match |
| "how to release my site" | Misses it, no shared words | Finds the deployment guide |
| Query in another language | Misses it | Works with multilingual models |
| Typos and abbreviations | Usually misses | Understands the intent |
| "pages like this one" | Not possible | Finds similar documents |
The index appears in the backoffice as UmbAI_Search and covers both content and media. It is culture-aware, so Danish content is indexed separately from English. Access protection is enforced at query time, so protected content does not leak into results for users who should not see it.
Where the two connect
This is the part that makes the combination genuinely useful. Umbraco AI Search registers a semantic_search tool that AI agents can call directly. So the agent is not just writing content, it can search your existing content by meaning first.
That unlocks workflows that were awkward before:
- Avoiding duplication. Before drafting a new page, the agent checks whether you have already covered the topic under different wording
- Internal linking. The agent finds genuinely related pages to link to, rather than relying on tags someone forgot to maintain
- Content audits. Ask which pages cover a theme, and get an answer based on meaning rather than keyword presence
- Related content. The tool can average a document's embeddings and find nearby ones, so "you might also like" needs no manual tagging
The search tool respects backoffice user permissions and start nodes, so an agent only surfaces what the connected user is allowed to see.
Practical notes on running it
Umbraco AI Search stores vectors in your existing Umbraco database by default, with no external service required. On SQL Server 2025 it uses native vector functions for the similarity maths. On older SQL Server versions and SQLite, it falls back to comparing every vector in .NET, which is fine for a small site but slows down as content grows. For anything substantial you will want SQL Server 2025 or a dedicated vector store, and swapping the store means implementing a seven-method interface.
You also need an embedding-capable AI provider configured, and both Umbraco.AI.Search and the Umbraco.Cms.Search framework it builds on have been through beta, so check current status before committing a production site.
Governance: Keeping a Human in Control
Giving any system write access to your website deserves proper thought. Umbraco has built out governance alongside the agent features, which is the right order.
- Guardrails inspect both the prompts going to the model and the output coming back, before or after generation, so content stays on-brand and sensitive data is not sent to an LLM provider
- Test and run lets you measure agent output against defined standards, catch model regressions, and compare models against mock data before AI touches real content
- Manual approval in the editor Copilot means a person signs off before anything goes live
- Model choice is yours. Umbraco supports a range of providers so you can pick based on budget and compliance needs
Our own practice adds a few habits worth copying. Work on a staging environment before production. Read the current state of a document before you write to it. Change one thing at a time and check the result. Keep backups of complex block structures before major edits.
When NOT to Give an Agent Access to Your CMS
Agent access is not right for every project. Be honest about these cases:
- You have no staging environment. Testing agent workflows directly against production is asking for trouble. Sort the environment first
- Your content model is inconsistent. If similar pages use different property names and ad-hoc structures, an agent will amplify the mess. Tidy the model first, and you will benefit even without AI
- You are in a strict regulatory setting. If content requires legal sign-off before publication, keep the agent to drafting only and remove publish rights entirely
- Nobody on the team can review the output. An agent that writes faster than you can check is a liability, not a saving
- You need one page written once. The setup effort only pays back across repeated work
The pattern that works is narrow permissions plus clear conventions plus a human approving publication. The pattern that fails is broad access with no review.
What Is Coming Next
Umbraco announced further agent capabilities at Codegarden in June 2026:
- Editor MCP, a curated version aimed at editors and marketers rather than developers
- Remote MCP on Umbraco Cloud, hosted by Umbraco with its own authenticated endpoint per project, covered by the existing Cloud data processing agreement, at no extra cost on all Cloud plans
- Umbraco Automate, an open-source drag-and-drop automation engine that runs inside your own infrastructure and can call AI agents as steps, with human approval steps built in
The hosted remote MCP is the significant one for most teams. It removes the local setup that currently limits this to developers, and lets editors connect their preferred AI client with nothing to install.
Getting Started
If you want to try this on your own Umbraco site, a sensible order is:
- Confirm you are on Umbraco 14 or later so the Management API is available, ideally Umbraco 17
- Create an API user with the narrowest permissions that cover the job
- Connect the Developer MCP to an MCP-capable AI client on a staging environment
- Write down your content conventions in a project instructions file, or as Agent Skills
- Start with read-only tasks such as content audits before granting write access
- Add semantic search once the basics are working, so the agent can find content as well as create it
The Honest Summary
Giving an AI agent access to Umbraco works, and it saves real time on repetitive content work. It is not magic. The agent needs an accurate picture of your content model, clear conventions, scoped permissions, and a human checking the output before it goes live.
What makes Umbraco's approach worth paying attention to is that it did not invent a proprietary AI layer. It exposed the APIs and permission model it already had through an open standard, then added governance around the edges. That means you are not locked in, and the safeguards you rely on are the ones you already understand.
Semantic search is what turns this from a writing tool into something more useful. An agent that can only create content adds volume. An agent that can also find content by meaning can help you keep a large site coherent, which is a much harder problem.
We build and maintain headless Umbraco sites with Next.js frontends for UK businesses, including work for organisations such as Bet365, Kohler Mira, Ticketmaster and Stoke-on-Trent City Council. If you are weighing up agent access to your CMS, or want your Umbraco content model tidied up so it is ready for it, we are happy to talk it through.
More in AI Industry Trends
View all
Ready to put AI to work in your business?
Book a free 30-minute discovery call. We will discuss your goals, identify quick wins, and outline a practical plan to get started.
Book a discovery callCurated by Matt Perry
CTO
What Happens When You Give an AI Agent Access to Umbraco?
When you give an AI agent access to Umbraco, it can read your content structure, create and update documents, and publish pages, all through the Umbraco Management API. The agent works through an MCP server, which is a standard way for AI tools to call into systems. Every action runs under an Umbraco API user, so the agent can only do what that user's permissions allow.
That is the short answer. The longer answer is more interesting, because we have been running this setup on our own website for months. This article covers what actually works, what breaks, and how Umbraco's new semantic search changes what an agent can do.
The Building Blocks: MCP, API Users, and the Management API
MCP (Model Context Protocol) is an open standard for connecting AI agents to external systems. Think of it as a universal adapter. Instead of every AI tool needing a custom Umbraco integration, the CMS exposes one MCP server and any compatible client can use it.
Umbraco HQ announced the Umbraco MCP Server at Codegarden in June 2025 and adopted MCP formally in October 2025. It wraps the Umbraco Management API, which shipped in Umbraco 14, and it authenticates using API users, which shipped in Umbraco 15. Nothing here is bolted on. It reuses the permission model Umbraco already had.
Here is how the pieces fit together:
| Layer | What it does | Shipped in |
|---|---|---|
| Management API | REST endpoints for every backoffice operation | Umbraco 14 |
| API users | Machine accounts with scoped permissions | Umbraco 15 |
| MCP server | Translates agent requests into API calls | Announced June 2025 |
| Agent Skills | Task-specific context so agents stop guessing | From October 2025 |
Umbraco calls this whole track "Umbraco in AI", and describes the result as "the agent-ready CMS". It is open source under the MIT licence.
What an Agent Can Actually Do
With the Developer MCP connected, an AI agent can perform real work in your Umbraco instance:
- Read your content model. The agent inspects document types, element types, compositions, and data types before it writes anything
- Create and update content. Draft a page from a brief, populate properties, and set metadata
- Edit inside blocks. Recent Umbraco 17 releases added a document patch endpoint, so an agent can change one block deep inside a Block List rather than rewriting a whole page
- Publish. Push content live, or schedule it
- Read logs. Surface warnings and deprecated properties during a migration
The precision matters more than it sounds. Early agent work in any CMS tends to fail because the model guesses at the schema. Umbraco added JSON Schema support to the Management API specifically so agents can read the exact shape of your content first. That single change moves the failure rate down sharply.
What We Learned Running This in Production
We manage originalobjective.com on headless Umbraco with a Next.js frontend, and we use an AI agent through the Umbraco MCP for real content work. Here is what experience taught us that the documentation does not.
1. Partial updates can destroy content
This is the big one. The Management API has an update endpoint that expects the complete set of property values. Send it a partial payload with just the two fields you wanted to change, and every other property on that document is wiped. On a blog post, that means the entire BlockGrid content disappears.
We learned this the hard way. The fix is simple once you know: use the dedicated property-update operation for partial changes, or read the full document, change what you need in memory, and send the whole thing back. Never send a partial payload to a full-update endpoint.
This is not an Umbraco bug. It is standard REST PUT semantics. But an AI agent reasoning about "update the heading" will not naturally infer it, which is exactly why guardrails matter.
2. Agents need house rules, not just permissions
Permissions stop an agent doing things it should not be allowed to do. They do not stop it doing allowed things badly. We keep a project instructions file that encodes our conventions: standard property names, which compositions to use instead of inventing custom properties, that all styling lives in Settings elements, and UK English throughout.
Umbraco formalised this pattern as Agent Skills, a structure originally from Anthropic and now under the Linux Foundation's Agent AI initiative. Each Skill is a folder with a description plus supporting files, and agents load only the ones they need. Umbraco ships 66+ Skills covering backoffice extension types, with Skills for implementation patterns and content modelling on the way.
3. Small format details cause most failures
A surprising share of failed agent operations come down to formatting, not logic:
- Media picker entries need a valid UUID in the key field, not a readable slug
- Date properties want
2026-08-24 00:00:00, not the ISO format with a T separator - Single-select dropdowns still expect the value wrapped in an array
None of these are hard. They are just invisible until something fails, which is a good argument for testing agent workflows on a staging environment first.
How Semantic Search Changes the Picture
Content management is only half the story. The other half is whether an agent can find the right content in the first place, and that is where Umbraco's search work becomes relevant.
Umbraco Search: a new provider model
Umbraco Search (the Umbraco.Cms.Search package) is a provider-based search architecture. The abstraction layer reached final release in 2026. It gives developers one consistent way to handle full-text querying, filtering, faceting, sorting, language variants, and results that respect protected-content rules, while letting you plug in whichever search engine you want.
Examine stays the default provider. Umbraco plans to bring Umbraco Search into the CMS core from version 19, eventually replacing the built-in search.
Umbraco AI Search: finding content by meaning
Umbraco AI Search (Umbraco.AI.Search) builds on that abstraction to add semantic vector search. Semantic search finds content by meaning rather than by matching exact words.
It works in four steps. When you publish content, the indexer extracts the text from your fields. That text is split into chunks and sent to an embedding model, which returns a vector: a long list of numbers representing the meaning of the text. Those vectors are stored in your database. When someone searches, their query goes through the same process, and the system finds content with the closest vectors.
The practical difference:
| Search query | Keyword search | Semantic search |
|---|---|---|
| "deployment guide" | Finds it, exact match | Finds it, meaning match |
| "how to release my site" | Misses it, no shared words | Finds the deployment guide |
| Query in another language | Misses it | Works with multilingual models |
| Typos and abbreviations | Usually misses | Understands the intent |
| "pages like this one" | Not possible | Finds similar documents |
The index appears in the backoffice as UmbAI_Search and covers both content and media. It is culture-aware, so Danish content is indexed separately from English. Access protection is enforced at query time, so protected content does not leak into results for users who should not see it.
Where the two connect
This is the part that makes the combination genuinely useful. Umbraco AI Search registers a semantic_search tool that AI agents can call directly. So the agent is not just writing content, it can search your existing content by meaning first.
That unlocks workflows that were awkward before:
- Avoiding duplication. Before drafting a new page, the agent checks whether you have already covered the topic under different wording
- Internal linking. The agent finds genuinely related pages to link to, rather than relying on tags someone forgot to maintain
- Content audits. Ask which pages cover a theme, and get an answer based on meaning rather than keyword presence
- Related content. The tool can average a document's embeddings and find nearby ones, so "you might also like" needs no manual tagging
The search tool respects backoffice user permissions and start nodes, so an agent only surfaces what the connected user is allowed to see.
Practical notes on running it
Umbraco AI Search stores vectors in your existing Umbraco database by default, with no external service required. On SQL Server 2025 it uses native vector functions for the similarity maths. On older SQL Server versions and SQLite, it falls back to comparing every vector in .NET, which is fine for a small site but slows down as content grows. For anything substantial you will want SQL Server 2025 or a dedicated vector store, and swapping the store means implementing a seven-method interface.
You also need an embedding-capable AI provider configured, and both Umbraco.AI.Search and the Umbraco.Cms.Search framework it builds on have been through beta, so check current status before committing a production site.
Governance: Keeping a Human in Control
Giving any system write access to your website deserves proper thought. Umbraco has built out governance alongside the agent features, which is the right order.
- Guardrails inspect both the prompts going to the model and the output coming back, before or after generation, so content stays on-brand and sensitive data is not sent to an LLM provider
- Test and run lets you measure agent output against defined standards, catch model regressions, and compare models against mock data before AI touches real content
- Manual approval in the editor Copilot means a person signs off before anything goes live
- Model choice is yours. Umbraco supports a range of providers so you can pick based on budget and compliance needs
Our own practice adds a few habits worth copying. Work on a staging environment before production. Read the current state of a document before you write to it. Change one thing at a time and check the result. Keep backups of complex block structures before major edits.
When NOT to Give an Agent Access to Your CMS
Agent access is not right for every project. Be honest about these cases:
- You have no staging environment. Testing agent workflows directly against production is asking for trouble. Sort the environment first
- Your content model is inconsistent. If similar pages use different property names and ad-hoc structures, an agent will amplify the mess. Tidy the model first, and you will benefit even without AI
- You are in a strict regulatory setting. If content requires legal sign-off before publication, keep the agent to drafting only and remove publish rights entirely
- Nobody on the team can review the output. An agent that writes faster than you can check is a liability, not a saving
- You need one page written once. The setup effort only pays back across repeated work
The pattern that works is narrow permissions plus clear conventions plus a human approving publication. The pattern that fails is broad access with no review.
What Is Coming Next
Umbraco announced further agent capabilities at Codegarden in June 2026:
- Editor MCP, a curated version aimed at editors and marketers rather than developers
- Remote MCP on Umbraco Cloud, hosted by Umbraco with its own authenticated endpoint per project, covered by the existing Cloud data processing agreement, at no extra cost on all Cloud plans
- Umbraco Automate, an open-source drag-and-drop automation engine that runs inside your own infrastructure and can call AI agents as steps, with human approval steps built in
The hosted remote MCP is the significant one for most teams. It removes the local setup that currently limits this to developers, and lets editors connect their preferred AI client with nothing to install.
Getting Started
If you want to try this on your own Umbraco site, a sensible order is:
- Confirm you are on Umbraco 14 or later so the Management API is available, ideally Umbraco 17
- Create an API user with the narrowest permissions that cover the job
- Connect the Developer MCP to an MCP-capable AI client on a staging environment
- Write down your content conventions in a project instructions file, or as Agent Skills
- Start with read-only tasks such as content audits before granting write access
- Add semantic search once the basics are working, so the agent can find content as well as create it
The Honest Summary
Giving an AI agent access to Umbraco works, and it saves real time on repetitive content work. It is not magic. The agent needs an accurate picture of your content model, clear conventions, scoped permissions, and a human checking the output before it goes live.
What makes Umbraco's approach worth paying attention to is that it did not invent a proprietary AI layer. It exposed the APIs and permission model it already had through an open standard, then added governance around the edges. That means you are not locked in, and the safeguards you rely on are the ones you already understand.
Semantic search is what turns this from a writing tool into something more useful. An agent that can only create content adds volume. An agent that can also find content by meaning can help you keep a large site coherent, which is a much harder problem.
We build and maintain headless Umbraco sites with Next.js frontends for UK businesses, including work for organisations such as Bet365, Kohler Mira, Ticketmaster and Stoke-on-Trent City Council. If you are weighing up agent access to your CMS, or want your Umbraco content model tidied up so it is ready for it, we are happy to talk it through.
More in AI Industry Trends
View allReady to put AI to work in your business?
Book a free 30-minute discovery call. We will discuss your goals, identify quick wins, and outline a practical plan to get started.
Book a discovery callFrequently Asked Questions
Can an AI agent publish content in Umbraco without approval?
It can if you grant it publish permission, but you should not. The safer setup gives the agent rights to create and update drafts only, leaving publication to a person. Umbraco's editor Copilot includes a manual approval step for exactly this reason, so an editor always signs off before anything goes live.
What is the Umbraco MCP server?
The Umbraco MCP server is an open-source bridge between AI assistants and the Umbraco Management API. MCP stands for Model Context Protocol, an open standard for connecting AI agents to external systems. It lets tools such as Claude, Cursor and GitHub Copilot read your content structure and perform real actions, all scoped by Umbraco's existing permission model.
Which Umbraco version do I need for AI agent access?
You need Umbraco 14 or later, because that is when the Management API shipped. API users, which the agent authenticates as, arrived in Umbraco 15. In practice you want Umbraco 17 or later, since recent releases added JSON Schema support and a document patch endpoint that let agents make precise edits inside blocks instead of rewriting whole pages.
What is the difference between Umbraco Search and Umbraco AI Search?
Umbraco Search (the Umbraco.Cms.Search package) is a provider-based architecture that gives developers one consistent way to handle querying, filtering, faceting and sorting, whichever search engine sits underneath. Umbraco AI Search (Umbraco.AI.Search) is an add-on built on top of it that adds semantic vector search, so content is found by meaning rather than exact keywords.
How does semantic search help an AI agent manage content?
Umbraco AI Search registers a semantic_search tool that agents can call directly. That means the agent can find existing content by meaning before it writes anything. In practice this prevents duplicate pages, produces better internal linking, and supports content audits based on what pages actually mean rather than which keywords they happen to contain.
What is the biggest risk of giving an agent CMS access?
The most common technical risk is accidental data loss from partial updates. Umbraco's full-update endpoint expects every property value, so sending only the fields you changed wipes the rest, including BlockGrid content. Use the dedicated property-update operation for partial changes. The broader risk is publishing unreviewed content, which scoped permissions and a human approval step solve.
Subscribe to the AI Growth Newsletter
Get weekly AI insights, tools, and success stories — straight to your inbox.
Here’s what you’ll get when you subscribe::
- AI for SMBs – adopt AI without big budgets or complex setup
- Future Trends – what’s coming next and how to stay ahead
- How to Automate Your Processes – save time with workflows that run 24/7
- Customer Service AI – chatbots and agents that delight customers
- Voice AI Solutions – smarter calls and seamless accessibility
- AI News – how to stay ahead of the ever changing AI world
- Local Success Stories – how AI has changed business in the UK.
No spam. Just practical AI tips for growing your business.
Get AI insights like this every week
Get AI insights like this every week
Subscribe Free