Como pensamos o MCP do Perpetuus CRM

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

• Menos tools, mais ricas — threads aninhadas, dados que o agente sempre precisa numa call
• Token economy — paginação agressiva; evolução para formatos compactos (estilo TOON)
• Descrições = prompt — testadas com agentes reais em contexto fresco
• Auth como produto — JWT + tenant hoje; PAT escopado no roadmap
• Backend = fonte de verdade — MCP nunca acessa banco direto

Passo a passo: conectar no Cursor

1. Clone o monorepo e suba perpetuus-crm-mcp (HTTP ou stdio).
2. Gere JWT no app Perpetuus e copie o documentId da organização.
3. Configure STRAPI_URL, PERPETUUS_JWT e PERPETUUS_TENANT_ID.
4. Adicione o servidor em Cursor → Settings → MCP e teste com “liste meus boards”.

{
  "mcpServers": {
    "perpetuus-crm": {
      "command": "node",
      "args": ["perpetuus-crm-mcp/dist/index.js"],
      "env": {
        "STRAPI_URL": "https://api.perpetuus.com.br",
        "PERPETUUS_JWT": "<jwt>",
        "PERPETUUS_TENANT_ID": "<org-id>"
      }
    }
  }
}

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