Servidor Admin Model Context Protocol (MCP)

Da a Claude, Cursor y otras herramientas de IA acceso de escritura a tu contenido y panel de Mintlify para editar páginas, ajustes y abrir PRs.

​

Acerca del Admin MCP

El servidor Admin MCP otorga a las herramientas de IA acceso de escritura a tu contenido y configuración de Mintlify. Úsalo para actualizar contenido y acceder a tu panel. Con el Admin MCP, puedes usar tus herramientas de IA preferidas para editar páginas, reestructurar la navegación, actualizar docs.json, abrir pull requests, cambiar configuraciones, crear workflows y más.

Conecta cualquier cliente MCP como Claude, Claude Code o Cursor al servidor Admin MCP para colaborar en tu contenido y configuración de Mintlify con las mismas herramientas que usas para escribir código. Cuando usas el servidor Admin MCP, todos los cambios ocurren en una rama y requieren una pull request para fusionarse. Si tu organización tiene varias implementaciones, una sola conexión de Admin MCP puede acceder a todas ellas y alternar entre ellas.

El servidor Admin MCP permite que las herramientas de IA accedan a tu panel de Mintlify. Trátalo como a un compañero de trabajo con acceso de escritura. Conéctalo solo desde herramientas de IA de confianza y revisa cada pull request antes de fusionarla.

​

Cómo se diferencia el Admin MCP del Search MCP

	Admin MCP	Search MCP
Audiencia	Tu equipo	Tus usuarios finales
Acceso	Leer, editar, reestructurar, guardar, crear workflows, gestionar la configuración	Leer y buscar en las páginas publicadas
Endpoints	Alojado por Mintlify, limitado a tu proyecto	/mcp en el dominio de tu sitio
Salida	Ediciones de contenido, cambios de navegación, pull requests, ejecuciones de workflows	Resultados de búsqueda y contenido de páginas

​

Requisitos previos

Antes de conectar el Admin MCP, confirma lo siguiente:

• Cuenta de Mintlify: Necesitas una cuenta de Mintlify con acceso al proyecto que quieres editar. La sesión de OAuth hereda tus permisos del dashboard, por lo que las acciones exclusivas de administrador (como update_config en configuraciones protegidas) requieren un rol de administrador en el proyecto.
• Acceso al proveedor de Git: La Mintlify GitHub App o la conexión de GitLab del proyecto debe tener acceso de escritura al repositorio de la rama de despliegue. save abre PRs a través de la misma integración utilizada para los despliegues normales.
• Cliente MCP: Una herramienta de IA compatible con MCP, como Claude, Claude Code, Cursor o Codex.

​

Conectarse al Admin MCP

Debes tener un inicio de sesión OAuth interactivo en tu cuenta de Mintlify para conectarte al Admin MCP. Las herramientas de IA intercambian ese inicio de sesión por un token de sesión limitado a una o varias implementaciones, según cómo otorgues el acceso. Una conexión limitada a implementaciones específicas solo puede hacer checkout de esas, mientras que una conexión a nivel de organización puede hacer checkout de cualquier implementación de tu organización.

Claude

1. Agregar el Admin MCP como conector personalizado

   1. Navega a la página Connectors en la configuración de Claude.
   2. Haz clic en Add custom connector.
   3. Agrega el conector
      • Nombre: Admin MCP
      • URL: https://mcp.mintlify.com
   4. Haz clic en Add y completa el inicio de sesión OAuth.
2. Usar el MCP en un chat

   Haz clic en el botón de archivos adjuntos (el icono más) y luego selecciona tu servidor Admin MCP. Claude ahora puede llamar a las herramientas del Mintlify Admin MCP mientras responde a tu prompt.

Claude Code

Agrega el servidor Admin MCP con la CLI de Claude Code:

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

En el primer uso, Claude Code abre una ventana del navegador para completar el inicio de sesión OAuth. Tras autenticarte, la sesión se reutiliza para las llamadas posteriores.

Cursor

