Skip to content
MarcusK00Public

About

One MCP connection for your Umbraco 17 or 18 site. Umbrella orchestrates the official MCP tools for each Umbraco product the site has installed, through a NuGet add-on and npm server. Currently supports: CMS, Automate, Engage & Forms MCP Servers

Topics

Resources

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

Umbrella logo

Umbrella

NuGet downloads

One MCP server for your Umbraco site. Umbrella detects which Umbraco products the site has installed and gives your AI tool (Claude Code, Codex, Antigravity, VS Code, Cursor, Claude Desktop) the tools for exactly those products.

Package Where it runs What it does
Umbraco.Community.Umbrella (NuGet) In your Umbraco site Detects installed products, serves GET /umbraco/management/api/v1/mcp/capabilities, adds MCP health checks, and the Umbrella dashboard with the config for each AI tool
umbrella-mcp (npm) On your machine, started by your AI tool Stdio MCP server: CMS tools always, Forms, Automate and Engage tools when the site has them. Tools are prefixed cms--, forms--, automate--, engage--; get-mcp-health explains what loaded and why

The site only needs the NuGet package, but installing it doesn't connect your AI tool. Each person connects their own: on Settings → Umbrella → Overview, New connection creates their API user, its access and its client secret, and hands over the config for their AI tool (Get started). The AI tool then starts umbrella-mcp with npx, which downloads it the first time.

Using Claude Code, Codex or Antigravity? Install the plugin (Claude Code, Codex or Antigravity) instead of editing a config file. For Claude Code, there is nothing to download by hand:

claude plugin marketplace add MarcusK00/Umbrella#v17/main
claude plugin install umbrella@umbrella --config base_url=https://your-site --config client_id=umbraco-back-office-mcp

Then run /plugin configure umbrella@umbrella in Claude Code to add the client secret, which it keeps in your system's credential store. See Codex plugin and Antigravity plugin for Codex and Antigravity install commands.

Contents

How it works

Animation: an AI tool starts umbrella-mcp, which asks the Umbraco site which products are installed, loads CMS, Forms and Automate but not Engage, which isn't installed, and hands their prefixed tools back to the AI tool

  1. The add-on finds each product by its assembly and checks that its Management API is live.
  2. When your AI tool starts umbrella-mcp, the server signs in as an Umbraco API user and asks the site which products it has.
  3. It loads the CMS tools, plus the tools of every detected product, and prefixes each tool with its product (forms--list-forms).
  4. The server's MCP instructions tell the agent which prefix to use for which kind of request, and every tool description starts with its product, for example [Umbraco Forms] ….

Without the add-on, the server still starts, with CMS tools only. Details for contributors: docs/architecture.md.

Get started

You need Umbraco 17, and Node.js 22.23.4 or later (24.22.1 or later on Node 24, 26.12.1 or later on Node 26) on the machine that runs your AI tool.

  1. Install the add-on in your site and restart it:

    dotnet add package Umbraco.Community.Umbrella
  2. Create the connection. In the backoffice, open Settings → Umbrella → Overview and click New connection in Access per API user. Each person, or each AI agent, that uses an AI tool with the site gets an API user of their own (see Teams, editors and hosted sites), and the panel creates it in three steps:

    • Details: a name for the person or agent. The client id is suggested from it (umbraco-back-office-<name>).
    • Access: per product, Defaults (follow the tool permission defaults, also when they change later) or Off, Read-only, No deletes or Full for this user only. Below that, the user groups: the panel preselects groups that grant the sections the products need, never Administrators, and warns when a product's section is missing.
    • Review: check it and click Create API user. Umbrella creates the API user, its client credentials and its access through Umbraco's own user endpoints.

    The panel then shows the client secret, once: copy it. Umbraco stores only its hash and Umbrella doesn't store it at all. Below it is the config for the person's AI tool:

    AI tool Where it goes
    Claude Code .mcp.json in the folder you open in Claude Code
    Claude Code (command) a claude mcp add command to run in that folder; Claude Code keeps it in your own settings
    Claude Code (plugin) two commands that install the Umbrella plugin, for every folder you open in Claude Code
    Claude Desktop claude_desktop_config.json (Claude Desktop: Settings → Developer → Edit Config)
    VS Code .vscode/mcp.json
    Cursor .cursor/mcp.json
    Codex (plugin) commands to add the Codex plugin and export the site and client id
    Antigravity (plugin) command to install the Antigravity plugin
    Other clients the generic mcpServers config

    The config is filled in with the address you opened the backoffice on and the new client id. Send the secret separately from the config. You can close the panel any time; the user is listed in Access per API user as Not connected yet until its MCP server starts.

    Without access to the Users section, you can't create API users, so New connection isn't shown. Ask someone who has it to use New connection, or to create the API user in Users → Create → API user, with client credentials (a client id and a secret of their choice) and user groups that grant the sections of the products the AI should use. Then open Connect an AI tool on the Overview (click Show steps if it is closed), pick that API user and your AI tool, and copy the config.

  3. Supply the secret. The config never contains the secret, only a way to supply it:

    • VS Code asks for it when the server starts.
    • The Claude Code plugin asks for it when you run /plugin configure umbrella@umbrella in Claude Code, and keeps it in your system's credential store.
    • The Antigravity plugin prompts for it (along with the site URL, client id and certificate check setting) when you enable the plugin in Customizations → Installed or /plugin.
    • Claude Code (.mcp.json) and Cursor read it from the UMBRELLA_CLIENT_SECRET environment variable.
    • The Codex plugin reads UMBRACO_CLIENT_SECRET (together with UMBRACO_BASE_URL and UMBRACO_CLIENT_ID) from your environment.
    • The claude mcp add command, Claude Desktop and other clients have a placeholder: replace it with the secret. That config then contains the secret, so keep it out of source control.

    To set the environment variable on macOS / Linux (add it to your shell profile to keep it):

    export UMBRELLA_CLIENT_SECRET="<the client secret>"

    Windows (PowerShell; applies to programs you start afterwards):

    setx UMBRELLA_CLIENT_SECRET "<the client secret>"

    Restart your AI tool afterwards: it only sees variables that were set before it started.

  4. Start it. Restart or reload your AI tool and approve the umbraco server when it asks. npx downloads and starts umbrella-mcp.

  5. Check it works. If the New connection panel is still open, it says when the AI tool has connected and which products it loaded. Ask the AI to call get-mcp-health: it sums up what the API user can use, and lists each product, whether its tools loaded, and how many. In the backoffice, Settings → Umbrella → Overview shows the API user the server connected as, whether it can reach each product, and what to fix if not.

The config

Every tab on the Overview is a variant of this config:

{
  "mcpServers": {
    "umbraco": {
      "command": "npx",
      "args": ["-y", "umbrella-mcp@17.1.2"],
      "env": {
        "UMBRACO_BASE_URL": "https://your-site",
        "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
        "UMBRACO_CLIENT_SECRET": "<your client secret>"
      }
    }
  }
}
  • Version: the config pins umbrella-mcp to the add-on's version: the two packages are released together with the same version number. After upgrading the add-on, change the version in your config; the Overview, the "MCP client setup" check and get-mcp-health say when they differ.
  • HTTPS: UMBRACO_BASE_URL must be https://, because the Management API token endpoint rejects plain HTTP. Open the backoffice over HTTPS to get the right address in the config.
  • Local sites: for a site on localhost the config sets NODE_TLS_REJECT_UNAUTHORIZED=0, because Node does not trust the ASP.NET Core development certificate. This turns off certificate checks for the MCP server process only, and only when the site is on the local machine.

Claude Code plugin

