Vai al contenuto
LinkProfit

Server MCP per gli assistenti AI

Collega Claude Code, Claude Desktop o Cursor alla tua area di lavoro via Model Context Protocol: configurazioni pronte, catalogo degli strumenti, permessi e piani.

Aggiornato il 14 agosto 2026

Il server MCP permette a un assistente AI di lavorare direttamente con i tuoi link e con l'analytics: «accorcia questa landing page sul nostro dominio di marca», «quali cinque link hanno guadagnato più clic la settimana scorsa», «silenzia fino a lunedì la regola di avviso per il dominio della campagna». L'assistente lo fa attraverso la stessa API pubblica che chiameresti tu, con esattamente i diritti della chiave con cui lo hai collegato.

https://api.linkprofit.com/v1/mcp

Il trasporto è JSON-RPC 2.0 su HTTP e segue la revisione 2025-06-18 del Model Context Protocol (viene accettata anche la revisione 2025-03-26). Non esiste un flusso di eventi avviato dal server né alcuno stato di sessione: GET e DELETE rispondono 405, non viene emesso alcun Mcp-Session-Id e ogni richiesta porta con sé tutto il contesto che le serve, dentro la chiave stessa. Funziona qualsiasi client MCP che parli HTTP — i tre qui sotto sono semplicemente quelli per cui forniamo configurazioni da copiare e incollare.

1. Creare una chiave per l'assistente

Nella tua dashboard apri Impostazioni → Chiavi API e crea una chiave di area di lavoro (lp_live_…). Concedile solo gli ambiti che l'assistente deve davvero avere — il catalogo degli strumenti più sotto elenca ciò che serve a ciascuno. Una chiave con links:read + analytics:read ti dà un assistente di sola lettura, capace di rispondere alle domande ma non di cambiare nulla.

Il valore completo della chiave viene mostrato una sola volta. Trattala come una password: finirà in un file di configurazione sulla tua macchina.

2. Aggiungere il server al tuo client

Claude Code

Un solo comando, nessun file di configurazione da modificare:

claude mcp add --transport http linkprofit https://api.linkprofit.com/v1/mcp \
  --header "Authorization: Bearer lp_live_…your key…"

Aggiungi --scope user per rendere il server disponibile in ogni progetto sulla tua macchina invece che solo in quello corrente. Verifica il risultato con claude mcp list, e rimuovilo in seguito con claude mcp remove linkprofit.

Claude Desktop

Modifica il file di configurazione — su macOS ~/Library/Application Support/Claude/claude_desktop_config.json, su Windows %APPDATA%\Claude\claude_desktop_config.json — e aggiungi il server:

