Registrar uma Ability no WordPress resolve uma parte do problema: define uma unidade de funcionalidade com nome, descrição, schemas de entrada e saída, callback de execução e verificação de permissão. Isso não a transforma automaticamente em uma ferramenta WebMCP que um agente de navegador consiga descobrir na página externa do WordPress Playground. São dois registros e duas rotas de exposição diferentes.
No Playground, essa diferença fica mais visível porque o WordPress roda dentro de uma cadeia de iframes. O agente observa a página superior, enquanto a ferramenta de um plugin é registrada no documento WordPress interno. O proxy WebMCP incorporado ao Playground existe justamente para transportar a descrição da tool para fora do iframe e devolver a chamada para dentro quando o agente decide executá-la. A implementação foi incorporada ao projeto em 3 de setembro de 2026, e a equipe do Playground publicou a explicação do fluxo em 5 de setembro.
Ability, tool e proxy são três peças diferentes
| Peça | Onde vive | O que descreve | Como chega ao agente |
|---|---|---|---|
| WordPress Ability | Registro da Abilities API no WordPress | Uma capacidade reutilizável com schema, execução e permissão | Via PHP interno ou, quando exposta, pela Abilities REST API e outros adaptadores |
| Tool WebMCP | document.modelContext do documento web | Uma ação que o navegador pode apresentar a agentes, com nome, descrição, input schema e função de execução | Por descoberta WebMCP no contexto da página |
| Proxy do Playground | Página externa, cliente do Playground e ponte entre frames | Espelha tools registradas dentro do WordPress e encaminha chamadas | Re-registra as tools na página que o agente consegue observar |
A consequência prática é simples: uma Ability pode ser a implementação de negócio por trás de uma tool, mas não é a própria tool. O artigo oficial do Playground é explícito ao afirmar que registrar a Ability, sozinho, não faz com que ela apareça automaticamente pelo proxy WebMCP.
O caminho request → proxy → iframe → plugin
- O plugin registra uma tool WebMCP dentro do WordPress. O documento interno passa a ter um descritor de ferramenta com nome, descrição e schema de entrada, além da função que será executada.
- A ponte do iframe detecta a lista de tools. A implementação do Playground acompanha registros, remoções e navegações do documento WordPress.
- O proxy reanuncia essas tools na página externa. É essa página superior que o agente de navegador consegue inspecionar para descobrir as ferramentas disponíveis.
- O agente envia os argumentos da tool. A chamada passa pelo cliente do Playground e pela ponte entre frames.
- A execução acontece no documento WordPress. O plugin roda a lógica local e o resultado percorre o caminho inverso até o agente.
O fluxo descrito no pull request do proxy é, conceitualmente: agente → contexto WebMCP da página do Playground → cliente do Playground → frame remoto → documento WordPress → execução do plugin. Isso explica por que o proxy não é apenas um detalhe de rede: ele resolve uma fronteira de descoberta e de ciclo de vida entre documentos.
Exemplo conceitual: a mesma ação em duas camadas
Imagine um plugin de eventos que precisa criar um rascunho. Na Abilities API, ele pode registrar algo como meu-plugin/criar-evento, definir um input com título e data, validar o retorno e usar um permission_callback para exigir que o usuário tenha permissão de editar conteúdo.
Se a intenção for que um agente no navegador veja uma ação chamada “Criar rascunho de evento” entre as Site tools do Playground, o plugin ainda precisa de uma tool WebMCP. Essa tool pode ser fina: recebe os mesmos argumentos, chama a Ability e devolve o resultado. O ganho desse desenho é manter regra de negócio, validação e permissão centralizadas na Ability, enquanto a camada WebMCP fica responsável pela descoberta e pelo contrato voltado ao agente.
Em outras palavras, a Ability responde “o que o WordPress sabe fazer e com quais regras”; a tool responde “como essa ação é oferecida ao agente neste documento web”.
O sinal public não elimina a necessidade da tool WebMCP
No WordPress 7.1, a documentação da Abilities API usa o metadado de alto nível public para indicar que uma Ability foi pensada para clientes externos, como REST, MCP ou agentes de IA. Esse sinal alimenta padrões por canal; para REST, por exemplo, influencia show_in_rest. Ainda assim, ele não cria por si só um registro em document.modelContext dentro do Playground.
Para consumo por HTTP, a rota é outra. Abilities expostas pela REST API aparecem sob /wp-json/wp-abilities/v1/ e podem ser descobertas e executadas por endpoints próprios. A documentação oficial também deixa claro que esses endpoints exigem usuário autenticado e que a execução continua sujeita ao permission_callback da Ability.
No Playground, um agente pode usar a tool já existente playground_request para fazer requisições ao WordPress e, por esse caminho, consultar ou executar uma Ability que esteja exposta pela REST API. Isso é diferente de a Ability aparecer diretamente como uma tool WebMCP nomeada e descoberta pelo agente.
Quando usar uma tool WebMCP e quando usar a Abilities REST API
| Necessidade | Caminho mais direto | Motivo |
|---|---|---|
| A ação deve aparecer como ferramenta explícita ao agente que está trabalhando no Playground | Tool WebMCP, possivelmente embrulhando uma Ability | Entrega descoberta nativa no contexto da página e uma interface específica para o agente |
| A mesma capacidade precisa atender integrações HTTP, automações ou clientes fora do navegador | Ability exposta pela REST API | Fornece endpoint estável, autenticação e execução independente de uma sessão WebMCP |
| Você já tem uma Ability bem definida e quer expô-la também como Site tool | Wrapper WebMCP fino sobre a Ability | Evita duplicar regra de negócio e separa transporte de implementação |
| O agente só precisa de acesso genérico a uma Ability exposta | playground_request + Abilities REST API | Dispensa criar uma tool dedicada quando uma requisição genérica é suficiente |
Esse último caminho é especialmente útil para experimentação ou para capacidades administrativas que já foram projetadas como API. Uma tool dedicada passa a valer mais quando nome, descrição e schema precisam orientar claramente a escolha do agente ou quando a ação deve compor a experiência de Site tools do navegador.
Limites atuais que afetam o desenho
- WebMCP ainda é uma especificação em incubação. O relatório da Web Machine Learning Community Group publicado em 15 de setembro de 2026 continua dizendo que WebMCP não é um padrão W3C nem está na Standards Track. Implementações e nomes de API ainda podem evoluir.
- É preciso suporte no navegador ou no ambiente do agente. O proxy consegue atravessar o iframe, mas a descoberta final ainda depende de uma implementação de WebMCP que o agente possa usar.
- Tools pertencem ao documento que as registrou. No proxy do Playground, uma navegação começa com uma lista nova; o sistema acompanha registros tardios e remove tools que deixaram de existir.
- Nem toda rota WordPress produz um documento com tools. O pull request cita respostas como REST, arquivos estáticos e admin-ajax.php como exemplos que não anunciam tools. A tela de login também não é coberta pelo fluxo padrão atual.
- Nomes reservados importam. Uma tool de plugin que colidir com uma tool interna playground_* é ignorada pelo proxy para evitar substituir uma ação do próprio Playground.
- Exposição não substitui autorização. A Ability deve continuar protegendo sua execução com regras de permissão adequadas. Tornar algo público para descoberta não deve ser tratado como autorização para qualquer operação.
Checklist para um plugin que quer conversar com agentes
- Modele a ação principal como Ability quando ela fizer sentido como capacidade reutilizável do WordPress.
- Defina schemas de entrada e saída e mantenha a verificação de permissão na camada de negócio.
- Decida se a capacidade precisa de REST; se precisar, configure a exposição de acordo com a versão do WordPress e o canal desejado.
- Se a ação deve aparecer diretamente ao agente no Playground, registre uma tool WebMCP que faça o mapeamento para a Ability ou para a lógica equivalente.
- Teste navegação, wp-admin e páginas públicas separadamente, porque o ciclo de vida das tools acompanha o documento ativo.
- Trate o proxy como parte da arquitetura de descoberta: ele anuncia para fora, encaminha para dentro e retira tools quando o contexto muda.
