Hotmart API MCP server — sales, subscriptions, club, products, coupons, tickets, and negotiation, auto-generated from the official OpenAPI spec
The Hotmart MCP server provides 40 tools with generally complete schemas and descriptions, but exhibits significant inconsistencies in description quality, parameter documentation depth, and output schema specification. Tool naming follows a consistent verb_noun pattern (hotmart_<action>_<resource>). Most tools include input parameter schemas with type declarations. However, descriptions range from detailed to minimal (some under 50 chars), parameter descriptions lack consistency, output schemas are not documented in the visible source, and error handling guidance is absent. No tool annotations (readOnlyHint, destructiveHint) are evident despite proper risk classification in metadata. The server mixes REST-style list operations with app-based visualizations (15 of 40 tools are *_app variants returning Prefab UI), which is valid but underdocumented regarding when to use tools vs. apps. Definition quality averages around 58, typical of a functional but not production-optimized toolkit.
Cancel multiple subscriptions in a single batch request.
Reactivate multiple cancelled subscriptions in a batch request.
Análise de churn — cancelamentos por período + tendência. LineChart cancelamentos no tempo + DataTable de recentes. Use pra 'análise de churn', 'cancelamentos da semana', 'taxa de cancelamento'.
Painel de comissões — total a pagar/receber por afiliado. DataTable com afiliado/papel/valor + Metric de total. Use pra 'comissões do mês', 'quanto pagar pros afiliados', 'settlement'.
Create a new coupon/discount code for a product.
Delete a coupon by its ID.
Output schemas not documented in source. No visible response shape specifications for any of the 40 tools, LLMs cannot infer what fields to extract or how to chain tools. Documentation exists only in implicit API responses, violating pattern:tool requirement for structured output specification.
Tool annotations missing. Risk classification exists in metadata (READ_ONLY, DESTRUCTIVE, REVERSIBLE, WRITE) but not exposed as MCP toolAnnotations (readOnlyHint, destructiveHint, idempotentHint). Prevents MCP clients from determining safe retry logic and exposing appropriate guardrails.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Painel de cupons de um produto — listagem com validade/desconto/usos. DataTable de cupons + Metric. Use pra 'listar cupons do produto X', 'ver cupons ativos', 'gerenciar cupons'. Pra CRIAR cupom use a tool `hotmart_coupon_create` direta.
List all coupons for a product.
Painel de evento — info + lista de participantes + breakdown lotes. Card com info + DataTable participantes + PieChart por lote. Funciona apenas pra produtos formato ETICKET (não ONLINE_EVENT). Use pra 'ver dados do evento X', 'quem comprou ingresso pro evento'.
Get detailed information about an event (dates, lots, tickets, pricing).
List all participants/ticket buyers for an event.
Análise por módulo da área de membros — qty aulas por módulo. BarChart aulas/módulo + DataTable. Use pra 'estrutura da área de membros', 'quantas aulas por módulo'.
List all pages/lessons within a specific module in a club.
List all modules in a club (members area) by subdomain.
Generate a payment negotiation (installment plan) for a subscriber in arrears.
Preview de proposta de negociação antes de gerar. Mostra os parâmetros e dispara o `hotmart_negotiation_generate` se confirmado. Use pra 'simular negociação pro assinante X', 'preview parcelamento'. NÃO gera por padrão — só prévia visual.
Catálogo de produtos — visão geral com formato/status/preço/info. Cards de metrics + PieChart status + DataTable. Use pra 'lista de produtos', 'catálogo', 'meus produtos ativos'.
List all offers (pricing variants, payment conditions) for a product.
List all subscription plans available for a product.
List all products in your Hotmart account.
Issue a refund for a specific sale by transaction code.
Breakdown de vendas — top produtos + top compradores. BarChart de produtos por receita + DataTable de compradores únicos. Use pra 'quais produtos vendem mais', 'top compradores', 'analise de quem está comprando'.
List all commission entries (what you earned as an affiliate or producer).
Painel visual de vendas Hotmart no período. Cards de métricas (receita total, ticket médio, qtd) + LineChart vendas/dia + PieChart por payment_type + DataTable. Use quando o usuário pedir 'dashboard de vendas', 'painel de vendas', 'visão geral das vendas do mês'.
List all sales transactions with full details (buyer, product, value, status, payment method).
List all buyers (participants) who made purchases, with name, email, and purchase count.
Get price breakdown details (base price, taxes, fees, discounts, final value) for sales.
Get aggregated sales summary (total revenue, count by status/payment type) for a date range.
Get the course progress of a specific student (completed lessons, percentage).
List all students/members registered in a club.
Visão geral dos alunos na área de membros — counts + progresso. Cards (total, ativos, bloqueados) + PieChart engajamento + DataTable ranking. Use pra 'lista de alunos', 'progresso médio', 'quantos alunos completaram'.
Visão 360 de um assinante — perfil + histórico de compras. Cards de LTV/qty/ticket + DataTable com purchases. Use pra 'ver dados do assinante X', 'histórico completo do código Y'.
List all purchases of a specific subscriber by their subscriber code.
Cancel a single subscription by its code.
Change the billing due day (charge date) for a subscription.
Reactivate a single cancelled subscription.
Get all payment/charge transactions for subscriptions (billing history).
Painel de saúde das assinaturas — counts por status + lista. Grid com cards (ativos, atrasados, cancelados) + PieChart breakdown + DataTable. Use pra 'saúde das assinaturas', 'visão geral das assinaturas', 'quantos assinantes ativos'.
List all active subscriptions with subscriber info, product, plan, and current status.
Get aggregated subscription counts by status (ACTIVE, DELAYED, CANCELLED, etc.).
Inconsistent parameter descriptions. Core tools like hotmart_sales_history_list, hotmart_subscriptions_list have minimal param descriptions (e.g., 'Maximum number of results to return' without bounds). Destructive tool hotmart_sale_refund lacks guidance on transaction_id format beyond 'e.g., HP2890253164'. Violates pattern:tool-description and pattern:constrained-input.
Destructive operations lack confirmation or dry-run support. Tools like hotmart_sale_refund and hotmart_coupon_delete have no documented confirmation pattern or recovery guide. Agents cannot safely retry or rollback if a refund partially succeeds. Violates pattern:confirmation-request.
App tool descriptions contain Portuguese text and lack English clarity for LLM context routing. E.g., hotmart_students_overview_app: 'Visão geral dos alunos...' with mixed PT/EN. Apps are advertised as rendering Prefab UI but descriptions do not explain when to invoke vs. standard tools. Violates pattern:tool-description and creates ambiguous tool selection.
Pagination not fully specified. Tools like hotmart_sales_history_list accept max_results but no offset/cursor return. No indication of whether results are paginated, what total count is, or how to fetch next page. Pattern:paginated-result requires explicit pagination support with total/cursor.
Error handling and recovery guidance absent. No documented error cases, validation rules, or guidance for LLMs on what to do if a call fails. E.g., hotmart_subscriber_purchases_list with subscriber_code param: no guidance on format, what error if not found, or recovery path. Violates pattern:recovery-guide and pattern:error-classification.
Opaque identifiers without human-friendly alternatives. Tools require product_id (integer), subscriber_code (alphanumeric), event_id (integer) with no documented way to resolve from names or email. Pattern:tool-description and mxe:natural-identifiers require supporting names/emails alongside IDs to reduce multi-step lookups.