Skip to main content

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

​
Update an existing page

​
Search before editing

​
Improve clarity without changing meaning

​
Add MDX components

​
How the tools map to docs edits

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