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. save 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 a session 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.
• save publishes only your changes. It ignores mode and 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_session reverts only your changes. It returns discardedChanges with the number of changes it reverted. Other people’s changes and the branch itself stay untouched.
• get_session_state lists only your changes.

• 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.
• Push directly to your deploy branch is off in your publishing settings.
• 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.

​

Publishing

• Your deploy branch requires a pull request. If branch protection rules or required approvals prevent direct pushes, MCP changes always open 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.

​

What the admin MCP can do

​

Content

• read: Fetch the full MDX of any page on the session branch. 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 work without a checkout 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.
• 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 work without a checkout.
• 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 the session 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 the session 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>'

​

Navigation

• list_nodes: Walk the navigation tree 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 works without a checkout, ignores 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, works without a checkout, 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 work without a checkout.
• 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 work without a checkout.

​

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.

​

Session

• list_deployments: List the projects your connection can access, returning each {subdomain, name}. Call this to discover which subdomain to pass to checkout.
• checkout: Bind a session to a branch for a given project subdomain, or switch which project’s session is active. Pass the deploy branch as branch to edit it 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. Call this before checkout to attach to an existing branch by name.
• get_session_state: Inspect the current branch, edited files, and pending navigation diff. On the deploy branch, lists only your changes.
• diff: List all changes between the session 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.
• save: Open a pull request or commit to the session branch. If your project allows the agent to push to main and you have no branch protection rules, Mintlify auto-merges the PR. On the deploy branch, commits only your pending changes directly.
• discard_session: Drop the session and its in-flight changes. On the deploy branch, reverts only your pending changes.

​

Example prompts

• “Check out a branch called 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. Save 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.”

​

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