La WordPress Abilities API es un registro de operaciones que un plugin, un tema o el propio núcleo declaran en un formato único y predecible: nombre, categoría, esquema de entrada y de salida, comprobación de permisos y función de ejecución. Esta página es una referencia: qué es, cómo registrar una ability, qué endpoints REST hay, cómo funcionan los permisos, qué añadieron las versiones 7.0 y 7.1 y dónde encaja MCP Adapter. Si buscas ejemplos de flujos de trabajo construidos sobre abilities, consulta el artículo WordPress e IA: la Abilities API desde WordPress 6.9.
Qué es la Abilities API de WordPress
La dev note de make.wordpress.org define una ability así:
“Una ability es una unidad de funcionalidad autónoma con entradas, salidas, permisos y lógica de ejecución definidos.”
Jonathan Bossenger, Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Todas las abilities registradas van a un registro central. De ese registro tiran el código PHP en el servidor, el cliente JavaScript del escritorio, la API REST y los agentes de IA conectados mediante MCP Adapter. El plugin describe la operación una sola vez, y cada uno de esos canales la ve con la misma forma, el mismo esquema y la misma comprobación de permisos.
El anuncio de la versión 6.9 lo plantea desde el punto de vista de los permisos:
“La nueva Abilities API proporciona un sistema de permisos estandarizado y legible por máquinas que abre la puerta a flujos de trabajo de nueva generación impulsados por IA y automatizados.”
WordPress News, WordPress 6.9 “Gene”, traducción propia
Cada ability pertenece exactamente a una categoría:
“Cada ability debe pertenecer exactamente a una categoría. Las categorías tienen un slug, una etiqueta y una descripción.”
Common APIs Handbook, Abilities API, traducción propia
Desde qué versión de WordPress está la Abilities API
La Abilities API entró en el núcleo con WordPress 6.9, publicado el 2 de diciembre de 2025. El handbook lo dice sin rodeos en el recuadro de la parte superior de la página:
“La Abilities API solo está disponible para WordPress 6.9 y versiones posteriores.”
Common APIs Handbook, Abilities API, traducción propia
Las versiones siguientes ampliaron la API sin cambiar sus bases:
| Versión | Fecha | Qué se añadió |
|---|---|---|
| 6.9 “Gene” | 2 de diciembre de 2025 | registro, categorías, esquemas, permisos, endpoints wp-abilities/v1 |
| 7.0 | dev note del 24 de marzo de 2026 | cliente JavaScript: @wordpress/abilities y @wordpress/core-abilities |
| 7.1 “Mary Lou” | 19 de agosto de 2026 | flag meta.public, cuatro filtros del ciclo de ejecución |
Un plugin que también deba funcionar en instalaciones anteriores a 6.9 comprueba que la función existe antes de registrar nada: la dev note de make.wordpress.org recomienda la condición function_exists( 'wp_register_ability' ), que es también la primera línea del ejemplo de más abajo.
El contexto más amplio de la versión 7.0, incluido el resto de cambios relacionados con la IA, lo cubre nuestra guía de WordPress 7.0 y su integración con IA.
Cómo registrar una ability en WordPress
El registro tiene dos pasos: primero la categoría y después la ability. Cada paso tiene su propio hook y el orden importa.
Cómo registrar una categoría de abilities
“Las categorías deben registrarse antes que las abilities que hacen referencia a ellas, usando el hook wp_abilities_api_categories_init.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Una categoría tiene slug, etiqueta y descripción. El argumento category al registrar una ability es obligatorio y debe apuntar al slug de una categoría que ya exista en el registro.
Hook wp_abilities_api_init
La ability en sí se registra en una acción distinta. Registrarla en otro punto no funciona:
“Las abilities deben registrarse en el action hook wp_abilities_api_init. Intentar registrar abilities fuera de este hook generará un aviso _doing_it_wrong() y el registro de la ability fallará.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Ejemplo de wp_register_ability
La firma de la función según el Code Reference:
function wp_register_ability( string $name, array $args ): ?WP_Ability {Fuente: Code Reference, wp_register_ability().
Si todo va bien, la función devuelve la instancia registrada de WP_Ability; si falla, null. Un ejemplo mínimo: una categoría y una ability de solo lectura que devuelve el número de entradas publicadas.
if ( function_exists( 'wp_register_ability' ) ) {
add_action( 'wp_abilities_api_categories_init', function () {
wp_register_ability_category( 'mi-plugin', array(
'label' => 'Mi plugin',
'description' => 'Operaciones que expone Mi plugin.',
) );
} );
add_action( 'wp_abilities_api_init', function () {
wp_register_ability( 'mi-plugin/numero-de-entradas', array(
'label' => 'Número de entradas publicadas',
'description' => 'Devuelve el número de entradas publicadas.',
'category' => 'mi-plugin',
'output_schema' => array( 'type' => 'integer' ),
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'execute_callback' => function () {
return (int) wp_count_posts()->publish;
},
'meta' => array(
'show_in_rest' => true,
'annotations' => array( 'readonly' => true ),
),
) );
} );
}Esta ability no recibe datos, así que no lleva input_schema. Devuelve un valor, así que output_schema es obligatorio.
Nombre de una ability y espacio de nombres
“El formato debe ser namespace/ability-name”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
El nombre se compone de minúsculas, números, guiones y una barra. El espacio de nombres suele ser el slug del plugin, lo que evita colisiones entre plugins que registran operaciones parecidas.
input_schema y output_schema en la Abilities API
Los esquemas no son un extra para la documentación. El núcleo valida con ellos los datos de entrada antes de la ejecución y los de salida después.
“Definir esquemas es obligatorio cuando hay un valor que pasar o devolver.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
El validador no cubre la especificación completa de JSON Schema:
“WordPress implementa un validador basado en un subconjunto de JSON Schema, versión 4.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
En la práctica, eso significa escribir los esquemas con la sintaxis del draft 4 y tener cuidado con las palabras clave que quedan fuera de ese subconjunto.
permission_callback y execute_callback
Los dos callbacks son obligatorios. El Code Reference los describe así:
“Obligatorio. Una función de callback para comprobar los permisos antes de la ejecución.”
Code Reference, wp_register_ability(), traducción propia
“Obligatorio. Una función de callback que se ejecuta cuando se invoca la ability.”
Code Reference, wp_register_ability(), traducción propia
El callback de permisos recibe los mismos datos que el de ejecución, de modo que puede decidir en función de la entrada concreta, por ejemplo permitir editar solo una entrada de la que el usuario es autor:
“Recibe la misma entrada que el callback de ejecución y debe devolver un booleano o un WP_Error”
Code Reference, wp_register_ability(), traducción propia
Cómo devolver errores en execute_callback
Un error se devuelve como objeto, no como excepción ni como resultado vacío:
“Las abilities deben gestionar los errores de forma controlada devolviendo objetos WP_Error:”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Anotaciones readonly, destructive e idempotent
Las anotaciones de meta.annotations describen la naturaleza de la operación. readonly marca una ability que no modifica nada:
“Opcional. Si es true, la ability no modifica su entorno.”
Code Reference, wp_register_ability(), traducción propia
Las otras dos anotaciones son destructive e idempotent. No son decorativas: de ellas depende el método HTTP al llamar por REST, y un cliente, por ejemplo un agente de IA, puede usarlas para saber si una operación se puede repetir.
En este sitio funciona nuestro propio servidor MCP, descrito en /.well-known/mcp/server-card.json, y solo expone herramientas de lectura. El mismo criterio sirve para las abilities: la primera versión de una integración con un agente son abilities con readonly: true, llamadas por GET. Las operaciones de escritura llegan después, cada una con su propio permission_callback.
Endpoints REST de la Abilities API
En WordPress 6.9 una ability no aparece en la API REST de forma automática. Hay que declararlo:
“Esto es posible estableciendo el argumento meta.show_in_rest en true al registrar una ability.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Los endpoints viven en el espacio de nombres wp-abilities/v1: listado de abilities, una ability concreta y ejecución. La ruta de ejecución es esta:
GET|POST|DELETE /wp-abilities/v1/abilities/{name}/runFuente: Make WordPress Core, Abilities API in WordPress 6.9.
Autenticación en la Abilities API
“El acceso a todos los endpoints de la REST API de Abilities requiere un usuario autenticado.”
Make WordPress Core, Abilities API in WordPress 6.9, traducción propia
Esto incluye el listado de abilities. Sirven la cookie de sesión, las application passwords o un mecanismo de autenticación propio. Un cliente anónimo ni siquiera ve qué abilities existen en el sitio.
Cómo ejecutar una ability por la API REST
El método HTTP del endpoint run lo determinan las anotaciones. Una ability readonly se llama con GET, una ability destructive e idempotent a la vez con DELETE, y en el resto de casos:
“Todos los demás casos: usa POST”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, traducción propia
La documentación REST del repositorio del proyecto deja claro que, para las abilities de solo lectura, es un requisito y no una recomendación:
”- Las abilities de solo lectura deben usar GET (
readonly: true)”GitHub, WordPress/abilities-api, docs/rest-api.md, traducción propia
Con GET y DELETE los datos de entrada no van en el cuerpo de la petición, sino en el parámetro input como JSON codificado en la URL.
Abilities API en JavaScript
WordPress 7.0 añadió un cliente para el navegador en dos paquetes. @wordpress/abilities es el almacén de abilities en sí, y @wordpress/core-abilities carga por REST las abilities registradas en el servidor:
“Esto cargará tanto @wordpress/core-abilities como su dependencia @wordpress/abilities, y obtendrá y registrará automáticamente todas las abilities del lado del servidor.”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, traducción propia
Los errores del cliente JS tienen códigos fijos. Una validación fallida da ability_invalid_input o ability_invalid_output, y una denegación de permisos:
“Si el callback de permisos devuelve false, se lanza un error con el código ability_permission_denied.”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, traducción propia
Abilities API en WordPress 7.1
El anuncio de la versión 7.1 resume los cambios en una frase:
“La Abilities API se basa en la infraestructura introducida en WordPress 6.9 con un ciclo de vida de ejecución filtrable, validación personalizada y descubrimiento compartido.”
WordPress News, WordPress 7.1 “Mary Lou”, traducción propia
Flag public en la Abilities API
WordPress 7.1 introdujo meta.public, un flag común de exposición a clientes. Rellena show_in_rest, pero un show_in_rest indicado de forma explícita tiene prioridad, y el valor por defecto sigue siendo false:
$show_in_rest = $meta['show_in_rest'] ?? $meta['public'] ?? false;Fuente: Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1.
El flag decide la visibilidad, no el acceso:
“El indicador public controla la visibilidad en el descubrimiento y la exposición a los clientes.”
Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1, traducción propia
Una ability marcada como pública sigue pasando por permission_callback. El flag public no lo sustituye.
Filtros del ciclo de ejecución de una ability
“La Abilities API ofrecía anteriormente las acciones wp_before_execute_ability y wp_after_execute_ability.”
Make WordPress Core, New execution lifecycle filters for the Abilities API in WordPress 7.1, traducción propia
A esas dos acciones de 6.9, la versión 7.1 añadió cuatro filtros:
| Filtro | Fase de la ejecución |
|---|---|
wp_pre_execute_ability | antes de la ejecución |
wp_ability_normalize_input | normalización de los datos de entrada |
wp_ability_permission_result | resultado de la comprobación de permisos |
wp_ability_execute_result | resultado de la ejecución |
Las acciones solo permitían observar la ejecución. Los filtros permiten intervenir en ella, por ejemplo normalizar la entrada o cambiar el resultado de la comprobación de permisos.
Abilities API y MCP Adapter
La Abilities API no incluye un servidor de Model Context Protocol. Ese papel lo cumple un paquete aparte:
“El paquete oficial de WordPress para la integración con MCP, que expone las abilities de WordPress como herramientas, recursos y prompts de Model Context Protocol (MCP) para agentes de IA.”
GitHub, WordPress/mcp-adapter, README, traducción propia
La configuración por defecto es conservadora:
“Las abilities de WordPress son privadas por defecto.”
GitHub, WordPress/mcp-adapter, README, traducción propia
Para que un cliente MCP vea una ability hay que poner meta.public (o meta.mcp.public) a true. El servidor por defecto del adaptador expone tres metaherramientas con las que el agente descubre y ejecuta abilities. La conexión:
“Conéctate mediante WP-CLI sobre STDIO, o apunta un cliente HTTP a
/wp-json/mcp/mcp-adapter-default-server.”GitHub, WordPress/mcp-adapter, README, traducción propia
STDIO mediante WP-CLI encaja con el trabajo en local y en staging, HTTP con un agente que funciona fuera del servidor. En ambos casos, lo que el agente puede hacer lo deciden los mismos permission_callback y anotaciones descritos más arriba.
Cómo conectar WordPress con agentes de IA mediante MCP lo explicamos con más detalle en la guía de integración de MCP e IA en WordPress. Si tu agencia o tu equipo interno necesita un servidor MCP propio o un conjunto de abilities diseñado para una tienda o un sitio concreto, lo describimos en la página de desarrollo de servidores MCP para WordPress.
Cómo saber si WordPress es compatible con la Abilities API
Lo más sencillo es hacerlo en código: function_exists( 'wp_register_ability' ) devuelve true desde la versión 6.9. Desde fuera, con una cuenta que tenga application password, basta con consultar el espacio de nombres wp-abilities/v1 en la API REST del sitio. Si no aparece, el sitio usa una versión anterior a 6.9 o algo está bloqueando la API REST. El listado solo devuelve las abilities con show_in_rest o public a true, así que un listado vacío no significa que los plugins no registren ninguna ability.
Última verificación de las fuentes: 6 de octubre de 2026.
