CLI ed editor

Customermates è il CRM open source pensato per l’IA. Una volta collegato, il tuo agente di programmazione legge e scrive contatti, trattative e note senza uscire dal terminale. Tutti i client qui descritti si autenticano allo stesso modo: una chiave API nell’intestazione x-api-key verso <BASE_URL>/api/v1/mcp, dove <BASE_URL> è l’indirizzo con cui apri Customermates, nel cloud o sulla tua istanza. I frammenti qui sotto contengono già l’indirizzo del sito che mostra questa pagina; se apri Customermates altrove, sostituisci anche quell’indirizzo, oltre a YOUR_KEY.

Crea una chiave API

In Customermates apri Chiavi API e connettori, fai clic su Aggiungi e scegli Chiave API standard. Dai alla chiave il nome del client (per esempio Claude Code); senza una data in Scade tra non scade mai. La chiave di 64 caratteri viene mostrata una sola volta, quindi copiala subito. Connessioni rapide nella stessa finestra lo fa al posto tuo: dà alla chiave il nome del client, la imposta in modo che scada dopo 365 giorni e mostra il frammento di configurazione con la chiave già inserita e la sua scadenza sotto.

Per creare una chiave serve Crea sulla riga API e webhook del tuo ruolo, e per la pagina stessa serve Accesso in lettura Tutti su quella riga; il ruolo integrato Amministratore ha entrambi. Una chiave eredita i permessi dell’utente che l’ha creata; non esiste un ambito per singola chiave. Crea una chiave per ogni client, così puoi revocarne una senza toccare le altre; il registro attività registra l’utente a cui appartiene una chiave, non la chiave stessa. Chiavi API e MCP funzionano su ogni piano e sulle istanze self-hosted. Dettagli: Chiavi API.

Claude Code

Claude Code aggiunge i server MCP tramite la propria CLI. Basta un comando. Eseguilo in un terminale qualsiasi, sostituendo YOUR_KEY:

claude mcp add --transport http customermates https://customermates.com/api/v1/mcp \
  --header "x-api-key: YOUR_KEY"

Non serve riavviare né modificare file di configurazione. Claude Code si collega automaticamente. Esegui claude mcp list per verificare che customermates compaia.

Ambito: per impostazione predefinita il comando usa l’ambito locale. Aggiungi --scope user per rendere Customermates disponibile ovunque sul tuo computer, oppure --scope project per scriverlo nel file .mcp.json di un repository, così lo trovano anche i colleghi.

Codex

Codex si collega direttamente a Customermates tramite Streamable HTTP. codex mcp add customermates --url <BASE_URL>/api/v1/mcp aggiunge l’URL del server, ma il comando della CLI non ha un’opzione per un’intestazione x-api-key personalizzata. Per l’accesso con chiave API, apri ~/.codex/config.toml (crealo se manca) e aggiungi il blocco completo qui sotto, sostituendo YOUR_KEY:

[mcp_servers.customermates]
enabled = true
url = "https://customermates.com/api/v1/mcp"
http_headers = { "x-api-key" = "YOUR_KEY" }

Per leggere la chiave dall’ambiente invece di salvarla nel file, sostituisci la riga http_headers del blocco qui sopra con:

env_http_headers = { "x-api-key" = "CUSTOMERMATES_API_KEY" }

Poi esporta CUSTOMERMATES_API_KEY nel profilo della tua shell. Le nuove sessioni rilevano il server, quindi chiudi quella corrente e avviane una nuova.

Lo stesso endpoint HTTP accetta anche OAuth. Se preferisci accedere in questo modo, aggiungi l’URL con codex mcp add customermates --url <BASE_URL>/api/v1/mcp, poi esegui codex mcp login customermates. Il bridge stdio descritto più avanti serve ai client Claude Desktop che ne hanno bisogno.

Cursor

Per configurare Cursor, apri Settings → Tools & MCP → Add new MCP server e incolla questo, sostituendo YOUR_KEY:

