Add Developer MCP documentation #7509

hifi-phil · 2025-10-15T08:35:42Z

Set up the initial documentation structure and first page for the Developer Model Context Protocol (MCP) integration in Umbraco CMS v16.

📋 Description

📎 Related Issues (if applicable)

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

Code blocks are correctly formatted.
Sentences are short and clear (preferably under 25 words).
Passive voice and first-person language (“we”, “I”) are avoided.
Relevant pages are linked.
All links work and point to the correct resources.
Screenshots or diagrams are included if useful.
Any code examples or instructions have been tested.
Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

Deadline (if relevant)

📚 Helpful Resources

🧾 Umbraco Contribution Guidelines
✍️ Umbraco Documentation Style Guide

Set up the initial documentation structure and first page for the Developer Model Context Protocol (MCP) integration in Umbraco CMS v16. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- 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]>

Added README files to organize the concepts and host-setup documentation sections. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Restructured Developer MCP navigation with proper subsections - Added Key Concepts subsection with Model Context Protocol and Context Engineering - Added Host Setup subsection with guides for Claude Desktop, Claude Code, Cursor, and GitHub Copilot - Removed old concepts.md file (replaced with concepts/README.md) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…ude Code - Added detailed setup guide for Claude Desktop with configuration examples - Added detailed setup guide for Claude Code with CLI and .mcp.json configuration - Updated main README with Node.js version requirement hint - Improved formatting of host setup links in README 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…sor and GitHub Copilot guides - Update page titles to include "Setup" suffix for consistency - Add comprehensive Cursor setup guide with configuration and screenshots - Add GitHub Copilot setup guide with install button and management instructions - Enhance Claude Desktop documentation with screenshot and improved formatting - Add cross-references to MCP toolkit selection guide across all host setup pages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…ing fixes Updates include: - Enhanced getting started sections across all host guides - Improved configuration instructions for Claude Code with emphasis on .mcp.json - Fixed formatting inconsistencies and hint blocks in Claude Desktop guide - Clarified tool limit warnings and restart behavior in Cursor guide - Corrected typos and improved flow in GitHub Copilot guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added note to remind users to replace placeholder values (UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, UMBRACO_BASE_URL) with their actual connection details. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added note to remind users to replace placeholder values with their actual connection details in the CLI configuration section. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added detailed documentation covering: - Authentication configuration keys - Tool and tool collection management options - Security configuration for media uploads - Environment configuration methods with precedence order - Examples for .env file and CLI argument usage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added documentation for NODE_TLS_REJECT_UNAUTHORIZED setting with warning about local HTTPS connections requiring this to be set to 0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Updated formatting in security configuration table and streamlined environment configuration section for better readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Renamed mcp-toolkit.md to available-tools.md for clearer documentation structure and updated SUMMARY.md to reflect the new file name. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Updated documentation structure in SUMMARY.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added new "Excluded Tools" entry in the Developer MCP documentation structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Removed the obsolete MCP as a Toolkit entry that was referencing the deleted mcp-toolkit.md file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added new documentation file for excluded tools in the Developer MCP section. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Updated context engineering documentation with enhanced explanations and added new images (chat-gpt-conversation.png and claude-code-context-window.png). Also updated excluded-tools.md with improved categorization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Enhanced Model Context Protocol documentation with reporting examples and LLM collaborator section - Updated context engineering documentation with improved explanations - Added new scenarios.md file for use case examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Added maintenance use case covering content reorganization, naming standardization, and technical debt cleanup. Fixed typo in schema scaffolding description. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

… MCP - Create scenarios.md with 23 practical use cases across 8 categories - Include example prompts and required tool collections for each scenario - Add table of contents for easy navigation - Update examples to demonstrate MCP value over standard UI operations - Add to SUMMARY.md as "Common Use Cases and Scenarios" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Simplified title from 'Common Use Cases and Scenarios' for brevity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Simplified TOC to link to major H2 section headings instead of individual numbered scenarios for proper anchor link functionality. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Replace 'how-best-to-use.md' with 'best-practice.md' for clearer naming - Remove empty prompt-pack.md file - Update SUMMARY.md to reflect new documentation structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Enhanced the best practices documentation to include considerations about: - Cost efficiency through context optimization - Environmental impact of token usage - Trade-offs between context size, cost, and compute usage This addition emphasizes that minimizing context isn't just a technical best practice but also reduces monetary costs and carbon footprint. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

eshanrnh · 2025-10-28T08:42:26Z

Thanks for the PR, @hifi-phil 🙌 We will review it soon.

