Servidor MCP de ComStack

Qué es esto

El servidor MCP de ComStack es la interfaz de integración que los asistentes de IA utilizan para gestionar proyectos de ComStack. Expone un kit de herramientas CMS headless completo (CRUD de páginas, temas, publicación en dos pasos, sincronización con GitHub y sesiones de voz en vivo) a través del Model Context Protocol.

Transporte: HTTP con streaming (POST /mcp) — sin estado. Modo Stdio para desarrollo local. Endpoint de producción: https://api.comstack.ai/mcp

Cómo funciona

Cada llamada a una herramienta incluye su propio project_id, por lo que una única sesión autenticada puede gestionar todos los proyectos a los que el usuario tiene acceso. Las herramientas se filtran según el rol del usuario: un visor no ve herramientas exclusivas de gestor, como publish.

Las operaciones destructivas están protegidas por un flujo de dos pasos: publish genera un manifiesto y devuelve un token de confirmación; publish-confirm utiliza dicho token para desplegar. Se requiere repetir el project_name en todas las herramientas destructivas como medida de seguridad entre proyectos.

Se aplican dos salvaguardas adicionales a la ruta de publicación:

1. Confirmación de project_name. publish, publish-confirm, delete-page, set-page-status y otras herramientas destructivas requieren un argumento project_name que debe coincidir exactamente con el nombre almacenado del proyecto. Si no coinciden, se devuelve un error mostrando tanto el nombre esperado como el proporcionado.
2. Simulación / confirmación de publicación. publish devuelve un manifiesto de páginas listas (READY) con un diff por página (is_new, change_type, títulos, descripciones, tamaños en bytes, URLs de destino) además de un confirmation_token (TTL de 5 minutos, de un solo uso). Solo publish-confirm realiza el despliegue. En el momento de la confirmación, el servidor vuelve a generar el manifiesto y rechaza la operación si el conjunto de páginas listas ha cambiado.

Cuándo usarlo

Utiliza el servidor MCP cuando desees que un asistente de IA (Claude, Cursor o cualquier cliente compatible con MCP) gestione el contenido de un proyecto de ComStack: crear páginas, aprobar y traducir, y publicar en el sitio en vivo.

Parámetros / campos / entradas

Cada herramienta con ámbito de proyecto requiere un argumento project_id. Las herramientas destructivas también requieren project_name, que debe coincidir exactamente con el nombre almacenado del proyecto.

Modos de autenticación

Modo	Cuándo usarlo
OAuth 2.1 Bearer	Usuarios humanos conectándose vía Claude, Cursor u otro cliente compatible con OAuth
Cabeceras x-api-key + x-project-id	Servicios headless y CI — usar claves de servicio (key_type: "service")

Límites de tasa

Ruta	Límite
POST /mcp	60 peticiones / min / IP
Rutas OAuth	30 peticiones / min / IP
Fallos de autenticación	10 fallos / min / IP

Los cuerpos de petición superiores a 1 MB son rechazados con un error HTTP 413.

Filtrado de herramientas por rol

tools/list se filtra según el rol del usuario. Niveles de rol (de mayor a menor): administrador de plataforma → gestor → editor → visor → ninguno. Las herramientas fuera de tu rol están ocultas; no solo se rechazan, sino que no aparecen en la lista.

Ejemplo

Un flujo de trabajo típico de sesión:

1. whoami                → confirm authenticated identity
2. list-my-projects      → pick a project_id
3. get-project-state     → see live pages, drafts, available templates
4. get-doc-template <id> → get the metadata example and markdown template
5. create-page           → new page draft (validates everything at once)
   update-page           → edit an existing page
6. approve-page          → translations run asynchronously; page moves to ready
7. publish               → review the manifest + get a confirmation_token
8. publish-confirm       → deploy; poll publish-status for published_urls

Errores comunes

Error	Causa	Solución
InvalidRequest	Clave API asignada al proyecto incorrecto	Verifica que el project_id coincida con el ámbito de la clave
403 project_name mismatch	El nombre suministrado no coincide con el almacenado	Llama a get-project-state para obtener el nombre correcto
HTTP 429	Límite de tasa excedido	Espera e intenta de nuevo
HTTP 413	Cuerpo de petición superior a 1 MB	Reduce el tamaño del contenido
Token expired	Cadena de refresco OAuth rota	Vuelve a autenticarte
Validation error	Campos de metadatos faltantes o inválidos	La respuesta de error lista todos los problemas a la vez con soluciones

Relacionado

• Instalación — conecta Claude u otro cliente paso a paso
• Herramientas — catálogo completo de herramientas con requisitos de rol y anotaciones
• Recursos — recursos MCP disponibles para asistentes de IA
• Ejemplos — ejemplos de flujos de trabajo de extremo a extremo
• Seguridad — modelo de amenazas y salvaguardas