DOCUMENTACIÓN · TNL-CMS 0.47.139

API y conexión MCP

Capítulo 18 de 22 · Uso, configuración y comprobaciones.

La API permite que un cliente autorizado consulte y gestione el CMS. MCP presenta herramientas con nombres, esquemas y permisos; no es una instrucción para que una IA adivine rutas o modifique archivos por su cuenta.

Gestión de conexiones API y MCP
TNL-CMS 0.47.139 · Instalación local de demostración, con datos de ejemplo. Pulsa la imagen para ampliarla.

En algunas pantallas esta sección aparece como «Claude (API)», aunque la API también admite otros clientes MCP compatibles.

Crear una conexión

  1. Entra con una cuenta autorizada para administrar integraciones.
  2. Abre la sección API del panel y crea una credencial o el flujo OAuth disponible.
  3. Elige únicamente los permisos que necesitará el cliente.
  4. Configura el endpoint MCP mostrado por tu sitio.
  5. Prueba la conexión con información del sitio y el catálogo antes de escribir contenido.

El endpoint habitual es /api/v1/mcp, con JSON-RPC sobre HTTP POST. Una visita directa desde la barra de un navegador no realiza por sí sola una sesión MCP. La autenticación se configura en el cliente y no debe quedar incrustada en páginas públicas.

Ejemplo de configuración

Utiliza siempre tu dominio y una credencial creada para ese uso. El siguiente valor es un marcador de posición, no una clave funcional:

{
  "mcpServers": {
    "tnl-cms": {
      "type": "http",
      "url": "https://tu-dominio.example/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer TU_TOKEN_PRIVADO"
      }
    }
  }
}

No pegues una credencial real en una entrada, imagen, repositorio público o manual. Si alguien necesita comprobar una conexión, revisa el alcance y el canal utilizado antes de compartir acceso.

Descubrir las funciones reales

Empieza con api_connection_info, site_info y editor_capabilities. Después consulta tools/list. El número de herramientas depende de los módulos y permisos de esa conexión; no es una cifra fija para todas las instalaciones.

Para construir páginas consulta editor_blocks_catalog, los patrones y el esquema de estilos. Las portadas tienen sus herramientas de catálogo, lectura y guardado. Sliders, tablas y otros componentes ofrecen sus esquemas o ayudas cuando estén disponibles.

Permisos de diseño y publicación

Leer contenido no concede permiso para publicarlo. Editar entradas no equivale a modificar cabecera, pie, menús o tema. Las herramientas de diseño requieren su permiso, y la publicación tiene una autorización propia.

Si una herramienta no aparece, comprueba módulo y permiso antes de concluir que la función no existe. Después de cambiar módulos, actualizar el CMS o ajustar credenciales, vuelve a pedir el catálogo. Un cliente puede conservar una lista antigua hasta reconectar.

Cambios comprobables

Usa content_get para leer la versión actual antes de sustituir bloques. En modificaciones amplias utiliza dry_run cuando la herramienta lo admita y revisa changes. Conserva el identificador y URL de la respuesta para comprobar qué se guardó realmente.

Las operaciones de contenido pueden crear revisiones restaurables; eso no autoriza a borrar páginas ajenas al encargo. Un buen cliente modifica solo los campos necesarios, comprueba el resultado y mantiene los permisos del usuario.

Resolver errores de conexión

Un 401 suele indicar una credencial ausente, caducada o revocada. Un permiso insuficiente requiere revisar el perfil autorizado, no inventar otra herramienta. Si recibes HTML donde esperas JSON, comprueba endpoint, autenticación y si un proxy o pantalla de acceso está interceptando la solicitud.

El editor del sitio y un cliente MCP externo pueden compartir herramientas, pero no necesariamente sesión visual. Una credencial API válida no implica que el navegador haya iniciado sesión en /admin.

Continúa la guía

La disponibilidad de pantallas depende de los módulos activos, tus permisos y los servicios conectados. Las capturas muestran una instalación de demostración, no datos del panel de clientes.

¿Necesitas ayuda con tu instalación? Contacta con TuNegocioEnLinea.net.