# Referencia de evoMCP

> Endpoint, OAuth, permisos, reglas de aprobación y lista completa de herramientas MCP de evoMCP, agrupadas por componente, con permiso y aprobación.

# Referencia de evoMCP

## Endpoint y protocolo

| Elemento | Valor |
| --- | --- |
| URL | `https://tu-sitio/mcp` |
| Método | Solo `POST`. Un mensaje JSON-RPC por petición, sin lotes y sin sesiones |
| Versiones del protocolo | `2026-07-28` y, por compatibilidad, `2025-11-25`, `2025-06-18` y `2025-03-26` |
| Métodos | `initialize`, `ping`, `server/discover`, `tools/list`, `tools/call`. Solo hay herramientas: no hay recursos ni prompts |
| Cabeceras con `Mcp-Protocol-Version: 2026-07-28` | `Mcp-Method` en toda petición salvo `initialize`, y `Mcp-Name` en `tools/call`; deben coincidir con el cuerpo |
| Autenticación | `Authorization: Bearer <token>` |
| Tamaño | Petición hasta 256 KB; respuesta hasta 1 MB (si se supera, la herramienta devuelve un error y pide paginar o filtrar) |
| Notificaciones | Se responden con 202 |

Códigos HTTP que puedes ver:

| Código | Cuándo |
| --- | --- |
| 400 | JSON no válido, mensaje JSON-RPC mal formado, versión de protocolo no soportada o cabeceras `Mcp-*` que no coinciden |
| 401 | Sin autenticar o token no válido. Incluye `WWW-Authenticate` con la ruta de metadatos OAuth |
| 403 | Origen no permitido |
| 404 | El endpoint está desactivado en las opciones |
| 405 | Método distinto de `POST` |
| 413 | Petición demasiado grande |
| 429 | Límite por IP (600 por minuto), límite por conexión o cuota mensual agotada |

Una herramienta que la conexión no puede usar no aparece en `tools/list`, y llamarla devuelve «Herramienta desconocida», igual que si no existiera.

### Respuestas de las herramientas

El resultado va en `structuredContent` y en el texto, con la forma `{"data": ...}`. Si la herramienta puede devolver texto procedente de terceros (artículos, menús, registros, datos de visitantes), el resultado incluye `"untrusted_content": true` y un aviso: ese texto no debe tratarse como instrucciones. Los errores de validación y de permisos llegan con `isError: true`.

Cuando una escritura exige aprobación, no se ejecuta. La respuesta es:

```
{"data": {"status": "pending_approval", "approval_id": 12, "message": "..."}}
```

Antes de dejarla pendiente, si la herramienta admite `dry_run`, se valida con una simulación: un error de validación llega al agente en el momento y no cuando un humano ya ha aprobado.

### `dry_run`

Las herramientas con `dry_run` aceptan un argumento booleano `dry_run`. Con `true`, simulan la acción y devuelven lo que harían, sin cambiar nada y sin pedir aprobación.

## Herramientas propias del servidor

Están siempre disponibles para cualquier conexión.

| Herramienta | Qué hace |
| --- | --- |
| `evomcp_capabilities` | Dice qué permisos tiene la conexión por componente, qué componentes existen en el sitio pero no están concedidos, cuántas herramientas ve y qué modo de aprobación tiene |
| `evomcp_approval_status` | Consulta el estado de una acción pendiente (`pending`, `executed`, `failed`, `rejected`, `expired`) y su resultado. Solo ve las aprobaciones de su propia conexión |

## Permisos y aprobación en las tablas

Cada herramienta pertenece a un componente y a un recurso de la matriz de permisos, que se escriben `componente/recurso`. El permiso es lo que la conexión necesita sobre ese par: lectura, escritura o full (las dos cosas).

La columna Aprobación puede valer:

