Graspil MCP

Para o índice completo da documentação, consulte llms.txt. Versões em Markdown das páginas de documentação estão disponíveis adicionando .md às URLs das páginas; esta página está disponível como Markdown.

Servidor MCP (agentes de IA)

O Graspil fornece seu próprio servidor MCP — uma forma de conectar um agente de IA (Claude, ChatGPT ou qualquer outro cliente compatível com MCP) diretamente aos seus dados no Graspil, para que o agente possa criar relatórios, consultar suas estatísticas e gerenciar transmissões e automações por conta própria — sem abrir o painel.

Uma vez que o servidor MCP esteja conectado ao seu agente, você pode simplesmente pedir em linguagem natural:

"Mostre-me quantos novos usuários entraram na semana passada em comparação com a semana anterior"
"Crie um relatório de funil de pagamento para junho e salve-o"
"Quanto ganhei com o programa de indicação este mês?"
"Crie uma transmissão com este texto ... e envie para todos os usuários ativos"

— e o agente chamará as ferramentas certas, buscará os dados e responderá.

{% hint style="info" %} O servidor MCP é uma camada fina sobre a API regular do Graspil: o agente trabalha com os mesmos bots e permissões que sua chave de API permite, e as restrições de acesso/plano se aplicam exatamente como no painel ou na API. {% endhint %}

---

O que o agente pode fazer via MCP

Área	O que o agente pode fazer	Plano
Relatórios	Listar eventos e recursos (bots) disponíveis, criar e visualizar relatórios (tendências, funis, retenção, UTM), salvar relatórios prontos, listar os salvos anteriormente	Premium
Painéis	Listar, criar, editar e excluir painéis	Premium
Transmissões	Criar, editar, lançar, cancelar e listar transmissões	Premium
Automações	Criar, editar, publicar/despublicar, excluir e listar automações (gatilho → ação)	Premium
Landing pages	Criar, editar, excluir e listar landing pages	Premium
Integrações	Listar integrações conectadas e tipos de integração disponíveis	Premium
Histórico de conversas	Visualizar o histórico de mensagens do bot com usuários, com filtros e busca por texto (somente leitura)	Premium
Programa de indicação	Visualizar saldo, lista de indicações, histórico de pagamentos e taxas efetivas (somente leitura)	Premium
Documentação	Busca em texto completo na documentação do Graspil — o agente pode consultar "como isso funciona" por conta própria	Qualquer (incl. gratuito)

{% hint style="warning" %} No plano gratuito, apenas a busca na documentação está disponível via MCP. Todas as outras áreas (relatórios, painéis, transmissões, automações, landing pages, integrações, histórico de conversas, programa de indicação) exigem um plano Premium (ou Trial); caso contrário, a solicitação falha com 403 Forbidden ("Tarifa Premium necessária"). {% endhint %}

{% hint style="warning" %} Operações sensíveis do programa de indicação (acúmulos, pagamentos, propriedade de códigos) não são expostas via MCP — essas ações permanecem disponíveis apenas pelo painel ou pela API direta. {% endhint %}

---

Autenticação

O agente se conecta usando sua chave pessoal da seção Chaves de API — uma chave simples de bot único (da seção "Meus Bots", consulte Autorização) não funciona para MCP; você precisa de uma chave pessoal (nível de usuário).

1. Abra Perfil → Chaves de API no painel.
2. Clique em "Criar chave" e dê um nome (ex.: "Claude MCP").
3. Opcionalmente, restrinja a chave a bots específicos e permissões por seção (somente leitura / acesso total) — por padrão, a chave dá acesso a todos os seus bots.
4. Copie o valor da chave — ele é exibido apenas uma vez em texto simples, então salve-o em um local seguro.

Uma única chave funciona em todos os bots aos quais você tem acesso — o agente escolhe o bot certo durante a conversa (perguntando se houver mais de um), então não há necessidade de conectar cada bot separadamente.

---

Conectando um agente

O servidor MCP do Graspil fala Streamable HTTP — a maioria dos clientes de IA modernos (Claude Desktop, Claude Code, etc.) suporta isso como um "servidor MCP remoto" configurado por URL.

Endereço do servidor: https://mcp.graspil.com/mcp

Formato geral de configuração para clientes que suportam servidores MCP remotos por URL com cabeçalhos personalizados:

{% code overflow="wrap" %}

{
  "mcpServers": {
    "graspil": {
      "url": "https://mcp.graspil.com/mcp",
      "headers": {
        "Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

{% endcode %}

As etapas exatas variam por cliente:

• Claude Desktop / Claude Code — adicione o servidor nas configurações de integração (Configurações → Conectores / servidores MCP), especificando a URL e o cabeçalho Api-Key.
• Outros clientes compatíveis com MCP — use o mecanismo equivalente para adicionar um servidor MCP remoto por URL com um cabeçalho de autenticação personalizado.

Uma vez conectado, o agente pedirá a lista de bots disponíveis (se houver mais de um) e confirmará qual usar para a conversa.

---

FAQ

O agente pode ver dados de outros usuários?
Não. O agente opera estritamente dentro das permissões da sua chave de API — ele só vê os bots e dados aos quais sua chave tem acesso.

Posso restringir o que o agente pode fazer?
Sim. Assim como uma chave de API regular, você pode restringi-la a bots específicos e conceder permissões de "somente leitura" por seção (ex.: permitir que o agente visualize relatórios, mas não crie transmissões) — configurado ao criar ou editar a chave na seção "Chaves de API".

O que acontece se eu revogar a chave?
O agente perde o acesso imediatamente — o servidor MCP não armazena dados próprios e não armazena permissões em cache por muito tempo; cada solicitação é verificada com a mesma chave.

Preciso instalar algo?
Não, o servidor já está implantado e mantido pelo Graspil — você só precisa da chave de API e de um cliente compatível com MCP.

Por que o agente recebe 403 Forbidden?
No plano gratuito, apenas a busca na documentação está disponível via MCP — todas as outras áreas (relatórios, painéis, transmissões, automações, landing pages, integrações, histórico de conversas, programa de indicação) exigem um plano Premium (ou Trial); a solicitação é rejeitada com 403 ("Tarifa Premium necessária"). Atualize a conta/bot para Premium.