Você pede ao agente: “liste os rascunhos que ainda não têm resumo” ou “quais produtos estão com estoque abaixo de 5?”. Sem um contrato no site, ele inventa rota REST, campo e permissão. Com a Abilities API, o WordPress já sabe o nome da operação, o schema de entrada, quem pode executar e o formato da resposta.
Este texto entrega três peças práticas: a cadeia que valida a chamada, uma ability de leitura para copiar, e a mesma pergunta rodando em dois clientes (MCP Adapter por fora e AI Client por dentro). Serve a quem desenvolve plugin ou integra agente a um site WordPress 6.9+, e quer o contrato no código em vez de um endpoint improvisado.
A API entrou no core no WordPress 6.9. No 7.1, o flag meta.public unificou a exposição. Quem executa continua decidido no permission_callback. O mapa de canais (Connector, Abilities, MCP, SSH) está em Mapa de integrações de IA no WordPress.
O que você precisa
Para entender o artigo: WordPress 6.9 ou mais novo. Para repetir o exemplo com meta.public: 7.1 ou mais novo.
Para repetir o fluxo:
- Plugin ou mu-plugin seu. A categoria entra em
wp_abilities_api_categories_init. A ability entra emwp_abilities_api_init. - WP-CLI com
wp ability(nightly do WP-CLI, ou pacote à parte no estável) para listar, validar e executar no terminal. - MCP Adapter e uma Application Password, se o cliente for externo (Cursor, Claude Desktop, etc.).
- WooCommerce 10.9 ou mais novo (de preferência 11.3+) só para a pergunta de estoque. O Adapter não vem embutido no Woo: instale o plugin canônico.
- Um Connector em Configurações → Connectors só se o AI Client for chamar o modelo. Sem Connector, PHP, REST e WP-CLI já executam a ability.
O que o core já declara
Antes de registrar a sua, confira o que o WordPress já publica. São três abilities de leitura. Desde o 7.1 elas vêm com meta.public:
| Ability | O que devolve |
|---|---|
core/get-site-info | Nome, descrição, URL, e-mail do admin, idioma, versão do WordPress |
core/get-user-info | Usuário atual: ID, nome, login, papéis, locale |
core/get-environment-info | Tipo de ambiente, PHP, banco, versão do WordPress |
No terminal:
wp ability list
wp ability get core/get-site-info --fields=name,label,readonly,public,show_in_rest
wp ability run core/get-site-info --input='{"fields":["name","version"]}' --user=admin
public (e, no fluxo MCP, o espelho em meta.mcp.public) coloca a ability à disposição da REST e do Adapter. Autorização é outra camada: o permission_callback decide se este usuário executa. Input que não bate com o schema volta WP_Error antes do seu callback. O callback não vê dado malformado.
A descrição que você escreve é o texto que o modelo lê para decidir se chama essa ability. Caso de uso, não slogan. “Lista rascunhos sem resumo antes de publicar” funciona melhor que “ferramenta editorial inteligente”.
Uma ability de leitura para copiar
O exemplo lista posts em rascunho cujo resumo (post_excerpt) ainda está vazio. Só leitura. Quem não pode edit_posts não executa. A categoria precisa existir antes da ability.
add_action( 'wp_abilities_api_categories_init', 'editorial_register_ability_category' );
add_action( 'wp_abilities_api_init', 'editorial_register_rascunhos_sem_resumo' );
function editorial_register_rascunhos_sem_resumo() {
wp_register_ability(
'editorial/rascunhos-sem-resumo',
array(
'label' => __( 'Rascunhos sem resumo', 'editorial' ),
'description' => __( 'Lista posts em rascunho que ainda não têm resumo…', 'editorial' ),
'category' => 'editorial',
'input_schema' => /* limite 1–20 */,
'output_schema' => /* array de { id, titulo } */,
'execute_callback' => 'editorial_listar_rascunhos_sem_resumo',
'permission_callback' => /* current_user_can( 'edit_posts' ) */,
'meta' => array(
'public' => true,
'annotations' => array(
'readonly' => true,
'destructive' => false,
),
),
)
);
}
O esqueleto acima já mostra o contrato. O trecho completo (categoria, schemas e o execute_callback) fica abaixo, recolhido.
Ver código completo (PHP)
add_action( 'wp_abilities_api_categories_init', 'editorial_register_ability_category' );
function editorial_register_ability_category() {
wp_register_ability_category(
'editorial',
array(
'label' => __( 'Editorial', 'editorial' ),
'description' => __( 'Operações de conteúdo do site.', 'editorial' ),
)
);
}
add_action( 'wp_abilities_api_init', 'editorial_register_rascunhos_sem_resumo' );
function editorial_register_rascunhos_sem_resumo() {
wp_register_ability(
'editorial/rascunhos-sem-resumo',
array(
'label' => __( 'Rascunhos sem resumo', 'editorial' ),
'description' => __( 'Lista posts em rascunho que ainda não têm resumo. Use quando pedirem o que falta antes de publicar. Só leitura.', 'editorial' ),
'category' => 'editorial',
'input_schema' => array(
'type' => 'object',
'properties' => array(
'limite' => array(
'type' => 'integer',
'description' => 'Quantos rascunhos recentes consultar.',
'minimum' => 1,
'maximum' => 20,
),
),
'additionalProperties' => false,
),
'output_schema' => array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'titulo' => array( 'type' => 'string' ),
),
),
),
'execute_callback' => 'editorial_listar_rascunhos_sem_resumo',
'permission_callback' => static function ( $input = null ) {
return current_user_can( 'edit_posts' );
},
'meta' => array(
'public' => true,
'annotations' => array(
'readonly' => true,
'destructive' => false,
),
),
)
);
}
function editorial_listar_rascunhos_sem_resumo( $input = null ) {
$input = is_array( $input ) ? $input : array();
$limite = isset( $input['limite'] ) ? (int) $input['limite'] : 10;
$posts = get_posts(
array(
'post_type' => 'post',
'post_status' => 'draft',
'posts_per_page' => $limite,
'orderby' => 'modified',
'order' => 'DESC',
)
);
$itens = array();
foreach ( $posts as $post ) {
if ( '' !== trim( (string) $post->post_excerpt ) ) {
continue;
}
$itens[] = array(
'id' => (int) $post->ID,
'titulo' => get_the_title( $post ),
);
}
return $itens;
}
Depois de ativar o plugin (WP-CLI com o pacote/nightly que traz wp ability):
wp ability exists editorial/rascunhos-sem-resumo
wp ability validate editorial/rascunhos-sem-resumo --input='{"limite":10}'
wp ability run editorial/rascunhos-sem-resumo --input='{"limite":10}' --user=admin
No lab deste artigo (WordPress 7.1.2), a validação rodou via WP_Ability::execute(): rascunhos sem resumo entram, rascunho com resumo sai, limite fora do schema devolve ability_invalid_input.


