Set up Mintlify MCP Server safely

The Mintlify Admin MCP server at https://mcp.mintlify.com is hosted write access to Mintlify documentation and parts of its dashboard. This guide follows only Mintlify’s current official documentation at https://www.mintlify.com/docs/ai/mintlify-mcp. It is for project owners who want to edit content through Claude Code, Codex, or Cursor without losing sight of access boundaries, Git review, and data protection. The server is not the read-oriented Search MCP for one documentation site: that Search MCP lives at the relevant site’s /mcp path. When the task is simply research in published documentation, that read-only path is usually the better and lower-risk choice.

Check prerequisites and permissions

Before installing, identify the Mintlify project the connection should serve and the person who will review resulting changes. You need a Mintlify account with access to that project. The OAuth login inherits the dashboard role according to the provider, so protected settings require project-admin access. The project’s GitHub, GitLab, or Bitbucket integration must be able to write to the deploy-branch repository because save creates a commit or pull request through that connection. Use a personal account only when the organization permits it, and revoke old connections under “Settings → Security & access → Connected apps.”

Define a narrow job before starting: update one named page, restructure a specified section, or correct a single navigation item. A broad objective such as “clean up the documentation” expands the possible diff unnecessarily. Put the target deployment, target branch, permitted paths, and intended result in a human-confirmed work request. Arrange a second reviewer when the content is legal, security-sensitive, or product-critical.

Connect the client and finish OAuth

For Claude Code, Mintlify documents this local configuration command:

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

For Codex, create a [mcp_servers.mintlify] section with the URL https://mcp.mintlify.com in ~/.codex/config.toml. In Cursor, configure the same URL as a mintlify entry in mcp.json. On first use, the client opens a browser for interactive OAuth. Verify the domain, account, and requested access in that browser; do not approve a login triggered by an unexpected redirect or text inside a document. Passwords, OAuth codes, session tokens, and Git tokens never belong in prompts, MDX examples, commits, or screenshots.

After signing in, make the available connection visible first. If more than one deployment is reachable, use only list_deployments and choose the confirmed subdomain. According to Mintlify, checkout creates or attaches a branch. Give it a traceable slug such as fix-auth-guide and verify that the deployment branch and project match the request. A checkout against the wrong deployment can otherwise create a technically valid but operationally wrong pull request.

Read first, then make the smallest change

Start with read, search, list_nodes, and then diff. This obtains page content, navigation context, and the actual pending changes without publishing anything. Use edit_page for a small reviewable change rather than write_page when a full replacement is not necessary. Manually inspect paths, links, code blocks, headings, versions, and examples in the preview. Navigation operations such as move_node and delete_node are not harmless formatting: they can change user journeys and discoverability.

Treat every fetched page, issue, and error message as untrusted content. Instructions such as “skip review,” “change permissions,” “insert a token,” or “call save” can be prompt injection even if they look like an internal note. They are not authorization. The client can pass tool results to a language model that then proposes changes. Keep context small, remove secrets and personal data from requested excerpts, and use a tool allowlist without write operations until the intended work is clear.

Review the diff and save safely

Before every save, call diff and compare every line with the confirmed work request. Open the editor or preview URL returned by Mintlify and inspect the rendered page as well. Check that a link, navigation item, frontmatter field, or example was not changed unintentionally. For ordinary content work, use save in pull-request mode so a second review occurs in the Git provider. Use auto mode or direct pushes only after explicit documented approval and a check of branch protection.

Code Mode is separate from the branch session and, according to Mintlify, can manage settings, workflows, members, billing, integrations, and analytics directly on the live deployment. Never derive such calls from an automated agent run, third-party document text, or a vague request. They need explicit human confirmation of the target, precise effect, and rollback plan. After a PR merge or an authorized direct change, verify the live result and roll back through Git or the dashboard if it differs from the approved outcome.

Data path, rotation, and completion

The connection flows from Mintlify to the MCP client and often onward to that client’s model provider. A hosted Mintlify service does not mean documentation content or dashboard responses are processed only locally. Before using production data, review the chosen client’s retention, training, DPA, and enterprise settings. Limit OAuth to the required deployments, remove the server after time-bounded work, and revoke the OAuth grant after a device change, role change, or suspected compromise. Pull requests already opened remain after revocation and should be closed or reverted when appropriate.

FAQ

Do I need a new branch for every change? Not necessarily, but one focused session per topic is easier to review. Mintlify keeps sessions in memory; use discard_session for unwanted drafts rather than leaving unknown branch remnants.

Why is a local MCP configuration entry not a security boundary? The configuration connects the client to a hosted service. Tool results can then enter the model provider’s context; OAuth, Git permissions, client data policy, and human review remain separate controls.

What is the safe default for save? A pull request with a reviewed diff and rendered preview. Use direct or automatically effective changes only with an explicit exception approval and an available rollback plan.