Admin Model Context Protocol (MCP) server

​

About the admin MCP

​

How the admin MCP differs from the search MCP

​

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 Mintlify GitHub App or GitLab 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, 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

​

What the admin MCP can do

​

Content

• read — Fetch the full MDX of any page on the session branch.
• search — Find lines matching a substring or regular expression across every page.
• edit_page — Apply a targeted edit to a page.
• write_page — Overwrite a page’s full MDX content.

​

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.
• create_node — Add a new page, group, tab, anchor, version, language, product, or dropdown.
• update_node — Update a node’s properties in place (rename a group, change an icon, set a default version).
• move_node — Move a node, including renaming a page’s path.
• delete_node — Remove a node from the navigation.

​

Configuration

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

​

Session

• list_deployments — List the deployments 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 deployment subdomain, or switch which deployment’s session is active.
• list_branches — List Git branches available for a deployment’s project, 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 main.
• save — Open a pull request or commit to the session branch.
• 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.
  • Cursor: delete the mintlify entry from mcp.json and reload.
  • Codex: delete the [mcp_servers.mintlify] block from ~/.codex/config.toml.