Edit docs content with the admin MCP

Use the Mintlify admin MCP to safely create, edit, review, and publish documentation content changes from an AI tool.

Overview

Use the admin 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.

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.

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 instead.

Basic editing flow

1. 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.

2. 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.

   Check out the mintlify deployment on a new branch with the slug update-api-auth-docs.
   
3. 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.

   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.
   
4. 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.

5. 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.

Useful prompts

Create a new page

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

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

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

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

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

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.

Best practices

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.

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.

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.”

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.

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.

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
• Review MDX text formatting
• Explore Mintlify components
• Learn how to structure navigation