API pública ≠ MCP

Desenvolvedores consomem APIs para pipelines ETL longos e contratos estáveis. Agentes autônomos fazem perguntas e ações pontuais — cada tool call custa tokens e latência.

Por isso o perpetuus-crm-mcp não é um wrap automático do OpenAPI. Tools são desenhadas para casos agent-first: snapshot de pipeline, contexto de card qualificado, busca fuzzy.

Princípios que seguimos

Catálogo amplo, com tools compostas — mais de cem tools cobrem o CRM, e as perguntas frequentes têm tools compostas que entregam numa call o que o agente sempre precisa (card + contato + tarefas + atividades, snapshot do pipeline)
Token economy — paginação com limite (padrão 25, máximo 100) e resumos; as respostas hoje saem em JSON, e formatos compactos (estilo TOON) estão no roadmap
Descrições = prompt — testadas com agentes reais em contexto fresco
Auth como produto — token do usuário ou PAT do CRM + tenant; o backend aplica as permissões
Backend = fonte de verdade — MCP nunca acessa banco direto

Passo a passo: conectar no Cursor

Clone o monorepo e suba perpetuus-crm-mcp (HTTP ou stdio).
Gere um token (PAT) no app Perpetuus, em Configurações → API Tokens e MCP, e copie o identificador da organização.
Configure STRAPI_URL, MCP_CRM_USER_TOKEN e MCP_CRM_TENANT_ID.
Adicione o servidor em Cursor → Settings → MCP e teste com “liste meus boards”.

{
  "mcpServers": {
    "perpetuus-crm": {
      "command": "node",
      "args": ["perpetuus-crm-mcp/dist/stdio.js"],
      "env": {
        "STRAPI_URL": "https://api.perpetuus.com.br",
        "MCP_CRM_USER_TOKEN": "<token>",
        "MCP_CRM_TENANT_ID": "<org-id>"
      }
    }
  }
}

Inspirado nas lições da Attio, adaptado ao nosso stack Strapi + boards + Chatwoot.

Como pensamos o MCP do Perpetuus CRM