O limite corta a consulta antes do filtro de resumo vazio. A lista devolvida pode ser mais curta que o número pedido. Em produção, filtre o excerpt na query. Aqui o objetivo é o contrato: schema de entrada, permissão, execute, schema de saída.
readonly avisa que a chamada não altera o site. destructive fica false de propósito: o padrão da anotação, quando você omite, trata a ability como capaz de apagar. Ability de escrita pede capability estreita e essa anotação consciente. Ensaio em site de teste, com OK humano, antes de mutação no ar.
A mesma pergunta em dois clientes
A ability já existe no registro. O cliente muda. O contrato não.
Cliente externo: MCP Adapter
Instale o MCP Adapter (em outubro/2026 ainda experimental no diretório; o caminho canônico). Crie uma Application Password para um usuário com a capability mínima. O endpoint padrão é:
https://seu-site.com/wp-json/mcp/mcp-adapter-default-server
O servidor MCP não lista uma tool por ability. Ele expõe três tools do Adapter: descobrir abilities, obter o schema de uma ability e executar. O fluxo concreto:
mcp-adapter-discover-abilities(ou o nome equivalente no cliente)mcp-adapter-get-ability-infocomeditorial/rascunhos-sem-resumomcp-adapter-execute-abilitycom{"limite":10}
No Cursor ou no Claude Desktop, a frase “liste os rascunhos sem resumo” só cai nessa ability se a descrição deixar o caso claro. Se o modelo escolher outra tool, o problema costuma ser a descrição, não o Adapter.
Para a loja, não reimplemente produto e pedido. Desde o WooCommerce 10.9 o plugin publica abilities canónicas (woocommerce/products-query, woocommerce/product-create, woocommerce/orders-query, entre outras). Na 11.3, elas passam a estar ligadas por padrão e o endpoint antigo /wp-json/woocommerce/mcp sai de cena: o transporte é o Adapter compartilhado + Application Password. Dados pessoais de cliente ficam de fora de propósito.
Em site de teste com Woo ≥ 10.9 e Adapter ativo:
wp ability get woocommerce/products-query
wp ability run woocommerce/products-query --input='{"page":1,"per_page":10}' --user=admin
A frase “quais produtos estão com estoque abaixo de 5?” é trabalho de woocommerce/products-query (filtre no schema da ability), não de um endpoint seu. O passo de um plugin real de expedição (etiqueta, SMS, concluir encomenda) está na palestra de Marco Almeida no WordPress Day for AI Faro: vídeo e slides. O registro é o mesmo. O transporte que ele usa é o Adapter.
Cliente interno: AI Client
Dentro do site, o AI Client (core 7.0+, com Connector em Configurações → Connectors) recebe a lista na hora do prompt:
wp_ai_client_prompt( 'Liste os rascunhos que ainda não têm resumo.' )
->using_abilities( 'editorial/rascunhos-sem-resumo' );
using_abilities() só declara funções que você nomeou. O WP_AI_Client_Ability_Function_Resolver executa ability dessa lista, não uma ability qualquer do registro. Sem Connector, o prompt com modelo não roda; a ability continua disponível em PHP, REST e WP-CLI. O loop que insiste sozinho até encerrar a tarefa ainda não é produto fechado no core.
| Canal | O que muda | O que fica |
|---|---|---|
| MCP Adapter | Transporte HTTP + Application Password | Nome, schema, permissão, execute |
| AI Client | Provedor do Connector + using_abilities() | O mesmo registro |
WP-CLI wp ability | Terminal local ou SSH | O mesmo registro |
Trocar o cliente não reescreve a ability. O WooCommerce fez isso ao aposentar a ponte MCP própria: as abilities canónicas ficaram; mudou o transporte por baixo.
WebMCP declara a ação na página, para o agente no navegador. O texto está em WordPress e WebMCP. A Abilities API declara a ação no servidor. São camadas diferentes. Confundir os dois nomes é o erro mais comum desta trilha.
Checklist rápido
- Registrar categoria e ability com schema, permissão e anotações.
- Validar com
wp ability validate/wp ability runno terminal. - Expor com
meta.public(e, se precisar de MCP, conferir a projeção no Adapter). - Cliente externo: Adapter + Application Password + descobrir → schema → executar.
- Cliente interno: Connector +
using_abilities()só com a lista consciente. - Mutação no ar: site de teste primeiro e OK humano.
Perguntas frequentes
O que é a Abilities API no WordPress?
É a API do core que registra operações do site (abilities) com nome, descrição, schema de entrada e saída, callback de execução e callback de permissão. Agentes e ferramentas descobrem o que o site sabe fazer sem adivinhar endpoints. Entrou no core no WordPress 6.9; o flag meta.public unificado é do 7.1.
Preciso do MCP Adapter para a ability existir?
Não. PHP, REST e WP-CLI leem o registro direto. O Adapter publica as abilities com projeção pública para um cliente MCP. Sem o plugin, a ability continua válida no site.
Como o WooCommerce usa a Abilities API?
Desde a 10.9, o WooCommerce registra abilities canónicas de produto e pedido. Na 11.3, elas ficam ligadas por padrão e o endpoint MCP antigo some: use o MCP Adapter e Application Password. Consulta de catálogo e estoque passa por woocommerce/products-query.
WebMCP e Abilities API são a mesma coisa?
Não. WebMCP anota a ferramenta na página, para o agente no navegador. A Abilities API registra a operação no site, com permissão de usuário WordPress. Um resolve a ação no browser; o outro, no servidor.
O agente pode executar qualquer ability registrada?
No AI Client, só o que entrou em using_abilities(). No MCP, só ability projetada como pública cujo permission_callback autoriza aquele usuário. O flag public abre o canal. A permissão decide a execução.
Qual a diferença entre Abilities API e REST API?
A REST continua existindo. A Abilities API padroniza a unidade de capacidade (schema, permissão, descoberta) para vários consumidores: PHP, REST, WP-CLI, MCP e AI Client. Você registra uma vez; o transporte muda.