This commit adds detailed documentation for creating media items using the Umbraco Developer MCP server, including: - New creating-media.md guide covering all media creation functionality - Documentation of supported media types and source types (file path, URL, base64) - Configuration requirements and environment variables - Usage examples and common scenarios - Best practices, security considerations, and troubleshooting - Updated README.md with link to new media creation guide - Updated SUMMARY.md navigation to include the new documentation page 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Relocated creating-media.md from reference/developer-mcp/ to reference/developer-mcp/best-practice/ - Updated SUMMARY.md to reflect new location under Best Practice section - Refined content and examples in creating-media.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

AndyButland

Looks excellent to me Phil. I just found a few small things to leave comment on line.

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

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

16/umbraco-cms/reference/developer-mcp/best-practice/example-instructions.md

16/umbraco-cms/reference/developer-mcp/excluded-tools.md

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

Co-authored-by: Andy Butland <[email protected]>

- Enhanced example-instructions.md with clearer introduction and context - Wrapped example content in markdown code block for better separation - Added explanation about version specification for AI documentation sources - Removed redundant warning count from excluded-tools.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…UmbracoDocs into cms/v16/developer-mcp

- Split long sentences in README.md to be under 25 words each - Changed "easy" to "straightforward" for more professional tone - Updated creating-media.md for consistency - Updated Acronyms.yml with new terms 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Split all sentences over 25 words into shorter, clearer statements: - Line 23: Context sending explanation (32 → 17 + 14 words) - Line 75: Session continuity explanation (26 → 15 + 10 words) - Line 78: File saving tip (29 → 18 + 11 words) - Line 116: Prompt failure guidance (28 → 24 words) - Updated Acronyms.yml 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Fixed 10 long sentences throughout the document: - Line 22: MCP clients explanation (52 → 17, 6, 23 words) - Line 31: Bridge description (26 → 16, 11 words) - Line 43: Content automation (27 → 7, 19 words) - Line 46: Quality improvements examples (27 → 19, 19 words) - Line 49: Workflow integration (28 → 19, 8 words) - Line 71: Future MCP servers (28 → 18, 10 words) - Line 83: Administrator permissions (27 → 12, 20 words) - Line 118: Configuration restart (39 → 22, 16 words) - Line 132: Destructive consequences warning (28 → 14, 17, 11 words) - Line 197: Version mismatch behavior (38 → 23, 7, 11 words) All sentences now under 25 words for better clarity and readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Split line 9 in README.md (28 words → 18 + 11 words) - Changed "easy" to "quickly" in best-practice/README.md line 59 - Updated "umbraco" to "Umbraco" for consistency - Changed "excellent" to "good" for more measured tone 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Split line 116 in best-practice/README.md (27 words → 12 + 18 words) - Split line 9 in example-instructions.md (31 words → 13 + 18 words) - Updated Acronyms.yml All sentences now under 25 words for improved readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Updated all references to use proper capitalization: - "data type" → "Data Type" - "document type" → "Document Type" This ensures consistency with Umbraco terminology throughout the available tools documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Split 5 sentences over 25 words in context-enginerring.md: - Line 19: Context sending (27 → 13, 14, 10 words) - Line 41: Context drift (32 → 18, 18 words) - Line 56: Information overload (32 → 24, 9 words) - Line 66: Request effectiveness (26 → 12, 12 words) + fixed typo "mainatin" - Line 73: Tool management (27 → 21, 8 words) Additional improvements: - Changed "completely" to "fully" for better readability - Changed "simple" to "basic" for more accurate description - Minor updates to best-practice/README.md and available-tools.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Line 107 in best-practice/README.md (27 → 19 + 10 words) - Line 116 in best-practice/README.md (27 → 12 + 18 words) - Line 69 in context-enginerring.md (27 → 11 + 20 words) All sentences now under 25 words for improved readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Configuration changes: - Line 34: Split tool collection hint (26 → 15 + 9 words) Claude Code changes: - Line 7: Split introduction (27 → 17 + 14 + 14 words) - Line 91: Split reconnect explanation (29 → 14 + 17 words) Claude Desktop changes: - Line 7: Split introduction (30 → 14 + 25 words) - Line 56: Split Node version issue (42 → 18 + 21 words) Additional updates to host-setup/README.md All sentences now under or at 25 words for improved readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Model Context Protocol changes (13 sentences fixed): - Line 7: Split introduction (26 + 26 → 23, 17, 11 words) - Line 16: Split protocol description (33 → 15, 23 words) - Line 38: Split client routing (37 → 14, 12, 11, 17 words) - Line 55: Split multiple servers (51 → 13, 20, 17, 16, 12 words) - Line 57: Split element description (31 → 13, 18 words) - Line 76: Split API description (37 → 15, 14, 11 words) - Line 82: Split compound tasks (36 → 23, 13 words) - Line 84: Split API automation (35 → 20, 18 words) - Line 87: Split Backoffice replacement (28 → 10, 9, 11 words) - Line 88: Split augmentation (28 → 10, 23 words) - Line 91: Split composable tools (26 → 9, 19, 14 words) - Line 106: Split tool orchestration (35 → 11, 13, 16 words) - Line 108: Split imagination limit (38 → 6, 19, 10 words) - Line 112: Split collaboration (36 → 20, 25, 13 words) Claude Desktop changes: - Replaced "Unfortunately" with "Note that" and removed it - All sentences already under 25 words Updates to cursor.md and github-copilot.md from user edits All sentences now at or under 25 words for improved readability. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Model Context Protocol changes: - Changed "several" to "many" for clearer quantification - Changed "really just" to "simply" for more concise language Configuration changes: - User edits applied 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…CP concepts - Split 27-word sentence about connection errors into two clearer sentences - Changed "just" to "merely" for better formal tone in LLM collaborator section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Standardize "Document Type" and "Data Type" capitalization in scenarios - Simplify example prompts by removing unnecessary details - Remove duplicate template inheritance scenario - Add CSV to acronyms list for style checking 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Removed the "Create and update Razor templates programmatically" scenario as template creation is not currently supported in the MCP server. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Changed all instances of "document type" to "Document Type" for consistency - Updated code formatting in stylesheet and webhook examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Changed specific Claude Desktop path references to generic "instruction file" - Makes documentation applicable to all MCP-compatible AI hosts - Updated section heading for clarity 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Added detailed step-by-step process for adding new blocks - Includes content type creation, model generation, partial views, and styling - Shows how to integrate with Block Grid Editor Data Type configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

eshanrnh · 2025-11-05T09:50:39Z

The PR looks great, @hifi-phil 🙌 I'll merge this PR in and make changes locally (add missing periods, formatting stuff, and so on).

hifi-phil marked this pull request as draft October 15, 2025 08:35

add to the summary file

052d411

hifi-phil changed the title ~~Add Developer MCP documentatio~~ Add Developer MCP documentation Oct 15, 2025

eshanrnh added the category/umbraco-cms label Oct 15, 2025

Phil Whittaker and others added 25 commits October 15, 2025 10:35

improve hints

98e604a

Add README files for concepts and host-setup sections

8f63245

Added README files to organize the concepts and host-setup documentation sections. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Update SUMMARY.md structure

af57751

Updated documentation structure in SUMMARY.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Add Excluded Tools section to SUMMARY.md

c140a0a

Added new "Excluded Tools" entry in the Developer MCP documentation structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Remove duplicate mcp-toolkit.md reference from SUMMARY.md

f0965b4

Removed the obsolete MCP as a Toolkit entry that was referencing the deleted mcp-toolkit.md file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Add excluded-tools.md documentation file

f8de587

Added new documentation file for excluded tools in the Developer MCP section. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Update scenarios page title to 'Use Cases and Scenarios'

74b843a

Simplified title from 'Common Use Cases and Scenarios' for brevity. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

hifi-phil requested a review from eshanrnh October 25, 2025 07:27

Phil Whittaker and others added 3 commits October 31, 2025 21:36

trigger rebuild

211d826

AndyButland approved these changes Nov 3, 2025

View reviewed changes

hifi-phil and others added 18 commits November 3, 2025 14:20

Apply suggestions from code review by Andy Butland

02802b6

Co-authored-by: Andy Butland <[email protected]>

Merge branch 'cms/v16/developer-mcp' of https://github.com/hifi-phil/…

d460fc3

…UmbracoDocs into cms/v16/developer-mcp

hifi-phil marked this pull request as ready for review November 4, 2025 09:15

Phil Whittaker and others added 2 commits November 4, 2025 09:41

eshanrnh approved these changes Nov 5, 2025

View reviewed changes

eshanrnh merged commit 22a3185 into umbraco:main Nov 5, 2025
50 of 60 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Developer MCP documentation #7509

Add Developer MCP documentation #7509

Uh oh!

hifi-phil commented Oct 15, 2025

Uh oh!

eshanrnh commented Oct 28, 2025

Uh oh!

AndyButland left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eshanrnh commented Nov 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add Developer MCP documentation #7509

Add Developer MCP documentation #7509

Uh oh!

Conversation

hifi-phil commented Oct 15, 2025

📋 Description

📎 Related Issues (if applicable)

✅ Contributor Checklist

Product & Version (if relevant)

Deadline (if relevant)

📚 Helpful Resources

Uh oh!

eshanrnh commented Oct 28, 2025

Uh oh!

AndyButland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eshanrnh commented Nov 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants