Admin Model Context Protocol (MCP) server

​

About the admin MCP

​

How the admin MCP differs from other Mintlify MCP servers

​

Prerequisites

• Mintlify account: You need a Mintlify account with access to the project you want to edit. The OAuth session inherits your dashboard permissions, so admin-only actions (such as update_config on protected settings) require an admin role on the project.
• Git provider access: The GitHub, GitLab, or Bitbucket connection for the project must have write access to the deploy branch’s repository. publish opens PRs through the same integration used for normal deploys.
• MCP client: An MCP-capable AI tool such as Claude, Claude Code, ChatGPT, Cursor, or Codex.

​

Connect to the admin MCP

claude mcp add --transport http mintlify https://mcp.mintlify.com

{
  "mcpServers": {
    "mintlify": {
      "url": "https://mcp.mintlify.com"
    }
  }
}

[mcp_servers.mintlify]
url = "https://mcp.mintlify.com"

​

How editing works

​

Edit the deploy branch directly

• Edits are live to collaborators. Anyone else editing the deploy branch in the dashboard sees the AI’s changes as they happen.
• publish publishes only your changes. It commits your pending changes straight to the deploy branch, like clicking Publish in the editor. Other people’s unpublished changes stay pending. Your own unpublished edits from the dashboard editor publish too.
• discard reverts only your changes. It returns discardedChanges with the number of changes it reverted. Other people’s changes and the branch itself stay untouched.
• status lists only your changes.

• Push directly to your deploy branch is off in your publishing settings.
• Branch protection on your deploy branch requires pull requests, or Mintlify can’t check your branch protection rules.
• Editing the deploy branch is locked in the dashboard editor.
• You connected with a client or machine-to-machine token instead of an OAuth login. These tokens aren’t tied to a user, so they have no “own” changes.

​

Work on a branch

​

Publishing

• Your deploy branch requires a pull request. If branch protection rules or required approvals prevent direct pushes, MCP changes always go through a pull request regardless of this setting.
• Mintlify hosts your project. For Mintlify-hosted sites, MCP changes always push directly, unless branch protection still requires a pull request.
• You aren’t an admin. Changing this setting requires the admin role on your project. Editors and viewers see the toggle disabled with a permission banner.

​

Redirect URIs

​

Credentials

1. In your dashboard sidebar, click MCP, then click Credentials.
2. Click Create credential.
3. Copy the secret. The dashboard shows the secret only once.

​

What the admin MCP can do

​

Content

• read: Fetch the full MDX of any page on branch, or on your deploy branch when you omit it. Pass in a file path or UUID. To read a private page, pass its private-page-<uuid> node ID from list_nodes with visibility: "private". Private reads don’t need a branch and require an OAuth session. The admin MCP rejects client and machine-to-machine tokens for private-page access.
• search: Find lines matching a substring or regular expression across every page on branch. Searches your deploy branch when you omit it.
• edit_page: Apply a targeted edit to a page. To edit a private page, pass its private-page-<uuid> node ID as path. Private edits require an OAuth session with an editor role or higher on the page and don’t need a branch.
• write_page: Overwrite a page’s full MDX content. Accepts a private-page-<uuid> node ID to overwrite a private page under the same OAuth and role requirements as edit_page. Use create_node to create a new private page.

​

Images

• upload_image: Start uploading a local image file to branch. Pass the destination path (for example, images/dashboard.png), the file’s contentType, and its exact size in bytes. Returns an uploadId, a presigned uploadUrl, and the headers to send with the upload.
• finalize_image_upload: Save the uploaded image to branch. Pass the uploadId and the same path. Returns the src to reference in MDX with edit_page or write_page, or in the logo or favicon fields of docs.json with update_config.

curl -X PUT --upload-file ./dashboard.png -H 'Content-Type: image/png' '<uploadUrl>'

​

Comments

• read_comments: List the open comment and suggestion threads on a page, oldest first. Pass path in the same forms as read. Each thread includes a threadId, its type (comment or suggestion), the quotedText it’s anchored to, the suggestedText for suggestions, and its comments with each author, content, and createdAt. If the anchored text no longer exists on the page, the thread includes anchorRemoved: true and quotedText shows the original quote. Reads threads on branch, or on your deploy branch when you omit it.
• add_comment: Start a new comment thread on a page without changing its content. Use it to leave feedback for your team instead of editing. Pass path in the same forms as read, the content of the comment, and quotedText: the smallest unique span of visible text to anchor to, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. For example, quote custom domain, not [custom domain](/path). Returns the new threadId. If the text isn’t on the page, the error is no_match. If it matches more than once, the error is not_unique, so quote a longer span.
• suggest_edit: Propose a tracked-changes suggestion on a page instead of editing it. The original text stays on the page with a strikethrough and the replacement appears alongside it. Nothing changes until someone accepts or rejects the suggestion in the dashboard editor. Pass path in the same forms as read, oldString, and newString. oldString is the smallest unique span of visible text to replace, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. Pass an empty newString to suggest a deletion, and an optional note to explain the change. Returns the new threadId with the originalText and suggestedText, trimmed to the span that changes. If the same suggestion is already open, the response includes alreadyExists: true and the existing threadId. The no_match and not_unique errors work as they do for add_comment. The error is no_change when both strings are the same, and conflicting_annotation when the text overlaps another open suggestion.
• reply_to_comment: Reply to a thread by threadId with content. Pass resolve: true to also resolve the thread. Mintlify posts the reply as the agent on behalf of the authorizing user, and it appears live in the dashboard editor.
• resolve_comment: Resolve a thread without replying.

