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

​

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.

​

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 nav 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 on the session branch, the response includes an editorUrl that opens the page in the dashboard editor.
• 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

• search_code_operations: Search the project management methods available to code mode. Each result includes the method’s full input schema.
• execute_code: Run a TypeScript script against the project management methods. The connection’s granted scopes gate every method, and any method you weren’t granted returns an authorization error.

​

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.
• 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 nav diff.
• diff: List all changes between the session and your deploy 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, auto-merges the PR.
• discard_session: Drop the session and its in-flight 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 any active session tokens immediately, so in-flight 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.