| Valor | Significado |
| --- | --- |
| (vacío) | Herramienta de lectura. Nunca pide aprobación |
| Siempre | Pide aprobación en cualquier modo |
| Delicada | Pide aprobación en los modos «toda escritura» y «solo destructivas o delicadas» |
| Normal | Pide aprobación solo en el modo «toda escritura» |

La columna `dry_run` indica si admite el argumento. Las herramientas que cambian datos personales o los devuelven llevan la indicación en su descripción.

## Contenido (`content`)

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `content_search_articles` | Busca artículos por texto, categoría y estado. Lista paginada (hasta 50) | `content/articles` | Leer |  | No |
| `content_get_article` | Lee un artículo completo: texto, fechas, estado, categoría, metadatos | `content/articles` | Leer |  | No |
| `content_list_categories` | Lista las categorías de artículos visibles para el usuario de la conexión | `content/categories` | Leer |  | No |
| `content_create_article` | Crea un artículo nuevo como borrador | `content/articles` | Escribir | Normal | Sí |
| `content_update_article` | Modifica campos de un artículo. No cambia su estado de publicación | `content/articles` | Escribir | Delicada | Sí |
| `content_set_article_state` | Publica, despublica, archiva o manda a la papelera un artículo | `content/articles` | Escribir | Siempre | Sí |
| `content_create_category` | Crea una categoría de artículos que queda sin publicar | `content/categories` | Escribir | Normal | Sí |

Los artículos que no están publicados solo los ve quien puede editarlos (o, con `core.edit.own`, los suyos).

## Menús, módulos, medios, plantillas, usuarios, extensiones y configuración (`plg_evomcp_joomla`)

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `menus_list_menus` | Lista los menús del sitio | `menus/menus` | Leer |  | No |
| `menus_list_items` | Lista elementos de menú, filtrando por menú y estado | `menus/items` | Leer |  | No |
| `menus_get_item` | Lee un elemento de menú | `menus/items` | Leer |  | No |
| `menus_set_item_state` | Publica, despublica o manda a la papelera un elemento de menú | `menus/items` | Escribir | Delicada | Sí |
| `modules_list_modules` | Lista módulos del sitio por posición y estado | `modules/modules` | Leer |  | No |
| `modules_get_module` | Lee un módulo; los parámetros con aspecto de secreto salen ocultos | `modules/modules` | Leer |  | No |
| `modules_set_module_state` | Publica, despublica o manda a la papelera un módulo del sitio | `modules/modules` | Escribir | Delicada | Sí |
| `media_list_files` | Lista ficheros y carpetas dentro de `/images` (solo metadatos) | `media/files` | Leer |  | No |
| `templates_list_styles` | Lista los estilos de plantilla del sitio y de la administración | `templates/styles` | Leer |  | No |
| `users_list_users` | Lista usuarios: nombre, usuario, correo, estado y grupos. Datos personales | `users/users` | Leer |  | No |
| `users_get_user` | Lee un usuario. Datos personales | `users/users` | Leer |  | No |
| `users_list_groups` | Lista los grupos de usuarios | `users/groups` | Leer |  | No |
| `users_set_user_blocked` | Bloquea o desbloquea a un usuario | `users/users` | Escribir | Siempre | Sí |
| `extensions_list_extensions` | Lista extensiones instaladas: tipo, elemento, versión y si están activas | `extensions/extensions` | Leer |  | No |
| `extensions_set_enabled` | Activa o desactiva una extensión; no se pueden tocar las protegidas del núcleo | `extensions/extensions` | Escribir | Siempre | Sí |
| `config_get_site_settings` | Lee ajustes no sensibles de la configuración global. Nunca devuelve credenciales | `config/global` | Leer |  | No |
| `scheduler_list_tasks` | Lista las tareas programadas con su estado y última ejecución | `scheduler/tasks` | Leer |  | No |

## Entidades, opciones y copias (`entities`)

