O servidor MCP da MemberPress AI Foundation disponibiliza um catálogo de ferramentas que um cliente de IA utiliza para ler e gerenciar dados da MemberPress. Cada ferramenta declara um nome, um esquema de entrada JSON e anotações que a classificam como somente leitura, gravação ou destrutiva.
Esta referência lista todas as ferramentas, agrupadas por domínio, com sua finalidade, parâmetros principais, escopo necessário e capacidade exigida do WordPress. Ela é o complemento do Referência sobre medidas de segurança para agentes, que explica como os escopos, as capacidades e o fluxo de confirmação são aplicados.
Como funciona a lista de ferramentas
Um cliente recupera o catálogo chamando a função ferramentas/lista método no endpoint MCP. Dois fatores determinam quais ferramentas aparecem na resposta:
- Nível de acesso à conexão (filtragem de escopo). O servidor retorna apenas as ferramentas permitidas pelo escopo da conexão. Uma conexão somente leitura (incluindo qualquer conexão com senha de aplicativo) tem acesso apenas às ferramentas de leitura. Uma conexão com escopos de gravação tem acesso adicional às ferramentas de gravação e destrutivas abrangidas por seus escopos. Uma ferramenta também fica oculta quando o proprietário do token não possui a capacidade necessária do WordPress —
memberpress_delete_membernão aparece para um usuário que não tenhaexcluir_usuários. - Complementos ativos (restrição de acesso a complementos). As ferramentas pertencentes a um complemento são registradas apenas enquanto esse complemento estiver ativo. Um site sem o MemberPress Courses, por exemplo, não exibe as ferramentas do curso.
Devido a esses dois fatores, o número de ferramentas que um site disponibiliza varia. O catálogo é formado por complementos:
| Registro | Ferramentas autenticadas | Ferramentas públicas |
|---|---|---|
| Versão básica (sem complementos) | 41 | 2 |
| + Cursos MemberPress | +8 | +2 |
| + Contas corporativas | +3 | — |
| + Downloads | +2 | — |
| Tudo ativo | 54 (39 leituras, 9 gravações não destrutivas, 6 destrutivas) | 4 |
Classificações de ferramentas
Cada ferramenta possui anotações que a classificam:
| Classificação | Anotação | Comportamento |
|---|---|---|
| Ler | readOnlyHint: true | Recupera dados. Nunca altera o estado. Disponível para todas as conexões. |
| Gravação não destrutiva | readOnlyHint: false, destructiveHint: false | Cria ou atualiza. Por padrão, exibe uma pré-visualização; passe executar: true para ser transmitido ao vivo. |
| Destrutivo | readOnlyHint: false, destructiveHint: true | Exclui, reembolsa, cancela ou reinicia. Requer o fluxo de confirmação em duas etapas com token. |
As mecânicas de gravação e execução destrutiva estão documentadas no Referência sobre medidas de segurança para agentes. Esta referência aborda o que é cada ferramenta e quais dados ela aceita.
Formato de resposta da ferramenta
Um cliente executa uma ferramenta com o ferramentas/chamada método. O resultado é retornado no formato padrão do MCP: um result.content matriz cujo primeiro elemento é um bloco de texto. Esse bloco texto O campo contém os dados da ferramenta como um String JSON o cliente deve analisar. Isso difere do ferramentas/lista forma, que retorna diretamente as definições das ferramentas.
O envelope de um lista_de_membros_do_memberpress chamada:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "{ ...string JSON com caracteres de escape... }" }
]
}
}
Analisando o texto A string retorna a carga útil — uma membros matriz com campos de paginação em linha:
{
"membros": [
{
"id": 50,
"e-mail": "member@example.com",
"nome de usuário": "member50",
"primeiro_nome": "Exemplo",
"sobrenome": "Membro",
"data_de_registro": "21/08/2023 17:18:31",
"active_memberships": [ { "id": 2332, "title": "Associação Básica" } ]
}
],
"total": 8,
"página": 1,
"por_página": 3,
"páginas": 3
}
Campos de paginação (total, página, por_página, páginas) ficam ao lado da matriz de dados, e não dentro de um objeto envolvent.
Ferramentas de leitura
As ferramentas de leitura recuperam dados e nunca alteram o estado. Elas estão disponíveis em todas as conexões, inclusive nas conexões com senha de aplicativo somente para leitura. Todas as ferramentas de leitura possuem readOnlyHint: true, destructiveHint: false, idempotentHint: true, e exigem apenas o ler âmbito (sempre concedido).
Parâmetros exibidos como necessário deve ser fornecido. As ferramentas de lista compartilham um padrão comum de paginação: página (padrão: 1) e por_página (padrão 20, máximo 100).
Membros
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_member | Detalhes completos sobre um membro, incluindo assinaturas ativas e planos de assinatura disponíveis. | identificador (ID de membro ou e-mail); incluir_transações (bool, padrão: false) |
lista_de_membros_do_memberpress | Listar membros com filtragem. Paginado. | pesquisa, status (ativo/inativo/todos), membership_id, página, por_página |
memberpress_export_members | Exportar membros como um array JSON paginado. | membership_id, status, date_from, date_to, página, por_página (padrão: 50) |
Associações
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_membership | Detalhes completos sobre uma assinatura/produto: preços, período de teste, grupo, regras de acesso, número de membros. | membership_id |
lista_de_associações_da_memberpress | Listar assinaturas/produtos com filtro de status. Paginado. | status (publicar/rascunho/todos), página, por_página |
memberpress_get_membership_stats | Estatísticas gerais sobre todas as assinaturas: assinantes ativos, receita total, receita média por assinante. | (nenhum) |
Assinaturas
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_subscription | Detalhes completos da assinatura: usuário, produto, status do período de teste, histórico de transações. | subscription_id |
lista_de_assinaturas_do_memberpress | Lista de assinaturas com filtragem. Paginada. | member_id, membership_id, status (pendente/ativo/suspenso/cancelado/todos), date_from, date_to, página, por_página |
Transações
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_transaction | Detalhes completos da transação: usuário, produto, assinatura, dados financeiros. | transaction_id |
lista_de_transações_dos_membros_da_imprensa | Listar transações com filtragem. Paginado. | member_id, membership_id, subscription_id, status (pendente/concluído/reprovado/reembolsado/todos), date_from, date_to, página, por_página |
Regras e acesso
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
regras_da_lista_de_membros_da_imprensa | Lista de regras de acesso com filtragem. Paginada. | membership_id, tipo_de_regra, página, por_página |
memberpress_get_protected_content | Todas as regras relativas a conteúdo protegido e se um membro tem acesso a cada uma delas. | member_id |
memberpress_list_protected_urls | Lista de regras de proteção de conteúdo com os conteúdos protegidos e as assinaturas exigidas. Paginada. | página, por_página |
memberpress_check_access | Se um usuário tem acesso a uma postagem/página específica. | user_id, post_id |
Cupons
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
lista_de_cupons_para_membros | Lista de cupons com filtro de status, detalhes do desconto e estatísticas de uso. Paginada. | status (ativas/expiradas/todas), página, por_página |
Relatórios e análises
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_revenue_report | Receita para um intervalo de datas, detalhada por período. | date_from, date_to, período (diário/semanal/mensal/anual), membership_id |
memberpress_get_churn_report | Assinaturas canceladas/suspensas/novas e taxa de cancelamento para um intervalo de datas. | date_from, date_to, membership_id |
análise_de_receitas_do_memberpress | Totais de transações, receita por produto, tendências mensais. | date_from, date_to, IDs de membros (matriz) |
memberpress_previsão_de_rotatividade | Número de assinaturas ativas, taxas de cancelamento, tempo médio até o cancelamento, rotatividade por produto. | membership_id |
análise_de_coorte_do_memberpress | Inscrições agrupadas por mês, com taxas de retenção, cancelamentos e receita por coorte. | date_from, date_to |
memberpress_ltv_análise | Receita por assinatura e duração agrupadas por produto, para estimativa do LTV. | membership_id |
memberpress_engajamento_dos_membros | Frequência das transações, distribuição do status das assinaturas, padrões de atividade. | membership_id, dias (máximo 365, padrão 90) |
previsão_de_renovação_do_memberpress | Vencimentos futuros em intervalos de 30 dias, com taxas históricas de renovação. | membership_id |
análise_de_pagamentos_não_concluídos_do_memberpress | Transações com falha e reembolsadas por produto, mês e gateway, em comparação com o volume de transações bem-sucedidas. | date_from, date_to |
memberpress_content_performance | Número de conteúdos protegidos, proporção entre membros e conteúdos, taxa de cancelamento por assinatura. | date_from, date_to |
memberpress_smart_query | Dados de contexto do site para responder a uma pergunta em linguagem natural sobre dados de filiação. | pergunta |
Quando date_from / date_to se forem omitidas, as ferramentas de análise utilizam um intervalo de datas padrão, em vez de exigir datas explícitas.
Sistema
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_system_info | Diagnósticos: versões do PHP/WordPress/MemberPress, complementos ativos, nomes dos gateways de pagamento, status das tabelas do banco de dados, contagens. | (nenhum) |
memberpress_list_webhooks | Listar os webhooks configurados com URLs, eventos e status de ativação. | (nenhum) |
lista_de_lembretes_para_membros | Listar os lembretes por e-mail configurados, com eventos desencadeadores, intervalos de tempo, status e associações. | (nenhum) |
Cursos (exige cursos com 1 aula teórica e 6 aulas práticas)
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_course | Detalhes do curso: seções, aulas, inscrições, taxa de conclusão. | course_id |
lista_de_cursos_para_membros | Listar cursos com filtragem. Paginado. | pesquisa, status (publicar/rascunho/todos), página, por_página |
memberpress_get_lesson | Detalhes da aula: seção, curso principal, disponibilidade. | ID da lição |
lista_de_aulas_para_membros | Listar aulas filtradas por curso ou turma. Com paginação. | course_id, section_id, página, por_página |
memberpress_get_student_progress | O progresso de um aluno por aula em um curso. | user_id, course_id |
lista_de_alunos_do_curso_memberpress | Alunos matriculados em um curso com status de conclusão. Paginado. | course_id, página, por_página |
Contas corporativas (requer o módulo MemberPress Contas corporativas)
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
memberpress_get_corporate_account | Conta corporativa por ID de usuário do titular: uso e lista de subcontas. | user_id |
lista_de_subcontas_de_membros | Subcontas de uma conta corporativa. Paginado. | id_da_conta_corporativa, página, por_página |
Downloads (requer o MemberPress Downloads)
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
lista_de_downloads_dos_membros | Lista de arquivos disponíveis para download com filtros: título, nome do arquivo, número de downloads, assinaturas. Paginada. | membership_id, página, por_página |
memberpress_get_download_stats | Estatísticas de um download: contagem, informações do arquivo, assinaturas, tamanho do arquivo. | id_do_arquivo |
Ferramentas de gravação (não destrutivas)
As ferramentas de gravação não destrutivas criam ou atualizam dados. Cada uma delas usa, por padrão, um visualização: ao chamá-la, ela retorna o que *aconteceria* sem alterar nada. Para executar em tempo real, passe executar: true. Cada uma delas requer um escopo de gravação específico e uma capacidade do WordPress. A verificação de escopo é executada primeiro e rejeita com SCOPE_INSUFICIENTE; o mecanismo de verificação de capacidade, então, rejeita com CAPACIDADE_INSUFICIENTE.
Essas ferramentas não estão disponíveis em conexões somente leitura (incluindo conexões com senha de aplicativo). É necessário atribuir à conexão o escopo de gravação relevante por meio do assistente, com o nível máximo de acesso total.
Alguns parâmetros estão documentados no inventário abaixo; os esquemas completos de entrada para cada ferramenta de gravação ainda exigem uma captura em tempo real com acesso total ou uma visualização específica para cada ferramenta (a conexão de captura somente para leitura não conseguiu enumerar os esquemas das ferramentas de gravação).
| Ferramenta | Objetivo | Escopo | Capacidade |
|---|---|---|---|
memberpress_create_member | Crie um membro. | escrever:membros | create_users |
memberpress_update_member | Atualizar um membro. Apenas os campos enviados pelo chamador são alterados; os campos omitidos permanecem inalterados. | escrever:membros | editar_usuários |
memberpress_create_coupon | Crie um cupom. | escrever:conteúdo | gerenciar_opções |
memberpress_create_subscription | Inscrever um associado já cadastrado em um plano de associação. | escrever:membros | editar_usuários |
memberpress_create_rule | Crie uma regra de acesso. | escrever:conteúdo | gerenciar_opções |
memberpress_create_webhook | Crie um webhook. | escrever:webhooks | gerenciar_opções |
memberpress_import_members | Importar membros em massa. | escrever:importações | create_users |
memberpress_lição_concluída | Marcar uma aula como concluída para um aluno. | escrever:cursos | editar_usuários |
memberpress_toggle_reminder | Ativar/desativar um lembrete por e-mail. | escrever:webhooks | gerenciar_opções |
Ferramentas destrutivas
As ferramentas destrutivas excluem, reembolsam, cancelam ou reinicializam dados. Elas envolvem destructiveHint: true e não pode ser executado com um único parâmetro. Cada um deles requer o fluxo de token de confirmação em duas etapas: a primeira chamada retorna uma pré-visualização e um código de uso único token_de_confirmação; uma segunda chamada que passa confirmar: "" com argumentos idênticos, executa a operação em tempo real. Os tokens expiram após 60 segundos, são de uso único e estão vinculados à ferramenta, aos argumentos e ao usuário específicos.
As ações reversíveis estão isentas da etapa de confirmação. Dois valores de ação que revertem, em vez de destruir, e são executados sem um token: memberpress_gerenciar_assinatura com ação: "retomar"e memberpress_gerenciar_subconta com ação: "adicionar". Qualquer outra ação nessas ferramentas — e qualquer chamada às outras quatro ferramentas destrutivas — requer o fluxo de tokens.
As ferramentas destrutivas também estão sujeitas ao kill switch: quando as gravações destrutivas são pausadas, todas as ferramentas destrutivas são rejeitadas com WRITES_PAUSED, independentemente do escopo ou de um token válido. Consulte o Referência sobre medidas de segurança para agentes.
Os parâmetros documentados constam na próxima seção; os esquemas completos de entrada ainda exigem uma captura em tempo real com acesso total ou uma visualização por ferramenta.
| Ferramenta | Objetivo | Escopo | Capacidade |
|---|---|---|---|
memberpress_delete_member | Excluir um membro (chamadas wp_delete_user; MemberPress realiza limpeza em cascata de linhas, transações, assinaturas e eventos). Recusa-se a excluir o usuário que fez a chamada ou qualquer usuário com o gerenciar_opções capacidade (administradores, superadministradores e qualquer função personalizada à qual essa capacidade tenha sido concedida). Ambas as verificações são executadas antes da execução e antes do ramo de pré-visualização; portanto, até mesmo uma pré-visualização é recusada. | escrever:membros | excluir_usuários — declarado como um portão explícito no nível da ferramenta; a ferramenta fica oculta de ferramentas/lista para usuários que não o possuem |
memberpress_delete_webhook | Excluir um webhook. | escrever:webhooks | gerenciar_opções |
memberpress_gerenciar_assinatura | Cancelar/suspender/retomar uma assinatura. | escrever:faturamento | gerenciar_opções |
transação de reembolso do MemberPress | Reembolsar uma transação. | escrever:faturamento | gerenciar_opções |
memberpress_gerenciar_subconta | Gerenciar uma subconta corporativa. | escrever:membros | gerenciar_opções |
memberpress_reset_course_progress | Redefinir o andamento do aluno no curso. | escrever:cursos | editar_usuários |
Parâmetros e comportamento documentados
Os detalhes a seguir sobre parâmetros e comportamentos foram extraídos do inventário do código-fonte e de confirmações da equipe de engenharia. Eles não constituem um esquema completo para todas as ferramentas; os parâmetros restantes são confirmados por meio da visualização prévia de cada ferramenta.
memberpress_create_coupon—tipo de desconto∈{porcentagem, dólar},discount_mode∈{padrão, primeiro pagamento}(padrãopadrão), além dediscount_amounte um opcionalIDs de membrosmatriz (restringe o cupom a produtos específicos). Valores legados (plano,primeiro,todos) são rejeitados categoricamente. Aceitaexecutar.memberpress_create_subscription— inscreve um membro *existente* em uma assinatura (é necessário ter membro + produto); recusa inscrições duplicadas; sempre usagateway='manual'(acesso concedido pela administração, não se trata de um evento de cobrança); filiais que comercializam produtos de uso único versus produtos recorrentes. Ofereceexecutar.memberpress_import_members— aceita um nível superiorenviar_e-mail_de_boas-vindasbooleano (padrãofalso); o e-mail de boas-vindas do WordPress é enviado uma vez para cada membro recém-criado após o provisionamento. Os usuários existentes cujos endereços de e-mail coincidirem não são recriados. Contémexecutar.memberpress_delete_member—member_id; chamadaswp_delete_user, permitindo que o MemberPressusuário_excluídogancho para limpar em cascata as linhas relacionadas. Apenas no fluxo de token de confirmação.memberpress_gerenciar_assinatura— um seletor de ações que abrange cancelar/suspender/retomar;currículoé uma variante não destrutiva que ignora a porta destrutiva. Fluxo de tokens de confirmação para ações destrutivas.memberpress_gerenciar_subconta— um seletor de ação;adicionaré uma variante não destrutiva que ignora a porta destrutiva.transação de reembolso do MemberPress—transaction_idobrigatório; opcionalcancelar_assinaturabooleano. Efeito colateral da resposta: quando a transação tiver uma assinatura associada Ecancelar_assinatura*não* foi aprovado, a resposta (pré-visualização e ao vivo) acrescentaa_lista_de_assinaturas_pode_exibir_contas_inativas: truee umnota_sobre_a_lista_de_assinaturas. Essa marcação e essa nota referem-se a apenas como a lista de assinaturas do painel de administração do WP exibe o status — essa coluna é derivada do status da transação mais recente, e não do registro da assinatura — e são ignoradas quandocancel_subscription: true. O sinalizador não descreve o comportamento de acesso: o reembolso da última transação associada a uma assinatura encerra o acesso do membro para aquele período. Esse formato de resposta deve constar em qualquer exemplo de reembolso. Apenas no fluxo de token de confirmação.
Ferramentas públicas
O endpoint público não autenticado (/wp-json/mp-mcp/v1/public-mcp) apresenta um conjunto separado e cuidadosamente selecionado de 4 ferramentas somente para leitura para uso sem um token. Elas retornam apenas dados públicos do catálogo — preços e links de inscrição — e nunca dados de membros, transações ou de administração. Todas as quatro são memberpress_-prefixado e transportado readOnlyHint: true.
Esses quatro nomes também existem na superfície de leitura autenticada, mas as versões públicas são distintas: esquemas mais simples, descrições específicas para o público e resultados limitados aos itens incluídos no catálogo público.
| Ferramenta | Objetivo | Parâmetros principais |
|---|---|---|
lista_de_associações_da_memberpress | Liste os planos de assinatura disponíveis ao público, incluindo preços e links para inscrição. | (nenhum) |
memberpress_get_membership | Detalhes sobre um plano de assinatura público: preços, informações sobre o período de teste e URL para inscrição. | membership_id |
lista_de_cursos_para_membros | Listar os cursos disponíveis ao público. | (nenhum) |
memberpress_get_course | Detalhes de um curso aberto ao público: visão geral e número de aulas. | course_id |
O catálogo público é configurado em dois níveis: um administrador o habilita globalmente (Configurações do MCP → “Habilitar endpoint do catálogo público de IA”, padrão desligado), e cada assinatura ou curso pode ser excluído individualmente desmarcando a caixa de seleção “Exibir no catálogo público de IA” na tela de edição. A obter_associação/get_course A consulta a um item que não consta no catálogo público não retorna nenhum dado.
Controle de portas de complemento
As ferramentas de complementos são registradas apenas enquanto o respectivo complemento estiver ativo, o que é detectado por uma sonda que verifica a classe principal do complemento:
| Complemento | Classe de detecção | Ferramentas |
|---|---|---|
| Cursos | memberpress\courses\models\Course | ferramentas do curso/aula |
| Contas corporativas | MPCA_Conta_Corporativa | ferramentas corporativas |
| Downloads | memberpress\downloads\models\Arquivo | ferramentas para download |
Um site que não possui um complemento simplesmente não expõe suas ferramentas — chamar uma ferramenta não registrada retorna o erro padrão de método desconhecido do JSON-RPC.
Referência do escopo
O assistente emite conexões com um ou mais escopos. O acesso de leitura é sempre concedido; os escopos de gravação são concedidos apenas com o limite máximo de “Acesso Total”.
Mapa das caixas de seleção da etapa “Acesso” do assistente individual para esses escopos — o valor de cada caixa de seleção é a string interna do escopo, armazenada literalmente no token:
| Balde do Mago | Escopo publicado |
|---|---|
| Leia tudo | ler (sempre concedido) |
| Editar conteúdo | escrever:conteúdo |
| Gerenciar membros | escrever:membros |
| Operações de faturamento | escrever:faturamento |
| Importações em grande volume | escrever:importações |
| Gerenciar webhooks | escrever:webhooks |
| Progresso no curso | escrever:cursos |
Não há um escopo específico para cupons, lembretes ou operações corporativas — os cupons fazem parte de escrever:conteúdo, lembretes por e-mail em escrever:webhooks, e subcontas corporativas em escrever:membros.
| Escopo | Subsídios |
|---|---|
ler | Todas as ferramentas de leitura. Sempre concedidas. |
escrever:membros | Ferramentas para criar/atualizar/excluir membros. |
escrever:faturamento | Ferramentas de gerenciamento de assinaturas e reembolso de transações. |
escrever:conteúdo | Ferramentas de regras de acesso e cupons. |
escrever:webhooks | Ferramentas de criação/exclusão de webhooks e lembretes por e-mail. |
escrever:importações | Ferramenta de importação de membros. |
escrever:cursos | Ferramentas de acompanhamento do andamento do curso. São exibidas no assistente somente quando a opção “Cursos” estiver ativa. |
completo | Metascópio legado. Satisfaz qualquer escreva:* solicitação. Mantida por motivos de compatibilidade com versões anteriores. |
Referência de Recursos
Além do escopo, cada ferramenta de gravação verifica se o proprietário do token possui a capacidade correspondente no WordPress. Um token com o escopo correto, mas cujo proprietário não possua a capacidade, é rejeitado com CAPACIDADE_INSUFICIENTE.
| Capacidade | Ferramentas |
|---|---|
create_users | create_member, import_members |
editar_usuários | atualizar_membro, criar_assinatura, lição_completa, reiniciar_o_progresso_do_curso |
excluir_usuários | excluir_membro — porta explícita no nível da ferramenta; oculta de ferramentas/lista sem isso |
gerenciar_opções | gerenciar_assinatura, transação_de_reembolso, create_rule, criar_cupom, create_webhook, excluir_webhook, alternar_lembrete, gerenciar_subconta |
Documentação relacionada
- Visão geral e guia de configuração do MemberPress AI Foundation — o que o AI Foundation oferece e como instalá-lo;
- Conectando clientes de IA ao MemberPress – Referência para desenvolvedores — autenticação e configuração por cliente;
- Medidas de segurança para agentes da MemberPress AI Foundation — escopos, o limite de acesso, tokens de confirmação e o botão de desativação;
- Erros e solução de problemas do MCP MemberPress — códigos de erro, incluindo
CAPACIDADE_INSUFICIENTEeWRITES_PAUSED.