In Claude Code (the terminal, the VS Code and JetBrains extensions, and the Desktop app's Code tab) you can connect without editing a config file. This repository is a Claude Code plugin marketplace, and its Umbrella plugin starts umbrella-mcp with the site and API user you give it. The client secret goes to your system's credential store, not into a file.

  1. Install the plugin. Claude Code fetches it from GitHub, so there is nothing to download by hand. The Overview's Claude Code (plugin) option shows these two commands with your site and client id filled in:

    claude plugin marketplace add MarcusK00/Umbrella#v17/main
    claude plugin install umbrella@umbrella --config base_url=https://your-site --config client_id=umbraco-back-office-mcp

    Inside Claude Code, /plugin marketplace add MarcusK00/Umbrella#v17/main and then /plugin install umbrella@umbrella do the same and ask for each value.

  2. Add the secret. In Claude Code, run /plugin configure umbrella@umbrella. It asks for the client secret and hides it as you type. The same command changes the other values later. After a New secret on the Overview, run it again with the new one.

  3. Start it. Restart Claude Code, or run /reload-plugins. /mcp lists the server as plugin:umbrella:umbraco.

The plugin also adds /umbrella:health, which calls get-mcp-health and explains what loaded and what to fix.

Value Meaning
base_url The site's https:// address
client_id The API user's client id. Default umbraco-back-office-mcp
client_secret The API user's client secret. Kept in your system's credential store
tls_reject_unauthorized 1 (the default) checks the site's HTTPS certificate. 0 turns the checks off for this MCP server: only for a site on your own machine with the ASP.NET Core development certificate. The Overview's command sets it for a localhost site
  • Updates: Claude Code doesn't update plugins from this marketplace on its own unless you turn auto-update on (/plugin → Marketplaces). After upgrading the add-on, run claude plugin marketplace update umbrella and claude plugin update umbrella@umbrella, then restart Claude Code.
  • Version: the marketplace follows v17/main, so it installs the latest 17.x release. If your site runs an older add-on, the Overview and get-mcp-health note that the versions differ. To install a specific release instead, add the marketplace from its release tag, for example MarcusK00/Umbrella#v<version>.
  • One site per install: the plugin keeps one set of values. For a second site, use the claude mcp add command from the Overview.
  • Claude Code only: Claude Desktop's chat, Cursor and VS Code's own MCP settings don't load Claude Code plugins. Use their configs from the Overview; Codex and Antigravity have their own plugin setups below.

Codex plugin

This repository is also a Codex plugin marketplace (.agents/plugins/marketplace.json), and plugins/umbrella/.codex-plugin/plugin.json packages the umbraco MCP server and the $health skill for Codex CLI and the ChatGPT desktop app.

  1. Install the plugin. The Overview's Codex (plugin) option shows these commands with your site and client id filled in:

    codex plugin marketplace add MarcusK00/Umbrella#v17/main
    codex plugin add umbrella@umbrella
  2. Set the environment variables. Codex forwards UMBRACO_BASE_URL, UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, and (for a localhost site) NODE_TLS_REJECT_UNAUTHORIZED=0 to umbrella-mcp:

    export UMBRACO_BASE_URL=https://your-site
    export UMBRACO_CLIENT_ID=umbraco-back-office-mcp
    export UMBRACO_CLIENT_SECRET="<the client secret>"

    Add those exports to your shell profile so Codex sees them across sessions, then restart Codex.

  3. Check it. Ask Codex to run $health (or call get-mcp-health). After upgrading the add-on, run codex plugin marketplace upgrade umbrella and reinstall umbrella@umbrella.

Antigravity plugin

plugins/umbrella/.antigravity-plugin/plugin.json and plugins/umbrella/mcp_config.json package the umbraco MCP server and the /health skill for Google Antigravity (CLI, IDE and desktop app).

  1. Install the plugin. The Overview's Antigravity (plugin) option shows the install command and the values to enter:

    agy plugin install https://github.com/MarcusK00/Umbrella/tree/v17/main/plugins/umbrella

    From a local checkout of this repository, agy plugin install ./plugins/umbrella installs the same bundle.

  2. Configure and enable it. Open Customizations → Installed (or run /plugin in the Antigravity CLI) and enable umbrella. Antigravity prompts for four variables:

    Variable Meaning
    UMBRACO_BASE_URL The site's https:// address
    UMBRACO_CLIENT_ID The API user's client id (for example umbraco-back-office-mcp)
    UMBRACO_CLIENT_SECRET The API user's client secret
    NODE_TLS_REJECT_UNAUTHORIZED 1 to verify HTTPS certificates, or 0 only for a localhost site using the ASP.NET Core development certificate
  3. Check it. Restart or reload, then run /health (or ask Antigravity to call get-mcp-health). To update after upgrading the add-on, run agy plugin install again from the release branch or checkout.

Teams, editors and hosted sites

Several people, or several AI agents, can work on the same site at once. Each connects as its own API user, and each API user can have its own access per product:

Animation: a dev agent, a content agent and an ops agent connect to the same site through umbrella-mcp, each as its own API user. The dev agent has full access; the content agent can list forms but gets no delete tool for pages; the ops agent runs an automation and asks get-mcp-health what it can use. A table then shows each agent's access per product.

Overview dashboard: connection status, default permissions per product, and one row per API user with Client setup and New connection

Give each person who connects an AI tool their own API user:

  • Why one each: the Overview's Access per API user table shows each API user that connected, and Tool Permissions can give each one their own settings. People who share an API user share its settings and show up as one user.
  • Setting someone up: on Settings → Umbrella → Overview, click New connection, name the person, pick their access and groups, and create it. Copy the client secret and the config for their AI tool, and send them separately. For an API user that already exists, use Connect an AI tool: click Show steps, pick that user and copy the config.
  • Looking after an API user: the ⋯ menu on its row in Access per API user has Info (client id, last connection, umbrella-mcp version, user groups, sections and tools per product, with links to its permissions, its config and the user in Users), New secret (replaces a lost or leaked secret and shows the new one once; the old one stops working), Disable API user (its AI tool can no longer sign in; Enable API user undoes it) and Forget connection (drops the row; the API user is not deleted). New secret and Disable need access to the Users section.
  • Editors: an editor doesn't need the site's source code. They need Node.js (the versions under Compatibility) and an AI tool, for example Claude Desktop. The Umbrella dashboard is in the Settings section, so someone with access to it sets them up.
  • Hosted sites, such as Umbraco Cloud: the MCP server runs on each person's machine and connects to the site over HTTPS, so it works with any environment. Open the dashboard on the environment the AI tools should use, so the config gets its address. Tool settings and the connection list are stored in that environment's database, so each environment has its own; create the API users on the environment the AI tools connect to.
  • Shared repositories: a .mcp.json committed to a repository holds one client id, so everyone who uses it signs in as the same API user. Use a plugin (Claude Code, Codex or Antigravity) or the claude mcp add command instead, which each tool keeps in each person's own settings, or keep .mcp.json out of the repository.

Tool settings are guardrails, not access control: see Known limitations.

Configuration

Site (appsettings.json)

Setting Default Meaning
Umbraco:Mcp:ClientId umbraco-back-office-mcp The client id the config on Settings → Umbrella → Overview starts with when no API user is picked yet. The "MCP API user" check does not use it: it reports on whichever API user the MCP server connected as

MCP server (environment variables)

Variable Meaning
UMBRACO_BASE_URL, UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET The site (https://) and the API user to sign in as. Required: the server exits without them
UMBRACO_MCP_MODULES Force modules on without detection, for example forms,automate
UMBRACO_TOOL_MODES, UMBRACO_INCLUDE_/EXCLUDE_TOOLS Toolkit filters. Unprefixed entries apply to CMS; forms:<value> targets a module; forms:* means no restriction for that module. In the two *_TOOLS lists you can also use the visible name, for example cms--delete-document or forms--list-forms
UMBRACO_READONLY true registers only read-only tools, for every module. To do this for one product, use the Umbrella dashboard
UMBRACO_NO_DESTRUCTIVE true leaves out the destructive tools, for every module. To do this for one product, use the Umbrella dashboard
UMBRACO_INCLUDE_SLICES, UMBRACO_EXCLUDE_SLICES Apply to every module

UMBRACO_INCLUDE_TOOL_COLLECTIONS and UMBRACO_EXCLUDE_TOOL_COLLECTIONS were removed in 17.1.0: choose tool groups in Tool Permissions.

Filters match the products' own tool names, before the prefix is added. For example, to leave out the Forms tool that deletes forms (the tool groups are chosen on the dashboard):

"env": {
  "UMBRACO_EXCLUDE_TOOLS": "forms--delete-form"
}

The command npx -y umbrella-mcp@<version> --list-tools, run with the same environment variables, prints the tool names the server would register and exits.

Tool permissions

Per-user tool permissions: set site-wide defaults or customise Off, Read-only, No deletes or Full per product for each API user

Tool groups and individual tools: toggle entire groups or single tools on and off, with Read-only and Destructive badges

Settings → Umbrella → Tool Permissions sets which tools the MCP server exposes. On the left you pick whose settings you edit: Defaults (every API user) or one API user. On the right, each product the site has installed has a card with an access setting, four steps from least to most:

  • Off: the MCP server doesn't load the product at all. Your AI tool sees none of its tools, and the server's instructions don't mention it. get-mcp-health notes that it was switched off in the backoffice. Umbraco CMS can't be switched off, because the MCP server signs in through it.
  • Read-only: only tools marked read-only (the ones that list and fetch), so the AI can look at that product but not change it.
  • No deletes: leaves out the tools the product marks as destructive (destructiveHint), so the AI can create and edit but not delete. That is mostly deletes, emptying recycle bins and terminating runs, plus removing and disconnecting Automate steps, Automate version rollback, running a Forms record action, and a few Engage switches and permission changes. Unpublishing, moving to the recycle bin, and CMS and Forms version rollback are not flagged, so they stay available.
  • Full: every tool in the groups that are switched on, the default.

Under the access setting, a bar shows how many of the product's tools the AI tool gets, for example 242 of 375 tools. Tool groups: X of Y switched on opens one switch per tool group (for example Umbraco Forms → Prevalue source). Switch a group off to stop exposing its tools. Fewer tools means less context for the AI and better tool choice. Each group shows how many tools stay at the chosen access, for example 6 of 14. Open a group (Show the tools in …) to see its tools with their descriptions and Read-only / Destructive tags, and untick single tools to switch them off; the group then shows, for example, 13 of 14 tools and a 1 off tag, and the bar notes which tools are switched off (Switch them on undoes it). A tool that the chosen access already removes is shown disabled with the reason (Not offered at Read-only. or Removed by No deletes.), and your choice is kept, so it comes back when the access allows it again. Switching a group off and on again keeps the tools you switched off. Filter groups and tools searches both. For one API user, Customise copies the defaults' switched-off tools too. A product with many groups gets a filter, and Switch all on / Switch all off apply to the groups shown.

  • Unsaved changes: while the page differs from what is saved, the footer at the bottom says Unsaved changes with Discard changes and Save. Changing something back makes the page clean again. Leaving with unsaved changes (another tab, another API user, another part of the backoffice) asks first; closing or reloading the browser tab gets the browser's own prompt.
  • On by default: every group starts ticked. Untick the ones you don't want; once you save a product, the saved list is used from then on.
  • When it applies: the next time the MCP server starts. Reconnect it in your AI tool after saving.
  • Before the first start: Tool Permissions has no tool groups until an MCP server has started once, because the server reports its tool groups when it starts.
  • The access setting always applies: it only removes tools, so the environment can't undo it. A product switched off stays off even when UMBRACO_MCP_MODULES forces it on. UMBRACO_READONLY=true makes every product read-only and UMBRACO_NO_DESTRUCTIVE=true removes destructive tools from every product, whatever the dashboard says.
  • If the site can't be read: when the MCP server can't read the site's settings it can't apply the dashboard's access settings, so set UMBRACO_NO_DESTRUCTIVE=true (or UMBRACO_READONLY=true) in the AI tool's config to enforce it regardless.
  • Older servers: an MCP server from before the No deletes step ignores it, one from before Off loads the product anyway, and one older than 17.1.0 still offers the tools switched off one by one. The Overview warns when that is the case (for example 1 tool is switched off, but the MCP server of … is older and still offers them), and the card notes it; update the server version in each AI tool's config. The version notes on the Overview and in get-mcp-health flag a server that isn't the add-on's version. When the last report has no counts for No deletes, the card warns that the MCP server still includes destructive tools.
  • Not a security control: anyone with the API user's credentials can call the Management API directly. Use the API user's groups and sections to limit what it can do.

The settings and the reported tool groups are stored in the umbracoKeyValue table, so they survive restarts and are shared by every server of a load-balanced site. Changing them needs access to the Settings section.

Different settings per API user

When each developer has their own API user, the tool settings can differ per user. The list on the left starts on Defaults: the settings you see and save there are the defaults every API user follows. Pick one API user to give it its own settings. Users with their own settings show how many products they have their own settings for, for example 2 own.

  • Customise: for a single API user, a product that follows the defaults is shown as a one-line summary with a Follows defaults tag and a Customise for {name} button. Customising starts that user's own access and groups for the product from a copy of the current defaults, tagged Own settings, and says when its access differs from the defaults. Use the defaults drops them again, and Use the defaults for everything at the top drops all of that user's own settings. Saving stores the customised products as that user's own settings; the others keep following the defaults, also when you change the defaults later.
  • No section access: for a single API user, a product whose section none of its user groups grant isn't listed: its MCP server doesn't load that product, whatever the access says. The Overview's access table shows it as No access. Grant the section to one of its groups in Users to give it access.
  • Per product, all or nothing: an own setting holds a product's groups and access together. A user can't follow the default groups with its own access.
  • Any API user: every API user on the site can be picked, also one that has never connected, so you can set up a new developer before their first start. Disabled API users aren't listed; enable one again (⋯ → Enable API user on the Overview) to edit its settings. Under a default, the card names the users that have their own settings for that product.
  • When it applies: the next time that user's MCP server starts, so they reconnect it in their AI tool. get-mcp-health says when the settings are the user's own ("for this API user").
  • Counts: for a single API user, the tool counts come from that user's own last start. A user whose MCP server hasn't started yet shows its groups and access without counts until it has, because the counts depend on each API user's permissions (the CMS tools in particular). A product that was off for the user isn't in its last report, so its groups come from the defaults until the user's server starts with it on. Under Defaults, each group shows the highest count any API user's MCP server reported.
  • Overview: Settings → Umbrella → Overview starts with a status banner: Everything is working, Ready to connect, or how many things need attention, grouped by products, MCP server and API users, with notes such as an older umbrella-mcp (one line per version, naming its users) behind an info toggle, with the add-on and umbrella-mcp versions and the last connection. Access per API user is a table with a column per product: the first row is the defaults, then each connected API user by name, and per product its access and the number of tools its last start got (a dot marks the user's own settings), the total, and No access (no tools, not counted in the total) when its groups don't grant a product's section. Each column header shows the product's version. Users made with New connection are listed straight away, marked Not connected yet, until their MCP server first starts. Edit defaults and Edit permissions open Tool Permissions with the defaults or that user picked; ⋯ has Info, New secret, Disable API user and Forget connection (see Teams, editors and hosted sites). A product that is installed but that an API user's MCP server didn't load at its last start (although it is on for that user and the user has its section) is a warning under products; ask the AI to call get-mcp-health for the reason.

Health checks

Settings → Health Check → MCP has three checks:

  • MCP products: which Umbraco products the add-on detected, their versions, whether their Management APIs are available, and whether the connected MCP servers loaded them.
  • MCP API user: every API user the MCP server has connected as, whatever its name or client id: when it last connected, whether it can still sign in, and which detected products its sections reach. A missing section is not reported as a problem: an API user for content only doesn't need Automate or Engage. Its MCP server doesn't load those products, and get-mcp-health says so. The MCP server connects once when your AI tool starts it, so until then the check only says no MCP server has connected yet. A stdio MCP server has no lasting connection, so the check shows the last connection, not whether one is open right now. Connections are stored in the umbracoKeyValue table.
  • MCP client setup: whether each connected API user's MCP server is the add-on's version.

The checks show short rows with the same findings as Settings → Umbrella → Overview, which has the details and the config to copy. The "MCP client setup" description points there, once for the whole group.

In your AI tool, the get-mcp-health tool shows what the server loaded and why: the add-on's status, the Umbraco version check, each product with its tool count and issues, and notes on what to fix, including when the server is not the add-on's version.

Troubleshooting

Start with get-mcp-health in your AI tool and the MCP health checks in the backoffice. They cover most of the cases below.

If none of this explains it, open an issue with the add-on and umbrella-mcp versions and the get-mcp-health output. Report security vulnerabilities privately, see the security policy.

Symptom Likely cause Fix
The server exits with Could not reach Umbraco at … Nothing answered at UMBRACO_BASE_URL: the site is not running, or the host or port is wrong. The code in brackets (ECONNREFUSED, ENOTFOUND, …) says which Start the site, or fix UMBRACO_BASE_URL, then reconnect the MCP server
The server exits with Umbraco refused the API user's token request Wrong client id or secret; the API user is disabled; or UMBRACO_BASE_URL is http:// Check UMBRACO_CLIENT_ID and UMBRACO_CLIENT_SECRET. The URL must be https://. The "MCP API user" check shows whether the user can still sign in
The server exits with Could not authenticate against Umbraco The first call to the site failed for another reason; the error after the message has the details Check the three UMBRACO_* values and the site's log
Authentication fails although the secret is right, or the server exits with Error: UMBRACO_CLIENT_SECRET is required. UMBRELLA_CLIENT_SECRET was not set when your AI tool started, so the server received the literal text ${UMBRELLA_CLIENT_SECRET}, or nothing Set the variable, then restart the AI tool (not just the MCP server)
The Overview's config has the wrong client id The API user picker is on another user, or no API user has a client id yet Pick the API user under Connect an AI tool. Only API users with client credentials are listed
There's no New connection button, and the ⋯ menu has no New secret or Disable Your backoffice user has no access to the Users section, so it can't create or change API users Ask someone with access to the Users section to use New connection, or to create the API user in Users; then use Connect an AI tool
New connection says the API user could not be created Umbraco refused it: often a user group you aren't a member of yourself (only administrators can give any group), or a name or client id that is taken Use Back to Access or Back to Details, change it, and create again. Groups you can't assign are marked in the panel
The client secret is lost or leaked Umbraco stores only its hash, so it can't be shown again ⋯ → New secret on the user's row makes a new one; the old one stops working. Put the new one into the AI tool
The server exits with Error: UMBRACO_BASE_URL is required. (or another variable) The MCP client config has no env entry for it Use the config from Settings → Umbrella → Overview
With the Claude Code plugin, /mcp doesn't list plugin:umbrella:umbraco A required value, usually the client secret, isn't set yet, so Claude Code doesn't start the server Run /plugin configure umbrella@umbrella in Claude Code, then /reload-plugins
With the Codex plugin, umbraco doesn't start or exits with a missing variable UMBRACO_BASE_URL, UMBRACO_CLIENT_ID or UMBRACO_CLIENT_SECRET isn't exported in Codex's launch environment Export them in your shell profile (NODE_TLS_REJECT_UNAUTHORIZED=0 for localhost too), then restart Codex
With the Antigravity plugin, umbrella stays disabled or doesn't start Required variables aren't filled in yet, or NODE_TLS_REJECT_UNAUTHORIZED isn't set Enable umbrella in Customizations → Installed (or /plugin) and fill in all four variables (1, or 0 for localhost)
The server exits with its HTTPS certificate was not accepted, or other TLS errors such as self-signed certificate Node does not trust the site's certificate. The config from the Overview only turns checks off for localhost Trust the certificate with NODE_EXTRA_CA_CERTS=<path to the .pem>, or for a local development host only, add NODE_TLS_REJECT_UNAUTHORIZED=0 to env
Only cms-- tools are listed The add-on is not installed or not reachable, or a product is not installed, not enabled, or not on major version 17 get-mcp-health gives the reason per product. "MCP products" in the backoffice shows what the site detected
One product's tools are missing although it is installed It is switched Off in Settings → Umbrella → Tool Permissions, in the defaults or for this API user get-mcp-health notes "Switched off in the backoffice". Set its access to another step and reconnect
A product's tools are missing, and get-mcp-health says the user groups don't grant its section The API user's groups don't grant that product's section, so the MCP server leaves it out If the user should have it, grant the section to one of its groups and reconnect. The "MCP API user" check names the section
"MCP client setup", the dashboard or get-mcp-health says the versions differ Your AI tool's config still pins the umbrella-mcp of an earlier add-on Set umbrella-mcp@<add-on version> in the config
Tool Permissions shows "No tool groups reported yet" No MCP server has started against this site yet Start it once from your AI tool, then reload the dashboard. If it stays empty, get-mcp-health notes why the tool groups could not be reported
Dashboard changes have no effect The server reads the settings when it starts Reconnect the MCP server

Compatibility

Component Version
Umbraco CMS 17.x (.NET 10)
Node.js 22.23.4+, 24.22.1+ or 26.12.1+
Umbraco Forms, Umbraco Automate, Umbraco Engage 17.x
@umbraco-cms/mcp-server-sdk 1.0.0-beta.48 (one copy shared by all products)
@umbraco-cms/mcp-dev 17.6.13
@umbraco-forms/mcp 17.7.0
@umbraco-automate/mcp 17.6.0
@umbraco-engage/mcp 17.5.0

Known limitations

  • Tool names are prefixed (cms--get-document), so they differ from the standalone CMS MCP's names.
  • Tool settings, per API user or for everyone, are guardrails applied by the MCP server on each developer's machine, not access control. Anyone with an API user's credentials can call the Management API directly, so the API user's Umbraco permissions (groups and sections) are the boundary.
  • Only --list-tools is supported as a CLI flag; --describe-tool is not implemented.
  • Collection filters do not pull in dependent collections (for example media does not add temporary-file) the way the standalone CMS MCP does.

Develop

The repository has the add-on in src/Umbraco.Mcp, the server in npm/, and a demo site with Forms, Automate and Engage in demo-site/.

dotnet test Umbraco.Mcp.slnx
cd npm && npm install && npm test && npm run build

Setup from scratch, the demo site, and the end-to-end checks: docs/development.md.

License

MIT

About

One MCP connection for your Umbraco 17 or 18 site. Umbrella orchestrates the official MCP tools for each Umbraco product the site has installed, through a NuGet add-on and npm server. Currently supports: CMS, Automate, Engage & Forms MCP Servers

Topics

Resources

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages