docs: add admin MCP content editing guide

ai/admin-mcp-content-edits.mdx

@@ -0,0 +1,156 @@
+---
+title: "Edit docs content with the admin MCP"
+sidebarTitle: "Edit with Admin MCP"
+description: "Use the Mintlify admin MCP to safely create, edit, review, and publish documentation content changes from an AI tool."
+keywords: ["Admin MCP", "MCP", "AI editing", "documentation edits", "MDX", "pull request", "content editing"]
+---
+
+## Overview
+
+Use the [admin MCP](/ai/mintlify-mcp) when you want an AI tool to edit your Mintlify documentation for you. The admin MCP gives trusted AI tools access to your docs on a Git branch, so the tool can read pages, make MDX edits, update navigation, and open a pull request for review.
+
+This guide focuses on content editing: creating pages, updating existing pages, and reviewing the final diff before publishing.
+
+<Note>
+  The admin MCP has write access to your docs. Connect it only to trusted AI tools, keep each editing session focused, and review the pull request before merging.
+</Note>
+
+## When to use it
+
+Use the admin MCP for docs content work such as:
+
+- Creating a new page from a prompt, issue, support ticket, or product note
+- Updating an existing page after a feature change
+- Rewriting unclear sections while preserving the page structure
+- Finding and replacing outdated terminology across pages
+- Adding examples, callouts, steps, tabs, or code blocks to MDX
+- Moving pages or adding a new page to the sidebar navigation
+
+For read-only retrieval from a published docs site, use the [search MCP](/ai/model-context-protocol) instead.
+
+## Basic editing flow
+
+<Steps>
+  <Step title="Connect the admin MCP">
+    Add `https://mcp.mintlify.com` to an MCP-capable client such as Claude, Claude Code, Cursor, or Codex. Complete the OAuth login with a Mintlify account that has access to the deployment you want to edit.
+  </Step>
+  <Step title="Check out a branch">
+    Ask the AI tool to check out the deployment and create a branch for the change. Use a specific slug so the branch is easy to recognize.
+
+    ```txt
+    Check out the mintlify deployment on a new branch with the slug update-api-auth-docs.
+    ```
+  </Step>
+  <Step title="Ask for a focused content change">
+    Describe exactly what should change and where. Mention the page path when you know it, or ask the tool to search first when you do not.
+
+    ```txt
+    Update /api/authentication to explain the new API key rotation behavior. Keep the existing page structure, add one warning callout, and include a short curl example.
+    ```
+  </Step>
+  <Step title="Review the draft">
+    Ask the tool to summarize the pages it changed and show the diff. Open the editor URL returned by `checkout` to review the rendered docs in the Mintlify dashboard.
+  </Step>
+  <Step title="Save as a pull request">
+    When the change looks correct, ask the tool to save the branch as a pull request with a clear title and body. Review and merge the PR through your normal Git workflow.
+  </Step>
+</Steps>
+
+## Useful prompts
+
+### Create a new page
+
+```txt
+Create a new docs page under the Create content section called "Reusable API examples". Explain when to reuse examples, how to structure snippets, and include one MDX snippet. Add it to the sidebar after Reusable snippets.
+```
+
+### Update an existing page
+
+```txt
+Read /create/code and update the code block guidance to mention diff highlighting. Preserve the current tone and only change the relevant section.
+```
+
+### Search before editing
+
+```txt
+Search the docs for pages that mention "legacy_token". Update each relevant page to use "api_key" instead, but do not change code examples that intentionally document the old field for migration.
+```
+
+### Improve clarity without changing meaning
+
+```txt
+Rewrite the "Prerequisites" section on /deploy/github to be easier to scan. Keep the same requirements, use bullets, and do not add new technical claims.
+```
+
+### Add MDX components
+
+```txt
+Add a Steps component to /quickstart that walks through installing the CLI, running a local preview, and publishing the first change. Keep the existing intro intact.
+```
+
+## How the tools map to docs edits
+
+| Task | Admin MCP tools |
+| :-- | :-- |
+| Find the right page | `search`, `list_nodes` |
+| Read page content | `read` |
+| Make a targeted MDX edit | `edit_page` |
+| Replace a full page draft | `write_page` |
+| Create a new page and add it to navigation | `create_node` |
+| Change page metadata such as title or description | `update_node` |
+| Move a page in navigation | `move_node` |
+| Review pending changes | `diff`, `get_session_state` |
+| Open a pull request | `save` |
+
+<Tip>
+  Use targeted edits for small changes and full-page overwrites for new pages or major rewrites. For page metadata, ask the tool to update the page node instead of editing frontmatter text directly.
+</Tip>
+
+## Best practices
+
+<AccordionGroup>
+  <Accordion title="Keep one branch per task">
+    Keep each session scoped to one docs change. A branch that updates one feature page or one terminology migration is easier to review than a branch with many unrelated edits.
+  </Accordion>
+
+  <Accordion title="Give source material">
+    Paste the product spec, changelog, issue, or support answer that the docs should reflect. The AI tool can write better documentation when it has the exact source of truth.
+  </Accordion>
+
+  <Accordion title="Name paths and constraints">
+    Include page paths, navigation placement, preferred components, and anything that should not change. For example: "Do not edit the API reference pages" or "Keep all examples in TypeScript."
+  </Accordion>
+
+  <Accordion title="Ask for a diff summary">
+    Before saving, ask the tool to summarize every changed page and explain why each change was made. Then review the rendered preview and the pull request diff.
+  </Accordion>
+
+  <Accordion title="Prefer reviewable edits">
+    Ask for concise, local changes when possible. Large rewrites should be split into multiple sessions so reviewers can verify each change with confidence.
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+### The tool cannot find the page
+
+Ask it to list navigation nodes or search for the page title. If your project has multiple deployments, confirm it checked out the correct `subdomain`.
+
+### The wrong deployment is open
+
+Ask the tool to call `list_deployments`, then `checkout` the correct deployment. Each deployment keeps a separate session.
+
+### The edit changes too much
+
+Ask the tool to discard the session or revert the specific page, then retry with narrower instructions. Include the exact section, heading, or string that should change.
+
+### The pull request is not ready
+
+Keep iterating on the same branch. Ask for follow-up edits, review the diff again, then save when the content is ready.
+
+## Next steps
+
+- Learn how to [connect and manage the admin MCP](/ai/mintlify-mcp)
+- Review [MDX text formatting](/create/text)
+- Explore [Mintlify components](/components/index)
+- Learn how to [structure navigation](/organize/navigation)

docs.json

@@ -111,6 +111,7 @@
                     ]
                   },
                   "ai/mintlify-mcp",
+                  "ai/admin-mcp-content-edits",
                   {
                     "group": "Automations",
                     "pages": [