{
  "customermates": {
    "url": "https://customermates.com/api/v1/mcp",
    "headers": {
      "x-api-key": "YOUR_KEY"
    }
  }
}

Cursor ricarica la configurazione al volo, quindi non serve riavviare. Gli strumenti compaiono subito in Composer. Per modificare direttamente il file, lo stesso blocco va in ~/.cursor/mcp.json (globale) oppure in <project>/.cursor/mcp.json (per progetto), all’interno di mcpServers.

Gemini CLI

Gemini CLI carica i server MCP da ~/.gemini/settings.json. Unisci questo blocco, sostituendo YOUR_KEY:

{
  "mcpServers": {
    "customermates": {
      "httpUrl": "https://customermates.com/api/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_KEY"
      }
    }
  }
}

Se mcpServers contiene già delle voci, aggiungi customermates accanto a quelle esistenti, senza sovrascrivere l’oggetto.

Claude Desktop (file di configurazione)

Per Claude Desktop il percorso consigliato è quello del connettore: OAuth, senza chiave, sincronizzato tra i tuoi dispositivi. Con un piano gratuito, o se preferisci una chiave statica, funziona anche il file di configurazione qui sotto.

Apri Claude → Settings → Developer → Edit Config, oppure direttamente il file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Unisci questo blocco, sostituendo YOUR_KEY:

{
  "mcpServers": {
    "customermates": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://customermates.com/api/v1/mcp",
        "--header",
        "x-api-key:YOUR_KEY"
      ]
    }
  }
}

mcp-remote è un adattatore che permette a Claude Desktop di dialogare con un server MCP HTTP remoto tramite stdio. Si scarica al primo avvio con npx, quindi serve Node 18+ nel PATH.

Poi riavvia: chiudi completamente l’app (⌘Q su macOS, non basta chiudere la finestra) e riaprila. Customermates compare nel pannello degli strumenti con l’elenco degli strumenti del CRM.

Prova il primo prompt

Il server fornisce istruzioni di connessione che descrivono la propria superficie di strumenti, le regole di sicurezza e il modo di recuperare le pagine pertinenti della Base di conoscenza. Sono i client a decidere se passare queste istruzioni al proprio agente. Se il tuo non lo fa, aggiungi la regola di recupero della Base di conoscenza alle istruzioni permanenti di quel client. Nei client che supportano i prompt MCP (come Claude Code) puoi eseguire il prompt integrato get-started per un avvio guidato: legge prima il tuo spazio di lavoro e le pagine pertinenti della Base di conoscenza, poi chiede solo le informazioni mancanti.

• «Imposta il campo Stato della trattativa Acme su “Vinta” e aggiungi una nota che dice che il contratto è stato firmato oggi.»
• «Mostrami gli ultimi dieci contatti che ho creato. Ce n’è qualcuno senza indirizzo e-mail?»
• «Crea un contatto per Jane Doe presso Initech, collegalo all’organizzazione Initech e avvia una trattativa per 12 ore di consulenza.»
• «Quali conversazioni con i clienti aspettano una mia risposta? Prepara una risposta alla più vecchia e salvala come bozza.»

Il prompt di risposta richiede un canale collegato su Customermates Cloud dal piano Pro; la bozza resta nella conversazione finché non la rivedi e non la invii.

Ogni spazio di lavoro definisce i propri tipi di record, come contatti, trattative o attività, e anche attributi come la fase di una trattativa o la priorità di un’attività dipendono dalla configurazione dello spazio di lavoro. Chiama discover_record_types e poi get_record_model per ottenere gli ID dei tipi pertinenti prima di scrivere.

Risoluzione dei problemi

Prossimi passi

• Connettore personalizzato: il percorso OAuth per le app Claude e ChatGPT.
• Catalogo degli strumenti MCP: tutti gli strumenti che l’agente può chiamare.
• Webhook: iscrivi altri sistemi alle modifiche del CRM.