MCP no Claude, no Codex e no Cursor

O MCP (Model Context Protocol) deixa a IA que você já usa operar o Cognizy: ler conversas, buscar na base de conhecimento, criar tarefas, mover negócios, agendar posts. As ferramentas saem da própria API, com as mesmas regras dos agentes do Cognizy. A lista completa fica em Ferramentas do MCP.

Antes de começar

1. Crie uma chave em Configurações › Integrações › API e webhooks com só as permissões que a IA deve ter. Para começar, marque leitura nos módulos que você usa; libere escrita depois, módulo por módulo.
2. Escolha como conectar:
   • Local (pacote @cognizy/mcp, roda no seu computador com npx; precisa do Node 20 ou mais novo): Claude Desktop, Claude Code, Codex e Cursor.
   • Hospedado (https://mcp.cognizy.ai/mcp, sem instalar nada): clientes que deixam pôr um cabeçalho, como o Claude Code e o Cursor.

Claude Desktop

Edite o arquivo de configuração (no Mac, ~/Library/Application Support/Claude/claude_desktop_config.json; no Windows, %APPDATA%\Claude\claude_desktop_config.json) e reinicie o app:

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": { "COGNIZY_API_KEY": "cole-a-chave-aqui" }
    }
  }
}

Essa configuração vale para todas as conversas. Para mais de uma empresa, crie uma entrada por chave (cognizy-loja, cognizy-clinica…) e ligue só a que quiser em cada conversa.

Claude Code

Local:

claude mcp add --scope user cognizy -e COGNIZY_API_KEY=cole-a-chave-aqui \
  -- npx -y @cognizy/mcp

Hospedado:

claude mcp add --transport http cognizy https://mcp.cognizy.ai/mcp \
  --header "Authorization: Bearer $COGNIZY_API_KEY"

Uma chave é de uma empresa só. Para trabalhar com uma empresa em cada projeto, use --scope local dentro de cada pasta, com a chave daquela empresa. claude mcp list mostra qual está ativa.

Codex

O app, a linha de comando e a extensão do Codex usam ~/.codex/config.toml:

[mcp_servers.cognizy]
command = "npx"
args = ["-y", "@cognizy/mcp"]

[mcp_servers.cognizy.env]
COGNIZY_API_KEY = "cole-a-chave-aqui"

Cursor

Em ~/.cursor/mcp.json (ou .cursor/mcp.json no projeto). Local:

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": { "COGNIZY_API_KEY": "cole-a-chave-aqui" }
    }
  }
}

Hospedado:

{
  "mcpServers": {
    "cognizy": {
      "url": "https://mcp.cognizy.ai/mcp",
      "headers": { "Authorization": "Bearer cole-a-chave-aqui" }
    }
  }
}

O que pedir

• "Quantas conversas fechamos na semana passada? Separe por canal."
• "Busque na base de conhecimento a política de troca e resuma em 3 linhas."
• "Liste os negócios parados há mais de 7 dias na etapa Proposta."
• "Crie uma tarefa no quadro Suporte para ligar para a Maria amanhã às 10h."
• "Agende um post para sexta com a última arte do Izy Studio." (vai para aprovação)

Permissões e aprovação

• A IA só enxerga as ferramentas que a chave permite e os módulos ligados na empresa. Sem a permissão, a ferramenta nem aparece.
• O que chega ao cliente (mandar mensagem, agendar, cancelar, lançar campanha) não executa na hora: vira um pedido que um dono ou administrador aprova em Para revisar ou na aba Aprovações de IA. A IA recebe um actionId e pode acompanhar com get_pending_action_status ou desistir com cancel_pending_action.
• Posts nas redes vão para aprovação, a não ser que a chave tenha social:publish.
• Os envios diretos de e-mail não são ferramenta do MCP: ficam para o seu sistema, pela API. O send_whatsapp_message só aparece para chave com whatsapp:send; não dê essa permissão a uma IA se não for isso que você quer.

Limites

O MCP chama a API pública, então valem os mesmos limites da chave: 60 chamadas por minuto, 1.000 por hora e a cota mensal da empresa. Toda chamada fica registrada na atividade da chave.