1. Abre la paleta de comandos con Command + Shift + P (Ctrl + Shift + P en Windows).
2. Busca Open MCP settings y haz clic en Add custom MCP.
3. En mcp.json, agrega el Admin MCP:

{
  "mcpServers": {
    "mintlify": {
      "url": "https://mcp.mintlify.com"
    }
  }
}

4. Recarga Cursor y completa el inicio de sesión OAuth cuando se te solicite.

Codex

Añade el servidor Admin MCP a la configuración de tu CLI de Codex en ~/.codex/config.toml:

[mcp_servers.mintlify]
url = "https://mcp.mintlify.com"

En el primer uso, Codex abre una ventana del navegador para completar el inicio de sesión de OAuth. Una vez autenticado, la sesión se reutiliza en las llamadas posteriores.

Consulta la documentación de Codex MCP para más detalles.

​

Cómo funciona una sesión

Cada sesión del Admin MCP se vincula a una sola rama de Git. El flujo es:

1. Descubrir implementaciones (opcional)

   Si tu conexión tiene acceso a más de una implementación, llama a list_deployments para ver qué valores de subdomain puedes usar en checkout. Omite este paso si tu conexión cubre solo una implementación.

2. Hacer checkout de una rama

   La primera llamada requerida es checkout {subdomain}. Crea una nueva rama mintlify-mcp/<slug>-<sha> a partir de la rama de despliegue de esa implementación (o se adjunta a una rama existente que indiques) y devuelve un editorUrl que puedes abrir para seguir el progreso en el editor del panel.

   Llama a list_branches antes de checkout si necesitas descubrir o filtrar las ramas existentes en el repositorio de una implementación.

3. Leer, buscar y editar

   La IA usa herramientas como search, read, list_nodes, edit_page, write_page, create_node y update_config para realizar cambios. Todas las ediciones se mantienen en la rama de la sesión en tiempo real; nada toca aún tu rama de despliegue.

4. Revisar el diff

   Llama a diff en cualquier momento para ver exactamente qué ha cambiado desde main. Abre el editorUrl en tu panel para ver los mismos cambios renderizados.

5. Guardar

   Llama a save para enviar la rama a Git. Usa mode: "pr" (predeterminado) para abrir una pull request, o mode: "commit" para hacer push directamente a una rama de PR existente.

6. Descartar si es necesario

   Llama a discard_session para descartar todos los cambios en la sesión y liberar la rama.

Si tu conexión tiene acceso a varias implementaciones, cada implementación de la que hagas checkout mantiene su propia sesión y rama en memoria al mismo tiempo.

Llamar a checkout de nuevo con un subdomain o una rama distinta cambia qué sesión está activa. No descarta las demás. Para abandonar un borrador en curso en lugar de simplemente alejarte de él, llama a discard_session.

​

Qué puede hacer el Admin MCP

​

Contenido

• read — Obtén el MDX completo de cualquier página en la rama de la sesión.
• search — Encuentra líneas que coincidan con una subcadena o expresión regular en todas las páginas.
• edit_page — Aplica una edición dirigida a una página.
• write_page — Sobrescribe el contenido MDX completo de una página.

​

Navegación

• list_nodes — Recorre el árbol de navegación con filtros opcionales. Filtra por parentId (usa recursive: true para incluir todos los descendientes), uno o más tipos de nodo, o cualquier ámbito de división: language, version, tab, dropdown, anchor, product o item. Los resultados se paginan a través de un cursor opaco.
• create_node — Agrega una nueva página, grupo, pestaña, ancla, versión, idioma, producto o desplegable.
• update_node — Actualiza las propiedades de un nodo en su lugar (renombrar un grupo, cambiar un icono, establecer una versión predeterminada).
• move_node — Mueve un nodo, incluido renombrar la ruta de una página.
• delete_node — Elimina un nodo de la navegación.

​

Configuración

• update_config — Modifica docs.json (tema, raíces de navegación, integraciones, configuración de SEO).

​

Sesión