Esta capa trabaja sobre los modelos y los formularios de Joomla, de modo que valida igual que el administrador. El permiso real se comprueba por entidad con el componente y el recurso de cada una (artículos con `content/articles`, módulos con `modules/modules`, y así). El componente `entities` es la pasarela y exige Super User para concederse.

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `entities_list_types` | Lista las entidades que se pueden gestionar y lo que permite la conexión en cada una | `entities/generic` | Leer |  | No |
| `entities_describe` | Campos de una entidad tal como los define el formulario de Joomla (tipo, etiqueta, opciones), filtros y estados. En módulos, `context {"module":"mod_custom"}` | `entities/generic` | Leer |  | No |
| `entities_list` | Lista elementos con paginación y filtros (`search`, `state` y los de cada entidad) | `entities/generic` | Leer |  | No |
| `entities_get` | Lee un elemento completo; los secretos salen ocultos | `entities/generic` | Leer |  | No |
| `entities_save` | Crea (sin `id`) o edita (con `id`, solo los campos que cambian). Lo creado queda como borrador si la entidad lo admite | `entities/generic` | Escribir | Normal | Sí |
| `entities_set_state` | Publica, despublica, archiva o manda a la papelera hasta 50 elementos | `entities/generic` | Escribir | Delicada | Sí |
| `entities_delete` | Elimina definitivamente hasta 50 elementos que ya estén en la papelera | `entities/generic` | Escribir | Siempre | Sí |
| `options_get` | Lee las opciones de un componente con sus campos; los secretos salen ocultos | `entities/options` | Leer |  | No |
| `options_set` | Cambia opciones de un componente, validadas con su formulario. Guarda una copia previa | `entities/options` | Escribir | Siempre | Sí |
| `backups_list` | Lista las copias previas a cambios hechos por evoMCP, sin su contenido | `entities/backups` | Leer |  | No |
| `backups_restore` | Restaura una copia (opciones de componente, ajustes del tema, páginas del constructor, ajustes globales, ficheros). Guarda antes una copia del estado actual | `entities/backups` | Escribir | Siempre | Sí |

Entidades de serie: artículos, categorías de artículos, etiquetas, campos personalizados de artículos, menús, elementos de menú, módulos del sitio, estilos de plantilla, banners y sus clientes y categorías, contactos y sus categorías, canales de noticias y sus categorías, redirecciones, grupos de usuarios y niveles de acceso. Las extensiones pueden declarar las suyas con el evento `onEvomcpCollectEntities`.

Las opciones de `com_evomcp`, las de registro de usuarios y las de subida de ficheros de medios no se pueden cambiar con `options_set`; los permisos (`rules`), la licencia y los secretos tampoco.

## YOOtheme Pro (`yootheme`)

