umbraco · eshanrnh · Nov 6, 2025 · Nov 5, 2025
diff --git a/16/umbraco-cms/reference/developer-mcp/README.md b/16/umbraco-cms/reference/developer-mcp/README.md
@@ -1,27 +1,26 @@
 ---
-description: Get started with the CMS developer MCP.
+description: Get started with the Umbraco CMS Developer Model Context Protocol (MCP).
 ---
 
-# Developer Model Context Protocol (MCP) server
+# Developer Model Context Protocol (MCP) Server
 
 The Developer [MCP Server](./concepts/model-context-protocol.md#mcp-servers) makes it straightforward for developers to connect AI tools with Umbraco. It allows you to harness large language models (LLMs) to perform almost any task that can be achieved within the Umbraco backoffice. This includes generating and editing content, managing media, automating workflows, and assisting with complex development tasks.
 
-This MCP Server acts as a secure gateway between your Umbraco installation and MCP-compatible AI environments. These include Claude (Desktop or Code), Cursor, or GitHub Copilot and many more.
+This MCP Server acts as a secure gateway between your Umbraco installation and MCP-compatible AI environments. These include Claude (Desktop or Code), Cursor, GitHub Copilot, and many more.
 
-Through this bridge, your AI assistant can interact directly with Umbraco's Management API. This enables a more natural, conversational way to develop and maintain your sites.
+Through this bridge, your AI assistant can interact directly with the Umbraco Management API. This enables a more natural, conversational way to develop and maintain your sites.
 
 {% hint style="info" %}
 Think of it as giving your AI tools a secure, structured way to “speak to Umbraco.”
 {% endhint %}
 
-## How does it work
+## How it works
 
-Unlike most Umbraco integrations, the Developer CMS MCP Server is not a plugin that you install into your Umbraco site.
-Instead, it runs as a standalone Node.js application that acts as an MCP server.
+Unlike most Umbraco integrations, the Developer MCP Server is not a plugin that you install into your Umbraco site. Instead, it runs as a standalone Node.js application that acts as an MCP Server.
 
-[MCP clients](./concepts/model-context-protocol.md#mcp-clients) are implemented inside compatible [host applications](./concepts/model-context-protocol.md#host-applications) such as Claude Desktop, Cursor, or Windsurf. These clients connect to this server. When you interact with your chat-based development environment, the client communicates with the MCP Server using the Model Context Protocol (MCP).
+[MCP clients](./concepts/model-context-protocol.md#mcp-clients) are implemented inside compatible [host applications](./concepts/model-context-protocol.md#host-applications) such as Claude Desktop, Cursor, or Windsurf. These clients connect to the server. When you interact with your chat-based development environment, the client communicates with the MCP Server using the Model Context Protocol (MCP).
 
-Learn more about [Model Context Protocol (MCP)](./concepts/model-context-protocol.md)
+Learn more about [Model Context Protocol (MCP)](./concepts/model-context-protocol.md).
 
 The MCP Server, in turn, talks directly to Umbraco through the Management API. This is the same API layer that powers the Umbraco backoffice and allows the server to directly read from and modify the CMS.
 
@@ -31,70 +30,73 @@ By exposing these endpoints as MCP tools, the Developer MCP Server enables you t
 The MCP Server acts as the bridge between your Umbraco instance and your AI assistant. It translates and adapts your tasks into Management API calls.
 {% endhint %}
 
-## Who is this for?
+## Intended audience
 
-**The Developer MCP Server is designed specifically to be used by Umbraco developers.**
+The Developer MCP Server is designed specifically to be used by Umbraco developers.
 
-While the Model Context Protocol (MCP) can be used for many types of solution, automation, and workflow integrations. This particular MCP Server focuses on developer-oriented tasks and productivity enhancements within Umbraco projects.
+The Model Context Protocol (MCP) can be used for many types of solution, automation, and workflow integrations. This particular MCP Server focuses on developer-oriented tasks and productivity enhancements within Umbraco projects.
 
 Example use cases:
 
-- **Automation of content, media and schema**
+- **Automation of content, media, and schema**
+
 Automate repetitive actions through conversational commands. This includes creating or updating content or media, generating content models, or performing large-scale operations.
 
 - **Developer quality-of-life improvements**
-Speed up tasks that would otherwise take time or require numerous clicks in the backoffice UI. Examples include batch-moving Document Types or Data Types, cleaning up unused entities, or synchronising content structures.
+
+Speed up tasks that would otherwise take time or require numerous clicks in the backoffice UI. Examples include batch-moving Document Types or Data Types, cleaning up unused entities, or synchronizing content structures.
 
 - **Integration into modern development workflows**
-Use the Developer MCP Server alongside other MCP servers such as Playwright MCP, Figma MCP, or GitHub MCP. This streamlines your end-to-end site development process.
 
-- **Leveraging LLM reasoning**  
-Use your LLM to understand, debug, or make better decisions. For example, ask it to interpret entries from Umbraco Logs, suggest schema changes, or explain configuration errors.
+Use the Developer MCP Server alongside other MCP Servers such as Playwright MCP, Figma MCP, or GitHub MCP. This streamlines your end-to-end site development process.
+
+- **Leveraging LLM reasoning**
 
-- [**Plus many, many more**](./scenarios.md)
+Use an LLM to understand, debug, or make better decisions. For example, ask it to interpret entries from Umbraco Logs, suggest schema changes, or explain configuration errors.
+
+- [**And many more**](./scenarios.md)
 
 **Not recommended for non-developers**
 
-While it’s technically feasible for non-developers to connect to Umbraco using this MCP server, we do not recommend it for the following reasons:
+While it’s technically feasible for non-developers to connect to Umbraco using this MCP Server, it is not recommended for the following reasons:
+
+- **Complex setup requirements**
+
+This MCP server must run locally and it requires a configured Umbraco user account with appropriate permissions.
 
-- **Complex setup requirements**  
-This MCP server must be run locally, and it requires a configured Umbraco user account with appropriate permissions.
+- **Powerful tool access**
 
-- **Powerful tool access**  
 Even for users with limited permissions, the MCP Server exposes many management-level tools. Incorrect commands could unintentionally alter or damage your Umbraco instance.
 
 {% hint style="warning" %}
-Do not connect the Developer MCP Server to a production Umbraco environment.   
-Always use a local or isolated development instance.
+Do not connect the Developer MCP Server to a production Umbraco environment. Always use a local or isolated development instance.
 {% endhint %}
 
-We are actively working on additional MCP servers tailored to other roles such as editors and content managers. These will provide safer, simplified toolsets and workflows.
+Additional MCP servers tailored to other roles such as editors and content managers are in development. These will provide safer, simplified toolsets and workflows.
 
 ## Getting started
 
 ### Umbraco Setup
 
 Before connecting the MCP Server, you need to create an [API User](../../fundamentals/data/users/api-users.md) in Umbraco. This user allows the MCP Server to communicate securely with the Management API.
 
-The level of access you assign to this API user determines what actions your AI agent can perform.
-For example:
+The level of access you assign to this API user determines what actions your AI agent can perform:
 
-- A user with Editor permissions can manage and update content but cannot modify Document Types or perform administrative tasks.
-- A user with Administrator permissions grants full access to all capabilities. This includes the ability to create, edit, or delete document types, data types, and more within Umbraco.
+- **Editor permissions:** Manage and update content but cannot modify Document Types or perform administrative tasks.
+- **Administrator permissions:** Full access including the ability to create, edit, or delete Document Types, Data Types, and more within Umbraco.
 
 {% hint style="warning" %}
-Only use a dedicated API user for MCP connections.   
-Do not share or reuse credentials from an existing backoffice user.
+Only use a dedicated API user for MCP connections. Do not share or reuse credentials from an existing backoffice user.
 {% endhint %}
 
 ### Host Setup
 
-Each MCP-compatible host application has its own setup process. For this reason, we provide dedicated setup guides for the main developer environments we see most often:
+Each MCP-compatible host application has its own setup process. Below you can find dedicated setup guides for the main developer environments seen most often:
 
-[Claude Desktop](./host-setup/claude-desktop.md)  
-[Claude Code](./host-setup/claude-code.md)  
-[GitHub Copilot](./host-setup/github-copilot.md)  
-[Cursor](./host-setup/cursor.md)  
+- [Claude Desktop](./host-setup/claude-desktop.md)  
+- [Claude Code](./host-setup/claude-code.md)  
+- [GitHub Copilot](./host-setup/github-copilot.md)  
+- [Cursor](./host-setup/cursor.md)  
 
 Although the details vary slightly, the general pattern is the same across all hosts:
 
@@ -115,13 +117,12 @@ Although the details vary slightly, the general pattern is the same across all h
 
 ```
 
-Add your Umbraco MCP configuration values (Client ID, Client Secret, URL of Umbraco) in the appropriate section of your host setup. Then restart the MCP Server or, in some cases, restart the host application itself.
+Add your Umbraco MCP configuration values (Client ID, Client Secret, and Umbraco URL) in the appropriate section of your host setup. Then restart the MCP Server or, in some cases, restart the host application.
 
 Once restarted, you’ll have access to the full suite of tools available through the Umbraco CMS Developer MCP Server.
 
 {% hint style="info" %}
-This Developer MCP Server requires Node.js version 22 or higher to be installed.  
-You can check your current Node.js version by running node -v in your terminal.
+This Developer MCP Server requires `Node.js` version 22 or higher. Check your current `Node.js` version by running `node -v` in your terminal.
 {% endhint %}
 
 #### Never Use Against Production Environments
@@ -132,11 +133,13 @@ You can check your current Node.js version by running node -v in your terminal.
 The Developer MCP Server provides powerful, direct access to your Umbraco Management API. While this makes it a good tool for development and testing, mistakes can have serious consequences. Misconfigurations or misunderstood commands can cause immediate and potentially destructive damage.
 
 **Always use the Developer MCP Server with:**
+
 - Local development instances only
 - Isolated staging or test environments
 - Environments where data loss or corruption would not impact live users or business operations
 
 **Never connect to:**
+
 - Production websites
 - Live client sites
 - Any environment where content, media, or configuration changes could affect real users
@@ -146,20 +149,14 @@ Even with limited user permissions, the scope and power of LLM-driven actions ma
 
 ### Choosing Your Tools
 
-Your first step after setup should be deciding which tools you want to enable.
-All tools are grouped into collections for easier management and isolation.
-
-[Learn more about Tool Collections](./available-tools.md)
+Your first step after setup should be deciding which tools you want to enable. All tools are grouped into collections for easier management and isolation. [Learn more about Tool Collections](./available-tools.md).
 
-Choosing the right tools improves how efficiently the AI communicates with Umbraco, making each conversation faster and more context-aware.
+Choosing the right tools improves how efficiently the AI communicates with Umbraco, making each conversation faster and more context-aware. [Learn more about Context Engineering](./concepts/context-enginerring.md).
 
-[Learn more about Context Engineering](./concepts/context-enginerring.md)
+### Using npx?
 
-### Why Use npx?
-
-We recommend launching the Developer MCP Server using npx.
-This allows you to run the Node.js application without needing to install anything globally.
-npx will temporarily download the package, execute it, and clean up automatically — ensuring you’re always using the latest version.
+It is recommended to launch the Developer MCP Server using npx. This allows you to run the `Node.js` application without needing to install anything globally.
+npx will temporarily download the package, execute it, and clean up automatically, ensuring you’re always using the latest version.
 
 If you prefer, you can also install it globally with:
 
@@ -173,12 +170,12 @@ For advanced configuration options and environment variable settings, see the [C
 
 ## Working with the MCP Server
 
-Once your MCP server is configured and connected, explore these guides to get the most out of your setup:
+Once your MCP Server is configured and connected, explore these guides to get the most out of your setup:
 
-- [Creating Media](./creating-media.md) - Learn how to upload and manage media items programmatically
-- [Available Tools](./available-tools.md) - Complete reference of all available tools and collections
-- [Scenarios](./scenarios.md) - Real-world examples and use cases
-- [Best Practices](./best-practice/README.md) - Tips for effective MCP usage
+- [Creating Media](best-practice/creating-media.md) - Learn how to upload and manage media items programmatically.
+- [Available Tools](./available-tools.md) - Complete reference of all available tools and collections.
+- [Scenarios](./scenarios.md) - Real-world examples and use cases.
+- [Best Practices](./best-practice/README.md) - Tips for effective MCP usage.
 
 ## Version Compatibility
 
@@ -193,9 +190,8 @@ The Umbraco MCP Server is designed to work with specific major versions of Umbra
 
 The MCP server automatically checks version compatibility on startup:
 
-- **✅ Version Match**: No message displayed, server functions normally
-- **⚠️ Version Mismatch**: The first tool request will fail with an error message asking you to retry if you want to proceed. After you retry, the warning displays once more. It is then never shown again for that session.
+- **✅ Version Match**: No message displayed, server functions normally.
+- **⚠️ Version Mismatch**: The first tool request fails with an error message prompting a retry. After retrying, the warning displays once more and is then suppressed for the rest of the session.
 - **⚠️ API Error**: If the version check API call fails, a warning is displayed once but does not block tool execution.
 
 The version check uses the Umbraco Management API endpoint `/umbraco/management/api/v1/server/information` to detect the connected Umbraco version and compares the major version number.
-