Improve README and remove empty host setup files

- Enhanced wording throughout README for clarity and consistency
- Fixed broken internal links to use correct relative paths
- Updated example use cases with more specific details
- Removed empty warp.md and windsurf.md host setup files
- Improved formatting and structure of JSON configuration example
- Added links to related documentation pages

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Phil Whittaker

16/umbraco-cms/reference/developer-mcp/README.md

@@ -19,14 +19,14 @@ Instead, it runs as a standalone Node.js application that acts as an MCP server.
 
 MCP clients—implemented inside compatible 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).
 
-Learn more about [Model Context Protocol (MCP)](./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, allowing it to read from and modify the CMS.
 
 By exposing these endpoints as MCP tools, the Developer MCP Server enables you to perform almost any backoffice action through natural language interaction with your LLM-powered chat environment.
 
 {% hint style="info" %}
-The MCP Server acts as the bridge between your Umbraco instance and your AI assistant, translating and adapting your tasks into real Management API calls.
+The MCP Server acts as the bridge between your Umbraco instance and your AI assistant, translating and adapting your tasks into Management API calls.
 {% endhint %}
 
 ## Who is this for?
@@ -37,32 +37,32 @@ While the Model Context Protocol (MCP) can be used for many types of solution, a
 
 Example use cases
 
-- **Automation of content and models**  
-Automate repetitive actions such as creating or updating content, generating content models, or performing large-scale content operations directly through conversational commands.
+- **Automation of content, media and schema**  
+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.
 
 - **Developer quality-of-life improvements**  
-Speed up tasks that would otherwise take time or multiple clicks in the backoffice UI. For example, batch-moving Document Types or Data Types, cleaning up unused entities, or synchronising content structures across environments.
+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.
 
 - **Integration into modern development workflows**  
 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.
 
 - **Leveraging LLM reasoning**  
-Go beyond automation—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 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.
 
-- **plus many, many more**
+- [**plus many, many more**](./how-best-to-use.md)
 
 **Not recommended for non-developers**
 
-While it’s technically possible 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, we do not recommend it for the following reasons:
 
 - **Complex setup requirements**  
-The server must be run locally, and it requires a configured Umbraco user account with appropriate permissions.
+This MCP server must be run locally, and it requires a configured Umbraco user account with appropriate permissions.
 
 - **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. 
+Do not connect the Developer MCP Server to a production Umbraco environment.   
 Always use a local or isolated development instance.
 {% endhint %}
 
@@ -72,13 +72,13 @@ We are actively working on additional MCP servers tailored to other roles—such
 
 ### Umbraco Setup
 
-Before connecting your MCP Server, you need to create an [API User](../../fundamentals/data/users/api-users) in Umbraco. This user allows the MCP Server to communicate securely with the Management API.
+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:
 
 - 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 — including the ability to create, edit, or delete structural elements within Umbraco.
+- A user with Administrator permissions grants 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.
@@ -88,39 +88,43 @@ Only use a dedicated API user for MCP connections. Do not share or reuse credent
 
 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:
 
-Claude Desktop
-Claude Code
-GitHub Copilot
-Cursor
-Windsurf
+[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:
 
 ``` json
-          "umbraco-mcp": {
-            "command": "npx",
-            "args": ["@umbraco-cms/mcp-dev@beta"],
-            "env": {
-              "NODE_TLS_REJECT_UNAUTHORIZED": "0",
-              "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
-              "UMBRACO_CLIENT_SECRET": "1234567890",
-              "UMBRACO_BASE_URL": "https://localhost:44391",
-              "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "culture,document,media",
-              "UMBRACO_EXCLUDE_TOOLS": "delete-document,empty-recycle-bin"
-            }
-          }
+{
+  "umbraco-mcp": {
+    "command": "npx",
+    "args": ["@umbraco-cms/mcp-dev@beta"],
+    "env": {
+      "NODE_TLS_REJECT_UNAUTHORIZED": "0",
+      "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
+      "UMBRACO_CLIENT_SECRET": "1234567890",
+      "UMBRACO_BASE_URL": "https://localhost:12345",
+    }
+  }
+}
+
 ```
 
-Add your Umbraco MCP configuration values (from your .env file) 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, 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.
 
 Once restarted, you’ll have access to the full suite of tools available through the Umbraco CMS Developer MCP Server.
 
 ### Choosing Your Tools
 
 Your first step after setup should be deciding which tools you want to enable.
-Some tools are grouped into collections for easier management and isolation.
+All tools are grouped into collections for easier management and isolation.
+
+[Learn more about Tool Collections](./mcp-toolkit.md)
+
+Choosing the right tools improves how efficiently the AI communicates with Umbraco, making each conversation faster and more context-aware.
 
-[Learn more about Tool Collections](Learn more about Tool Collections)
+[Learn more about Context Engineering](./concepts/context-enginerring.md)
 
 ### Why Use npx?
 
@@ -136,7 +140,7 @@ npm install -g @umbraco/mcp-server
 
 ```
 
-For advanced configuration options and environment variable settings, see the Configuration guide.
+For advanced configuration options and environment variable settings, see the [Configuration guide](./configuration.md).
 
 ## Version Compatibility