Estas herramientas solo existen si la plantilla YOOtheme está instalada. Las que cambian una página del constructor exigen que el grupo del usuario de la conexión tenga el filtro de texto de Joomla en «Sin filtro».

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `yootheme_list_pages` | Lista los artículos con una página del constructor | `yootheme/layouts` | Leer |  | No |
| `yootheme_get_layout` | Estructura de una página: secciones, filas, columnas y elementos con su ruta. Con `format=json`, el layout completo (hasta 150 KB) | `yootheme/layouts` | Leer |  | No |
| `yootheme_find_nodes` | Busca nodos por tipo de elemento y por texto; devuelve su ruta | `yootheme/layouts` | Leer |  | No |
| `yootheme_list_element_types` | Tipos de elemento del constructor instalados, con su grupo y si pueden contener otros | `yootheme/layouts` | Leer |  | No |
| `yootheme_describe_element` | Un tipo de elemento: dónde puede ir, qué hijos admite, campos y valores por defecto | `yootheme/layouts` | Leer |  | No |
| `yootheme_update_node_props` | Cambia propiedades de un nodo | `yootheme/layouts` | Escribir | Delicada | Sí |
| `yootheme_add_node` | Añade un nodo con sus hijos, validando la jerarquía y las propiedades | `yootheme/layouts` | Escribir | Delicada | Sí |
| `yootheme_move_node` | Mueve un nodo a otro padre o a otra posición | `yootheme/layouts` | Escribir | Delicada | Sí |
| `yootheme_duplicate_node` | Duplica un nodo con todo lo que contiene, justo después del original | `yootheme/layouts` | Escribir | Delicada | Sí |
| `yootheme_remove_node` | Quita un nodo con todo lo que contiene. Guarda antes una copia de la página | `yootheme/layouts` | Escribir | Siempre | Sí |
| `yootheme_replace_layout` | Sustituye el layout entero de una página, validado nodo a nodo. Guarda antes una copia | `yootheme/layouts` | Escribir | Siempre | Sí |
| `yootheme_create_page` | Crea una página del constructor nueva como borrador (sección, fila y columna) | `yootheme/layouts` | Escribir | Normal | Sí |
| `yootheme_get_theme_info` | Versión de YOOtheme Pro, estilos de la plantilla y número de páginas del constructor | `yootheme/theme` | Leer |  | No |
| `yootheme_get_theme_config` | Ajustes del personalizador. Sin ruta, los grupos de primer nivel; con una ruta con puntos, ese valor | `yootheme/theme` | Leer |  | No |
| `yootheme_set_theme_config` | Cambia o quita un ajuste del tema por ruta con puntos. Guarda antes una copia, restaurable con `backups_restore` | `yootheme/theme` | Escribir | Siempre | Sí |

La jerarquía válida es layout, sección, fila, columna y elementos. La biblioteca del constructor y las plantillas de página del constructor no tienen herramientas propias.

## Sistema (`system`, `config`, `scheduler`)

Solo superusuarios. El núcleo de Joomla y evoMCP no se actualizan desde estas herramientas.

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `system_info` | Versión de Joomla, PHP y base de datos, estado del sitio, número de extensiones y si hay actualizaciones | `system/info` | Leer |  | No |
| `system_list_updates` | Actualizaciones de extensiones que Joomla ya conoce | `system/updates` | Leer |  | No |
| `system_find_updates` | Consulta los servidores de actualización (todas las extensiones o una). Hace peticiones de red | `system/updates` | Escribir | Normal | No |
| `system_apply_update` | Actualiza una extensión con una de las actualizaciones listadas | `system/updates` | Escribir | Siempre | Sí |
| `system_install_from_url` | Instala o actualiza una extensión desde una URL https | `system/install` | Escribir | Siempre | Sí |
| `system_uninstall_extension` | Desinstala una extensión por su id. No las protegidas del núcleo ni evoMCP | `system/install` | Escribir | Siempre | Sí |
| `system_set_config` | Cambia ajustes de la configuración global de una lista cerrada de claves. Guarda antes una copia | `config/global` | Escribir | Siempre | Sí |
| `system_clear_cache` | Limpia la caché de Joomla (todos los grupos o uno) y las entradas caducadas | `system/cache` | Escribir | Delicada | Sí |
| `system_read_log` | Lista los registros de Joomla o lee las últimas líneas de uno, con filtro de texto. Pueden contener IP y correos | `system/logs` | Leer |  | No |
| `scheduler_set_task_state` | Activa o desactiva una tarea programada | `scheduler/tasks` | Escribir | Delicada | Sí |
| `scheduler_run_task` | Ejecuta una tarea programada ahora mismo | `scheduler/tasks` | Escribir | Siempre | Sí |

Límites de `system_install_from_url`: solo https y sin puerto; solo servidores de los sitios de actualización instalados más la lista de las opciones de evoMCP; solo IP públicas, y cada redirección se vuelve a comprobar; máximo 40 MB. `system_set_config` nunca toca credenciales, rutas ni sesiones. `system_read_log` solo lee la carpeta de registros, por nombre y solo el final del fichero.

## Capa avanzada: SQL y ficheros (`advanced`)

Viene deshabilitada de fábrica y solo la usa un superusuario. Hay tres cerrojos y hacen falta los tres:

1. El plugin «evoMCP - Capa avanzada» se instala deshabilitado y hay que habilitarlo a mano.
2. El interruptor «Capa avanzada (SQL y ficheros)» de las opciones de evoMCP está apagado y hay que encenderlo.
3. La conexión necesita permiso `full` sobre el componente `advanced`, y solo un Super User puede concedérselo.

El instalador no habilita este plugin, ni al instalar ni al actualizar. Si la capa está encendida, la pestaña Conectar lo avisa.

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `advanced_sql_read` | `SELECT`, `SHOW`, `DESCRIBE` y `EXPLAIN SELECT`: una sola sentencia, sin comentarios, hasta 200 filas, en una transacción de solo lectura con límite de tiempo. Datos personales posibles | `advanced/sql` | Leer |  | No |
| `advanced_sql_write` | `INSERT`, `UPDATE`, `DELETE` o `CREATE TABLE`, una sentencia. `UPDATE` y `DELETE` exigen un `WHERE` real y antes se copia la tabla | `advanced/sql` | Full | Siempre | Sí |
| `advanced_files_list` | Lista una carpeta de las raíces permitidas, sin ficheros ocultos | `advanced/files` | Leer |  | No |
| `advanced_files_read` | Lee un fichero de texto de hasta 200 KB; de un binario devuelve tamaño y huella | `advanced/files` | Leer |  | No |
| `advanced_files_write` | Crea o sobrescribe un fichero de hasta 2 MB. Copia previa de lo que se sobrescribe | `advanced/files` | Full | Siempre | Sí |
| `advanced_files_delete` | Elimina un fichero permitido, con copia previa si pesa menos de 2 MB | `advanced/files` | Full | Siempre | Sí |

Reglas de SQL: se usa `#__` como prefijo de tablas. No se pueden leer las tablas de credenciales, sesiones ni las internas de evoMCP, y las columnas que parecen secretos salen ocultas. No se escribe en tablas de evoMCP ni de credenciales. La copia previa de una tabla se llama `<tabla>_bak_evomcp_<fecha>` y el mantenimiento diario la borra a los 30 días.

Reglas de ficheros:

| Raíz | Carpeta | Escritura |
| --- | --- | --- |
| `images` | `images` | Sí |
| `media` | `media` | Sí |
| `templates` | `templates` (no las plantillas del núcleo ni `yootheme`) | Sí |
| `tmp` | `tmp` | No |
| `logs` | `administrator/logs` | No |

No se admiten `..`, enlaces simbólicos ni ficheros ocultos. Solo tipos no ejecutables y nunca código PHP. El HTML solo se escribe en plantillas y los SVG no pueden llevar scripts.

## Herramientas que añaden otras extensiones evo

Cuando están instaladas, evoLeadGate, evoOrigin y evoYTAccess registran sus herramientas en evoMCP. Se documentan aquí porque cuelgan de su propio componente en la matriz de permisos.

