Admin Model Context Protocol (MCP) server

Give AI tools like Claude, ChatGPT, and Cursor write access to your Mintlify content and dashboard so they can edit pages, update settings, and open PRs.

About the admin MCP

The admin MCP server gives AI tools write access to your Mintlify content and settings. Use it to update content and access your dashboard. With the admin MCP, you can use your preferred AI tools to edit pages, restructure navigation, update docs.json, open pull requests, change settings, create workflows, and more.

Connect any MCP client like Claude, Claude Code, ChatGPT, or Cursor to the admin MCP server to collaborate on your Mintlify content and settings with the same tools you use to write code. When you use the admin MCP server, all changes happen on a branch and require a pull request to merge. If your organization has multiple deployments, a single admin MCP connection can access and switch between all of them.

The admin MCP server allows AI tools to access your Mintlify dashboard. Treat it like a coworker with write access. Connect it only from trusted AI tools and review every pull request before merging.

The admin MCP is a hosted Mintlify service at https://mcp.mintlify.com. Every client connects to the same endpoint and authenticates with your Mintlify account.

How the admin MCP differs from the search MCP

	Admin MCP	Search MCP
Audience	Your team	Your end users
Access	Read, edit, restructure, save, create workflows, manage settings	Read and search published pages
Endpoints	Hosted by Mintlify, scoped to your project	`/mcp` on your site domain
Output	Content edits, navigation changes, pull requests, workflow runs	Search results and page content

Prerequisites

Before connecting the admin MCP, confirm the following:

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, ChatGPT, Cursor, or Codex.

Connect to the admin MCP

You must have an interactive OAuth login against your Mintlify account to connect to the admin MCP. AI tools exchange that login for a session token scoped to one or more deployments, depending on how you grant access. A connection scoped to specific deployments can only check out those, while an organization-wide connection can check out any deployment in your organization.

Add the admin MCP as a custom connector

Navigate to the Connectors page in the Claude settings.
Click Add custom connector.
Add the connector:
- Name: Admin MCP
- URL: https://mcp.mintlify.com
Click Add and complete the OAuth login.

Use the MCP in a chat

Click the attachments button (the plus icon), then select your admin MCP server. Claude can now call the Mintlify admin MCP tools while answering your prompt.

How a session works

Every admin MCP session binds to a single Git branch. The flow is:

Discover deployments (optional)

If your connection has access to more than one deployment, call list_deployments to see which subdomain values you can check out. Skip this step if your connection covers only a single deployment.

Check out a branch

The first required call is checkout {subdomain}. It creates a fresh mintlify-mcp/<slug>-<sha> branch from that deployment’s deploy branch (or attaches to an existing branch you name) and returns an editorUrl you can open to follow along in the dashboard editor.

Call list_branches before checkout if you need to discover or filter existing branches in a deployment’s repository.

Read, search, and edit

The AI uses tools like search, read, list_nodes, edit_page, write_page, create_node, and update_config to make changes. All edits buffer on the session branch in real time—nothing touches your deploy branch yet.

Review the diff

Call diff at any time to see exactly what changed since main. Open the editorUrl in your dashboard to see the same changes rendered.

Save

Call save to flush the branch to Git. mode: "auto" (default) opens a pull request and, if the deployment’s agent review setting is push-to-main and the deploy branch isn’t protected, merges it immediately (response includes merged: true). Use mode: "pr" to always open a pull request and leave it open for review, or mode: "commit" to push directly to an existing PR branch without opening a new PR.

Discard if needed

Call discard_session to drop all in-session changes and release the branch.

If your connection has access to multiple deployments, each checked-out deployment keeps its own session and branch in memory at the same time.

Calling checkout again with a different subdomain or branch switches which session is active. It doesn’t discard the others. To abandon an in-progress draft instead of switching away from it, call discard_session.

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.

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. If your deployment 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

After you connect the admin MCP, you can drive it with natural-language prompts. For example:

“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

Sessions hold an in-memory branch on the Mintlify side. If you abandon a session without saving or discarding it, the branch persists until your next checkout overwrites it. Avoid leaving stale mintlify-mcp/* branches in your repository. Clean them up periodically.

Disconnect or revoke access

Disconnect the admin MCP when you no longer want an AI tool to edit your project, or when you want to force a fresh OAuth login.

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.

Revoking the OAuth grant does not affect pull requests the MCP has already opened. Close or revert those PRs in your Git provider if you want to undo pending changes.