You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 16/umbraco-cms/reference/developer-mcp/README.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ Think of it as giving your AI tools a secure, structured way to “speak to Umbr
19
19
Unlike most Umbraco integrations, the Developer CMS MCP Server is not a plugin that you install into your Umbraco site.
20
20
Instead, it runs as a standalone Node.js application that acts as an MCP server.
21
21
22
-
[MCP clients](./concepts/model-context-protocol.md#mcp-clients)- implemented inside compatible [host applications](./concepts/model-context-protocol.md#host-applications) such as Claude Desktop, Cursor, or Windsurf - 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).
22
+
[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).
23
23
24
24
Learn more about [Model Context Protocol (MCP)](./concepts/model-context-protocol.md)
25
25
@@ -28,7 +28,7 @@ The MCP Server, in turn, talks directly to Umbraco through the Management API. T
28
28
By exposing these endpoints as MCP tools, the Developer MCP Server enables you to perform almost any backoffice action. You can do this through natural language interaction with your LLM-powered chat environment.
29
29
30
30
{% hint style="info" %}
31
-
The MCP Server acts as the bridge between your Umbraco instance and your AI assistant, translating and adapting your tasks into Management API calls.
31
+
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.
32
32
{% endhint %}
33
33
34
34
## Who is this for?
@@ -39,14 +39,14 @@ While the Model Context Protocol (MCP) can be used for many types of solution, a
39
39
40
40
Example use cases:
41
41
42
-
-**Automation of content, media and schema**
43
-
Automate repetitive actions such as creating or updating content or media, generating content models, or performing large-scale content or media operations directly through conversational commands.
42
+
-**Automation of content, media and schema**
43
+
Automate repetitive actions through conversational commands. This includes creating or updating content or media, generating content models, or performing large-scale operations.
44
44
45
-
-**Developer quality-of-life improvements**
46
-
Speed up tasks that would otherwise take time or require numerous clicks in the backoffice UI. For example, batch-moving Document Types or Data Types, cleaning up unused entities, or synchronising content structures across environments.
45
+
-**Developer quality-of-life improvements**
46
+
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.
47
47
48
-
-**Integration into modern development workflows**
49
-
Use the Developer MCP Server alongside other MCP servers such as Playwright MCP, Figma MCP, or GitHub MCP to streamline your end-to-end site development process.
48
+
-**Integration into modern development workflows**
49
+
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.
50
50
51
51
-**Leveraging LLM reasoning**
52
52
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.
@@ -68,7 +68,7 @@ Do not connect the Developer MCP Server to a production Umbraco environment.
68
68
Always use a local or isolated development instance.
69
69
{% endhint %}
70
70
71
-
We are actively working on additional MCP servers tailored to other roles - such as editors and content managers - that will provide safer, simplified toolsets and workflows.
71
+
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.
72
72
73
73
## Getting started
74
74
@@ -80,7 +80,7 @@ The level of access you assign to this API user determines what actions your AI
80
80
For example:
81
81
82
82
- A user with Editor permissions can manage and update content but cannot modify Document Types or perform administrative tasks.
83
-
- A user with Administrator permissions grants full access — including the ability to create, edit, or delete document types, data types and more within Umbraco.
83
+
- 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.
84
84
85
85
{% hint style="warning" %}
86
86
Only use a dedicated API user for MCP connections.
@@ -115,7 +115,7 @@ Although the details vary slightly, the general pattern is the same across all h
115
115
116
116
```
117
117
118
-
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.
118
+
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.
119
119
120
120
Once restarted, you’ll have access to the full suite of tools available through the Umbraco CMS Developer MCP Server.
121
121
@@ -129,7 +129,7 @@ You can check your current Node.js version by running node -v in your terminal.
129
129
{% hint style="danger" %}
130
130
**Critical: Do not connect the Developer MCP Server to a production Umbraco environment.**
131
131
132
-
The Developer MCP Server provides powerful, direct access to your Umbraco Management API. While this makes it an excellent tool for development and testing, it also means that mistakes, misconfigurations, or misunderstood commands can have immediate and potentially destructive consequences.
132
+
The Developer MCP Server provides powerful, direct access to your Umbraco Management API. While this makes it an excellent tool for development and testing, mistakes can have serious consequences. Misconfigurations or misunderstood commands can cause immediate and potentially destructive damage.
133
133
134
134
**Always use the Developer MCP Server with:**
135
135
- Local development instances only
@@ -194,7 +194,7 @@ The Umbraco MCP Server is designed to work with specific major versions of Umbra
194
194
The MCP server automatically checks version compatibility on startup:
195
195
196
196
-**✅ Version Match**: No message displayed, server functions normally
197
-
-**⚠️ 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 is displayed once more and then never shown again for that session.
197
+
-**⚠️ 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.
198
198
-**⚠️ API Error**: If the version check API call fails, a warning is displayed once but does not block tool execution.
199
199
200
200
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.
0 commit comments