| Herramienta | Qué hace | Recurso | Permiso | Aprobación | `dry_run` |
| --- | --- | --- | --- | --- | --- |
| `evoleadgate_list_leads` | Lista leads capturados: formulario, correo, fecha, verificación, entrega. Datos personales | `evoleadgate/leads` | Leer |  | No |
| `evoleadgate_get_lead` | Lee un lead: campos del formulario, consentimientos, atribución UTM y estado de los correos. No incluye IP ni agente de usuario | `evoleadgate/leads` | Leer |  | No |
| `evoleadgate_lead_stats` | Estadísticas agregadas por formulario y por día, sin datos personales | `evoleadgate/leads` | Leer |  | No |
| `evoleadgate_delete_leads` | Elimina leads y sus descargas por id, hasta 50 | `evoleadgate/leads` | Escribir | Siempre | Sí |
| `evoorigin_stats` | Visitas por mes, fuente, medio y campaña, sin datos personales | `evoorigin/stats` | Leer |  | No |
| `evoorigin_list_visits` | Lista visitas: origen, página de entrada, IP truncada, usuario si se identificó. Datos personales | `evoorigin/visits` | Leer |  | No |
| `evoorigin_list_leads` | Lista resúmenes de atribución de leads: primer y último origen, número de visitas | `evoorigin/leads` | Leer |  | No |
| `evoorigin_get_lead_attribution` | Atribución de un lead por su referencia | `evoorigin/leads` | Leer |  | No |
| `evoorigin_delete_visits` | Elimina visitas por id, hasta 100 | `evoorigin/visits` | Escribir | Siempre | Sí |
| `evoorigin_delete_leads` | Elimina resúmenes de atribución por id, hasta 100 | `evoorigin/leads` | Escribir | Siempre | Sí |
| `evoorigin_purge_now` | Ejecuta ahora la purga de retención según los plazos configurados | `evoorigin/visits` | Escribir | Siempre | Sí |
| `evoytaccess_get_settings` | Lee los ajustes de evoYTAccess | `evoytaccess/settings` | Leer |  | No |
| `evoytaccess_set_settings` | Cambia los ajustes de evoYTAccess | `evoytaccess/settings` | Escribir | Siempre | Sí |

## Para desarrolladores: registrar herramientas desde una extensión

Un plugin del grupo `evomcp`, o un plugin de sistema que escuche `onEvomcpCollect`, registra un proveedor de herramientas:

```
public function onEvomcpCollect(Event $event): void
{
    $event->getArgument('registry')->register(new MiProveedor($this->getApplication()));
}
```

`MiProveedor` implementa `ToolProvider`, contrato versión 1:

| Método | Qué devuelve |
| --- | --- |
| `contract()` | La versión del contrato. Los proveedores con otra versión se rechazan |
| `component()` | Clave, título y árbol de recursos para la matriz de permisos |
| `tools()` | Las herramientas: nombre, esquema JSON de entrada, permiso `read`, `write` o `full`, anotaciones, `personalData`, `untrustedContent` y `dryRun` |
| `call()` | La ejecución de una herramienta |

El núcleo oculta las herramientas que la conexión no puede usar, valida los argumentos contra el esquema, aplica la aprobación y audita. Las anotaciones `destructiveHint`, `consequentialHint` y `approvalRequired` determinan cuándo se pide aprobación. Para declarar entidades gestionables con las herramientas genéricas, escucha `onEvomcpCollectEntities` y registra una definición en el `EntityRegistry`.

## OAuth 2.1

| Elemento | Valor |
| --- | --- |
| Metadatos del recurso | `/.well-known/oauth-protected-resource` |
| Metadatos del servidor | `/.well-known/oauth-authorization-server` |
| Autorización | `/oauth/authorize`: inicio de sesión de Joomla y pantalla de consentimiento |
| Token | `/oauth/token` |
| Registro dinámico de clientes | `/oauth/register` |
| Clientes identificados por documento de metadatos (CIMD) | Admitidos, con protección contra SSRF |
| Flujos | Código de autorización con PKCE `S256` y refresco con rotación |
| Autenticación del cliente | Ninguna (cliente público) |
| Ámbito | `mcp` |
| Prefijos de token | `evomcp_` (token manual), `evomat_` (acceso), `evomrt_` (refresco) |

El consentimiento guarda solo lo que el usuario desmarca. Por eso, los componentes que lleguen después a una conexión ya autorizada se ven sin repetir el consentimiento; si el cliente ya tiene la lista de herramientas en memoria, hay que reconectar el conector para refrescarla. Una conexión por OAuth tiene como techo la matriz de la conexión elegida.

---

https://evoaddons.com/es/documentacion/evomcp-referencia