​

Navigation

• list_nodes: Walk the navigation tree of branch, or of your deploy branch when you omit it, with optional filters. Filter by parentId (use recursive: true to include all descendants), one or more node types, or any division scope: language, version, tab, dropdown, anchor, product, or item. Results paginate through an opaque cursor. Pass visibility: "private" to list the private pages and folders the OAuth user can access instead of the branch navigation tree. Private listing ignores branch and the other filters, and returns each node’s role.
• create_node: Add a new page, group, tab, anchor, version, language, product, or dropdown. Pass visibility: "private" with data.type: "page" or data.type: "group" to create a private page or private folder in the caller’s private tree. The caller becomes the node’s manager. Private creation requires an OAuth session, doesn’t need a branch, and places the node at the private root or under an existing private-folder-<uuid> parent. For new pages, the response includes an editorUrl that opens the page in your dashboard.
• update_node: Update a node’s properties in place (rename a group, change an icon, set a default version). Accepts a private-page-<uuid> or private-folder-<uuid> node ID to rename a private page or folder or change its icon or tag. Private updates require an OAuth session with an editor role or higher and don’t need a branch.
• move_node: Move a node, including renaming a page’s path.
• delete_node: Remove a node from the navigation. Accepts a private-page-<uuid> or private-folder-<uuid> node ID to delete a private page or folder from the caller’s private tree. Private deletions require an OAuth session with a manager role on the node and don’t need a branch.

​

Configuration

• update_config: Modify docs.json (theme, navigation roots, integrations, SEO settings).

​

Project management

{
  "subdomain": "acme",
  "request": { "action": "noindex", "noindex": true }
}

• get_deployment_settings: Read a project’s dashboard settings, Git sources, custom hostname status, and source checks in one call. Slack configuration and snippets are opt-in.
• get_analytics_report: Read a prebuilt analytics report, such as page views, popular pages, referrals, feedback, assistant chats, or search quality. Select the report with request.report. Large results paginate with maxRows and rowOffset. For custom queries, use query_analytics.
• get_workflows: List workflows, get one workflow, or page through its runs.
• list_repos_and_prs: List connected repositories, a repository’s pull requests, or available integrations to use in a workflow.

• update_deployment_settings: Change one dashboard setting, such as noindex, base_path, name, disable_ai_chat, search_settings, privacy, custom_scripts, or an add-on. Use update_config for docs.json settings.
• manage_custom_domain: Add or remove a custom domain, provision its hostname, or retrigger hostname validation.
• manage_git_source: Add, update, remove, or reorder the Git repositories a project builds from, or set the base source.
• manage_access_auth: Configure or remove site authentication, add or delete passwords, configure end-user authentication, or switch which one is active.
• manage_workflow: Create, update, enable or disable, delete, or trigger a workflow.
• manage_members_sharing: List or remove organization members, update their roles, or manage private page grants and moves.

​

Branches and publishing

• list_deployments: List the projects your connection can access, returning each {subdomain, name}. Call this to discover which subdomain to pass.
• create_branch: Start a new branch off your deploy branch with a title that also names its pull request. Returns the branchName to pass as branch. See Work on a branch. You don’t need it to edit the deploy branch directly.
• list_branches: List Git branches available for a project’s repository, with optional query filtering. Returns the branch names, total count, and the deploy branch. Pass any of them as branch.
• status: List the edited files, changed docs.json keys, and pending navigation diff on branch, or on your deploy branch when you omit it. On the deploy branch, lists only your changes.
• diff: List all changes between branch and your deploy branch. Each changed file and docs.json entry includes authors and byYou. authors lists the members whose unpublished edits the entry contains. byYou is true when the entry includes your own edits. Use byYou to tell your changes apart from a colleague’s on a shared branch.
• publish: On the deploy branch, commit only your pending changes directly. On a branch, commit pending changes and return the branch’s pull request, opening one if needed. Pass merge: true to also merge the pull request when edits to the deploy branch are allowed.
• discard: Abandon the edits on branch. On the deploy branch, reverts only your pending changes. On another branch you created, deletes the branch and closes its pull request.

​

Example prompts

• “Start a branch titled ‘Add billing FAQ’ and create a new page under the FAQ group titled ‘Billing’. Draft answers for the five questions in this Linear issue.”
• “Find every page that mentions the deprecated legacy_token field and update the example to use api_key instead. Publish it as a PR titled ‘docs: replace legacy_token references’.”
• “Reorganize the API reference: move the webhooks pages into a new group called ‘Webhooks’ and update the icons to match the rest of the section.”
• “Read the open comments on the quickstart page, make the requested edits, and reply to each thread, resolving it once addressed.”

​

Best practices

​

Disconnect or revoke access

• Revoke the OAuth grant: In your Mintlify dashboard, navigate to Settings → Security & access → Connected apps and revoke the entry for the AI tool you connected. Revoking invalidates the tool’s access token within 30 seconds. After that, tool calls fail and the tool must complete a new OAuth login on the next call.
• Delete a credential: To revoke access for an AI app or gateway that uses a credential, go to MCP → Credentials in your dashboard sidebar and delete it.
• Remove the connector in the client:
  • Claude: Settings → Connectors, then remove the admin MCP entry.
  • Claude Code: claude mcp remove mintlify.
  • ChatGPT: Settings → Connectors, then remove the Mintlify entry.
  • Cursor: delete the mintlify entry from mcp.json and reload.
  • Codex: delete the [mcp_servers.mintlify] block from ~/.codex/config.toml.