• list_deployments — Lista las implementaciones a las que tu conexión puede acceder, devolviendo cada {subdomain, name}. Llama a esto para descubrir qué subdomain pasar a checkout.
• checkout — Vincula una sesión a una rama para un subdomain de implementación dado, o cambia qué sesión de implementación está activa.
• list_branches — Lista las ramas de Git disponibles para el proyecto de una implementación, con filtrado opcional por query. Devuelve los nombres de las ramas, el total y la rama de despliegue. Llama a esto antes de checkout para adjuntarte a una rama existente por nombre.
• get_session_state — Inspecciona la rama actual, los archivos editados y el diff de navegación pendiente.
• diff — Lista todos los cambios entre la sesión y main.
• save — Abre una pull request o hace commit en la rama de la sesión.
• discard_session — Descarta la sesión y sus cambios pendientes.

​

Ejemplos de prompts

Después de conectarte al Admin MCP, puedes manejarlo con prompts en lenguaje natural. Por ejemplo:

• “Haz checkout de una rama llamada add-billing-faq y crea una nueva página bajo el grupo FAQ titulada ‘Billing’. Redacta respuestas para las cinco preguntas de este issue de Linear.”
• “Encuentra todas las páginas que mencionen el campo obsoleto legacy_token y actualiza el ejemplo para que use api_key en su lugar. Guarda como PR titulada ‘docs: replace legacy_token references’.”
• “Reorganiza la referencia de API: mueve las páginas de webhooks a un nuevo grupo llamado ‘Webhooks’ y actualiza los iconos para que coincidan con el resto de la sección.”

​

Buenas prácticas

Abrir la URL del editor

Cada checkout devuelve un editorUrl. Ábrelo en una pestaña aparte para ver cómo se renderizan los cambios de la IA en vivo en el editor del panel mientras escribes prompts.

Revisar cada PR

El Admin MCP es lo suficientemente potente como para reescribir cientos de páginas en una sola sesión. Antes de fusionar, lee el diff de la PR y revisa la vista previa renderizada. No apruebes cambios grandes sin revisarlos.

Usar slugs para los nombres de ramas

Pasa un slug a checkout (por ejemplo, add-quickstart) para que la rama generada automáticamente sea legible. Sin él, el nombre de la rama deriva del token de sesión y es difícil de reconocer en tu repositorio.

Mantener las sesiones enfocadas

Mantén cada sesión enfocada en un solo cambio. Las sesiones más pequeñas producen pull requests más fáciles de revisar y preservan las ventanas de contexto de los agentes. Usa discard_session y vuelve a llamar a checkout para cambiar a un trabajo no relacionado.

Las sesiones mantienen una rama en memoria en el lado de Mintlify. Si abandonas una sesión sin guardarla ni descartarla, la rama persiste hasta que tu próximo checkout la sobrescriba. Evita dejar ramas mintlify-mcp/* obsoletas en tu repositorio. Límpialas periódicamente.

​

Desconectar o revocar el acceso

Desconecta el Admin MCP cuando ya no quieras que una herramienta de IA edite tu proyecto, o cuando quieras forzar un nuevo inicio de sesión de OAuth.

• Revocar la autorización de OAuth: En tu panel de Mintlify, ve a Settings → Security & access → Connected apps y revoca la entrada de la herramienta de IA que conectaste. Revocar invalida cualquier token de sesión activo de inmediato, por lo que las llamadas a herramientas en curso fallan y la herramienta debe completar un nuevo inicio de sesión de OAuth en la próxima llamada.
• Eliminar el conector en el cliente:
  • Claude: Settings → Connectors, luego elimina la entrada del Admin MCP.
  • Claude Code: claude mcp remove mintlify.
  • Cursor: elimina la entrada mintlify de mcp.json y recarga.
  • Codex: elimina el bloque [mcp_servers.mintlify] de ~/.codex/config.toml.

Revocar la autorización de OAuth no afecta a las pull requests que el MCP ya haya abierto. Cierra o revierte esas PRs en tu proveedor de Git si quieres deshacer los cambios pendientes.