One of the big challenges when getting started with this project was wrapping my head around how all the moving pieces fit into a heavily agentic workflow: AI in Umbraco versus Umbraco in AI, Umbraco-MCP versus the Management API, and where the backoffice and testing skills come in.

Let's dig into three related but distinct parts of the tooling: the Management API, the Umbraco MCP server, and Umbraco backoffice Skills. They tend to get filed together, which is understandable and also the source of some of the confusion.

They're related, but they aren't three flavors of the same thing. Two do closely related work at different levels of automation. The third operates on an entirely different plane. Let's build a clear mental model of each.

I'll use Claude and Claude Code throughout as my examples, since that's what I'm working with, but none of this is Claude-specific. It applies to any coding agent that can call MCP servers and read SKILL.md files: Cursor, GitHub Copilot, Windsurf, and others.

The Management API: the backoffice's own controls, exposed as code

Everything you can do by clicking around the Umbraco backoffice — creating content, uploading media, editing document types, emptying the recycle bin — the backoffice itself does by calling a REST API under the hood. That's the Management API (/umbraco/management/api/v1/…). It's not a special add-on; it's part of the foundation the backoffice already runs on, made available for you to call from your own code.

Because it's the same power the backoffice has, it can read and write, and it reaches everything: content, media, schema, settings. It's OAuth-authenticated: a privileged, back-office surface, not something you'd expose to the public.

You use it when you want something repeatable and unattended: seeding test content in a staging environment, a batch job that regenerates images across a hundred articles, a script that provisions the same document types every time you spin up a fresh environment. Anything where you want the exact same thing to happen on every run, with no improvisation, belongs here.

A quick aside: there's also a Content Delivery API. This is a different thing: read-only, public-safe access to your published content as JSON, built for headless front-ends (a separate SPA, a mobile app) to consume. It doesn't write anything and doesn't touch schema.

Umbraco MCP: control of the backoffice handed to your LLM

Enter Umbraco MCP: the MCP server is a wrapper over the Management API. It's a set of roughly 200 tools that an LLM like Claude can call directly, and each tool is, under the hood, a Management API call dressed up so an agent can discover and use it without hand-writing HTTP requests, managing OAuth tokens, or paging through results.

So MCP doesn't do anything the Management API can't. The difference is who's using it and how. The Management API is for deterministic code you write and version-control. MCP is for handing that same reach to an agent for exploratory, human-supervised, often one-off work.

Here's the kind of thing MCP is good at: "Add an author field across these six element types." Or getting a quick answer to "What breaks if I delete this node?" — where MCP can trace everything referencing that node in a single move, instead of you clicking through the tree hoping you've found it all. It's great when you don't know the exact steps in advance and want a capable assistant to work them out while you watch.

You wouldn't want an agent improvising writes unattended in a CI pipeline. That's what the Management-API-in-code path is for. The rule of thumb: if you'd be uncomfortable with your LLM making decisions as it goes, script the API directly. If the value is in the LLM figuring out the steps, use MCP.

Umbraco AI Skills: instructions for building on the CMS

The first two tools both operate on a running CMS; they change what content, media, and schema exist in it. Umbraco AI Skills do something entirely different. They're informational markdown files for building with Umbraco, usable by any editor that supports the SKILL.md format.

There are two:

backoffice-skills: knowledge and scaffolding that teaches your LLM to build Umbraco backoffice extensions — dashboards, property editors, TipTap buttons, sections, collections, auth providers, and the plumbing beneath them.

backoffice-testing-skills: knowledge that teaches your LLM to test those extensions — Lit component tests, MSW-mocked APIs, and Playwright E2E via @umbraco/playwright-testhelpers.

These don't touch your CMS data at all. They're bundles of instructions, reference docs, and code patterns that load into the agent's context and teach it how to write the source code that extends the backoffice: the actual TypeScript, C#, and manifest files that make up an Umbraco extension. A Skill is knowledge; the file changes still come from the agent's ordinary Read/Write/Edit tools. Nothing gets called against a live Umbraco instance.

The cleanest way to hold the distinction: MCP and the Management API do things. They change what's in the CMS. Skills inform. They provide instructions that help write the code that extends the CMS.

There are seams where they meet. You might have Skills help you write an extension, and then, when you want to test it against real content, MCP comes in afterward to create test content in the backoffice, act on it, and clean it all up when you're done.

One nice property of Skills: they self-activate. Once they're set up, the moment your work drifts into extension territory — "add a property action to the media picker" — the relevant Skill pulls itself into context without you needing to know it exists.

MCP, Skills, and the Management API: better together

If you're writing Management API scripts and it's working, what does the rest of it buy you?

You don't strictly need any of it. But if you're using an LLM to code or triage, it seems silly not to set them up, because having them connected improves the quality of help you get, even in sessions where the agent never calls a single MCP tool or triggers a single Skill.

Because MCP is a near one-to-one wrapper over the Management API, the list of ~200 tool names is effectively a map of the entire Management API surface. Even when the agent is hand-writing raw HTTP calls and never invoking a tool, those names sitting in context tell it which endpoints exist: that there's an audit log, a reference-checker, a way to list a document type's available compositions. The result is fewer invented endpoints, more correct terminology, and the agent surfacing capabilities you didn't know were there. It's a reference map that happens to also be callable.

Skills give you the same ambient benefit on the extension-development side: their names enumerate every backoffice extension point that exists, so the agent names the right primitive instead of guessing. And because Skills load their code patterns on trigger, they arrive with the correctness details built in, not just the label.

Building in better standards and structure

None of this requires you to change how you work. You can keep writing Management API code by hand, but you're doing it with a better-informed assistant, one that knows the real shape of the surface it's helping you build on. That's the point of the extra tooling: not to bloat your process, but to layer in structure and remove friction from an agentic workflow.