Conectar Claude ao aqoon

O aqoon funciona com o Claude Desktop e Claude Code através do Model Context Protocol (MCP). Uma vez conectado, o Claude pode pesquisar sua base de conhecimento diretamente durante conversas — sem necessidade de copiar e colar.

Claude Desktop (Conectores)

A maneira mais fácil de conectar o Claude Desktop. Sem arquivos de configuração ou comandos de terminal.

Passo 1: Adicionar aqoon como conector

Você só precisa fazer isso uma vez:

1. Abra o Claude Desktop
2. Clique em Personalizar (canto inferior esquerdo)
3. Clique em Conectores na barra lateral
4. Clique no ícone + no topo
5. Selecione Adicionar conector personalizado
6. Preencha o formulário:
   • Nome: aqoon
   • URL: https://aqoon.ai/mcp/
7. Clique em Salvar

Passo 2: Conectar

1. Na lista de Conectores, encontre aqoon e clique em Conectar
2. Seu navegador abre — faça login com sua conta aqoon
3. Clique em Aprovar na página de consentimento
4. Pronto! O Claude Desktop agora pode pesquisar sua base de conhecimento.

Isso cria uma chave de API de acesso total automaticamente. Você pode visualizá-la e revogá-la em Chaves de API no seu painel.

Claude Code e Chaves de API

Para o Claude Code ou se preferir configuração manual, você precisará de uma chave de API. Crie uma em Chaves de API na barra lateral. Uma chave de acesso total é a escolha certa para uso pessoal.

Isso conecta o Claude diretamente ao aqoon pela internet. O Claude Code não precisa de dependências extras. O Claude Desktop requer Node.js ≥ 18 para a ponte mcp-remote.

Claude Code

Execute este comando uma vez no seu terminal, substituindo your-instance e aqn_your_api_key pelos seus valores reais:

claude mcp add aqoon --transport http https://your-instance/mcp \
  --header "Authorization: Bearer aqn_your_api_key"

Claude Desktop

Abra o arquivo de configuração do Claude Desktop (claude_desktop_config.json) e adicione o seguinte dentro do bloco mcpServers. Isso usa mcp-remote para conectar o Claude Desktop ao servidor remoto (requer Node.js).

{
  "mcpServers": {
    "aqoon": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-instance/mcp",
        "--header",
        "Authorization: Bearer aqn_your_api_key"
      ]
    }
  }
}

Reinicie o Claude Desktop após salvar o arquivo. A primeira inicialização pode demorar um momento enquanto o mcp-remote é instalado.

Opção B: Pacote Local

Se preferir executar um servidor MCP local na sua máquina, instale o pacote aqoon-mcp. Isso requer que o Python esteja instalado.

pip install aqoon-mcp

Claude Code

claude mcp add aqoon aqoon-mcp \
  -e AQOON_URL=https://your-instance \
  -e AQOON_API_KEY=aqn_your_api_key

Claude Desktop

Adicione o seguinte ao claude_desktop_config.json:

{
  "mcpServers": {
    "aqoon": {
      "command": "aqoon-mcp",
      "env": {
        "AQOON_URL": "https://your-instance",
        "AQOON_API_KEY": "aqn_your_api_key"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar o arquivo.

Verificando a Conexão

Após a configuração, inicie uma nova conversa no Claude e pergunte:

"Liste as coleções na minha base de conhecimento aqoon."

Se o Claude responder com os nomes das suas coleções, a conexão está funcionando. Consulte Ferramentas e Uso do MCP para uma lista completa do que o Claude pode fazer com o aqoon.

Solução de Problemas

Problema	Causa	Solução
"Could not load app settings" com command: Required	O Claude Desktop não suporta "type": "http" ou "type": "streamable-http" diretamente	Use a configuração mcp-remote mostrada acima (com "command": "npx")
Servidor desconectado / SyntaxError: node:fs/promises	Versão do Node.js é muito antiga (< 18)	Instale Node.js ≥ 18. Se usar nvm: nvm alias default 22. Ou use o caminho completo na configuração: "command": "/path/to/node/v22/bin/npx"
Servidor desconectado (sem erro nos logs)	Cache npx obsoleto de uma versão mais antiga do Node	Exclua o cache: rm -rf ~/.npm/_npx/ e reinicie o Claude Desktop
Claude não usa as ferramentas do aqoon	Servidor não listado nas ferramentas do Claude	Clique no ícone de plug no Claude Desktop para verificar. Se estiver ausente, reinicie o Claude Desktop