loogle-scripts/services/loogle-mcp/docs/ONBOARDING.md

Onboarding client AI — Loogle MCP Hub

Endpoint MCP: https://mcp.loogle.it/mcp

OAuth: al primo collegamento compare la pagina login Loogle. Usa le credenziali famiglia.

Password iniziale = username (es. lucia / lucia). Cambiala da https://mcp.loogle.it/dashboard

---

Daniele (admin)

• Username: daniele
• Tool admin: reindex_document, audit completo, revoca token refresh

Lucia

• Username: lucia
• Progetti isolati in /mnt/ha-apps/mcp/context/lucia/

Davide

• Username: davide

Luca

• Username: luca

---

ChatGPT (Plus/Pro/Business)

1. Abilita Developer Mode nelle impostazioni ChatGPT
2. Settings → Connectors → Add MCP Connector
3. URL server: https://mcp.loogle.it/mcp
4. Completa OAuth con le tue credenziali
5. Abilita i tool desiderati nella conversazione

Redirect URI supportati (pre-registrati):

• https://chatgpt.com/connector_platform_oauth_redirect
• https://chat.openai.com/connector_platform_oauth_redirect

Claude App / Claude Desktop

1. Settings → Connectors → Add remote MCP server
2. URL: https://mcp.loogle.it/mcp
3. Autenticazione OAuth al primo uso

Redirect URI: https://claude.ai/api/mcp/auth_callback

Cursor IDE

Cursor supporta MCP remoto con OAuth automatico (Streamable HTTP).

Configurazione

Globale (tutti i progetti): ~/.cursor/mcp.json
Solo questo repo: .cursor/mcp.json (già presente nel progetto loogle-mcp)

{
  "mcpServers": {
    "loogle-mcp": {
      "url": "https://mcp.loogle.it/mcp"
    }
  }
}

Collegamento

1. Apri Cursor Settings → Tools & MCP
2. Trova loogle-mcp → clic Connect
3. Si apre il browser → login con le tue credenziali Loogle (daniele, lucia, …)
4. Autorizza → Cursor torna con i tool attivi

Redirect OAuth Cursor (già registrati sul server):

• https://www.cursor.com/agents/mcp/oauth/callback (web / Agents)
• http://localhost:8787/callback (desktop app)

Uso in chat

Chiedi all'agente di usare i tool MCP, ad esempio:

«Usa whoami e list_projects per vedere i miei progetti Loogle»

Se il server risulta disconnesso: Reconnect da Tools & MCP.

---

Gemini CLI

Aggiungi in ~/.gemini/settings.json (o equivalente):

{
  "mcpServers": {
    "loogle": {
      "url": "https://mcp.loogle.it/mcp",
      "transport": "http"
    }
  }
}

Al primo avvio completa il flow OAuth nel browser.

Cursor IDE

File .cursor/mcp.json nel progetto:

{
  "mcpServers": {
    "loogle-mcp": {
      "url": "https://mcp.loogle.it/mcp"
    }
  }
}

---

Tool disponibili

Tool	Descrizione
ping	Test connettività
whoami	Utente e scope
list_projects	Progetti utente
create_project	Nuovo archivio contesto
get_project_context	Legge memoria progetto
save_context	Salva/appende memoria
search_context	Ricerca semantica contesti
search_knowledge	RAG su Paperless + contesti + Gitea indicizzati
search_gitea_knowledge	RAG solo su file Gitea (runbook, markdown)
list_gitea_indexed_files	File Gitea nel vector store
reindex_gitea_repo	Re-indicizza un repo (admin/owner)
get_document	Testo documento Paperless
list_recent_documents	Ultimi doc indicizzati
reindex_document	Solo admin
list_repos	Repository Gitea accessibili
get_file	Legge file da repo Gitea
search_code	Cerca nel codice sorgente
list_issues / get_issue	Issue su repo Gitea
create_issue	Crea issue (scope gitea:write)
link_project_repo	Collega/scollega repo Gitea a un progetto

Esempio prompt agente

"Usa list_projects per vedere i miei progetti, poi get_project_context sul progetto attivo e search_knowledge per trovare documenti rilevanti su [argomento]."

Troubleshooting

• 401 su MCP: token scaduto — riconnetti il connector OAuth
• Knowledge vuota: verifica token Paperless e Ollama su DS920
• Dashboard: https://mcp.loogle.it/dashboard