{
  "mcpServers": {
    "linkprofit": {
      "type": "http",
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

Riavvia Claude Desktop. Gli strumenti compaiono nel selettore degli strumenti di una nuova conversazione.

Cursor

Crea .cursor/mcp.json nel progetto (oppure ~/.cursor/mcp.json per averlo ovunque):

{
  "mcpServers": {
    "linkprofit": {
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

Cursor rileva il file al salvataggio e mostra il server in Settings → MCP.

Verificare la connessione a mano

I problemi di qualsiasi client si leggono più facilmente a livello di protocollo. Questo è lo stesso handshake che eseguono i client:

curl -s -X POST https://api.linkprofit.com/v1/mcp \
  -H "Authorization: Bearer $LINKPROFIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

Una risposta sana indica la versione del protocollo, il server e la sua capacità relativa agli strumenti. Sostituisci il metodo con tools/list per vedere il catalogo, e con ping per verificare nient'altro che la raggiungibilità.

Strumenti

Dieci strumenti, tutti confinati all'area di lavoro a cui appartiene la chiave. La colonna dell'ambito indica ciò che la chiave deve possedere; uno strumento per cui la chiave non ha l'ambito semplicemente fallisce quando viene chiamato, non viene nascosto dal catalogo.

| Strumento | Che cosa fa | Ambito richiesto | | --- | --- | --- | | list_links | Elenca i link brevi dell'area di lavoro, con un filtro facoltativo per stringa di ricerca | links:read | | get_link | Legge un singolo link dal suo id | links:read | | create_link | Crea un link breve; senza domain_id viene usato il dominio predefinito dell'area di lavoro | links:write | | update_link | Cambia la destinazione o il titolo di un link esistente | links:write | | analytics_summary | Clic, visitatori e scansioni QR di un periodo, facoltativamente per un solo link | analytics:read | | analytics_breakdown | Clic e visitatori raggruppati per paese, città, dispositivo, browser, sistema operativo, referer o UTM | analytics:read | | analytics_top_links | I link più cliccati del periodo, con clic e visitatori | analytics:read | | analytics_timeseries | Clic e visitatori nel tempo, per ora, giorno o settimana | analytics:read | | list_alert_rules | Elenca le regole di avviso con i loro canali e la finestra di soppressione | alerts:read | | update_alert_rule | Attiva, disattiva o ritara la finestra di soppressione di una regola di avviso | alerts:write |

Gli schemi degli argomenti provengono dalle stesse definizioni che validano la chiamata, così ciò che viene detto all'assistente su uno strumento e ciò che il server accetta davvero non possono divergere. Gli strumenti di sola lettura sono annotati come tali, ed è questo che permette a un client di chiedere conferma prima dei tre strumenti che modificano i dati: create_link, update_link e update_alert_rule — più tutto ciò che una versione futura aggiungerà a quell'elenco.

Ogni chiamata a uno strumento che modifica dati viene scritta nel log di audit dell'area di lavoro, con la chiave che l'ha effettuata e l'annotazione che è arrivata via MCP: le modifiche di un assistente sono tracciabili quanto quelle di una persona.

Permessi e sicurezza

È la chiave a definire il confine dei permessi. Non esiste una «modalità assistente» privilegiata: la chiamata a uno strumento gira con gli ambiti della chiave, dentro l'area di lavoro della chiave, sotto lo stesso limite di frequenza e lo stesso isolamento tra tenant di una chiamata REST. Un id di un'altra area di lavoro riceve not_found, esattamente come via REST.

Tre abitudini che vale la pena adottare:

  • Dai all'assistente una chiave tutta sua, mai quella che usa la tua integrazione di produzione. Revocarla allora non costa nulla.
  • Parti in sola lettura. links:read + analytics:read copre le domande di reportistica che le persone pongono davvero a un assistente. Aggiungi links:write solo quando vuoi che i link vengano creati dalla chat.
  • Ruota la chiave se si espone. Una chiave dentro un file di configurazione viaggia con i backup, le condivisioni schermo e i ticket di assistenza. Revocala nella dashboard nel momento stesso in cui trapela; la richiesta successiva riceve 401.

Il limite di frequenza è condiviso con l'API REST — per chiave, su una finestra scorrevole di un minuto — quindi un assistente loquace e un job in background sulla stessa chiave si contendono lo stesso budget. È un altro argomento a favore di una chiave separata. Vedi Limiti di frequenza per gli header e le regole dei nuovi tentativi.

Requisiti di piano

Due funzionalità del piano regolano l'accesso all'endpoint:

  • api_access — il diritto di usare l'API in generale;
  • assistant_tools — il diritto di usare il catalogo degli strumenti e quindi MCP.

Entrambe si impostano sul piano su cui si trova la tua area di lavoro. Un'area di lavoro il cui piano non comprende una delle due riceve 403 con il codice plan_restricted e un messaggio che nomina la capacità mancante. Se rivendi LinkProfit con il tuo marchio, questa è una funzionalità che decidi tu se includere in un piano o vendere come upgrade.

Risoluzione dei problemi

403 plan_restricted — il piano non comprende assistant_tools (o api_access). Passa a un piano superiore; qui non c'è nulla nella chiave o nella configurazione del client che possa risolvere.

401 unauthorized — l'header manca, è malformato, oppure la chiave è sconosciuta, revocata o scaduta. I tre casi sono deliberatamente indistinguibili. Verifica che il valore sia la chiave per intero, che sia preceduto da Bearer , e che il client mandi davvero l'header — l'handshake con curl qui sopra risponde a questa domanda in una sola richiesta.

403 forbidden — è stata usata una chiave partner (lpp_live_…). MCP è una superficie di area di lavoro: crea una chiave di area di lavoro.

429 rate_limited — la chiave ha esaurito la sua finestra. La risposta porta con sé Retry-After; i client che riprovano subito non fanno che tenere la chiave bloccata.

405 su GET — è previsto, non è un guasto. Il server non offre alcun flusso di eventi e non mantiene sessioni; un client che parla soltanto il trasporto basato su SSE delle revisioni più vecchie non riesce a connettersi.

Uno strumento risponde con un errore invece che con i dati — in una trascrizione di chat due cose diverse si somigliano. Gli argomenti che non superano la validazione tornano indietro come risultato dello strumento contrassegnato come errore, con l'elenco dei campi incriminati, e l'assistente può correggersi e riprovare. Un ambito mancante torna indietro come errore di protocollo con il codice insufficient_scope e il nome dell'ambito: quello richiede una nuova chiave, non un altro tentativo.

Letture correlate