Server MCP di Elido per Claude Desktop, Cursor e Claude Code

Il server MCP di Elido è un piccolo processo Node che permette a Claude Desktop, Cursor o Claude Code di creare link corti, elencarli e leggere le serie temporali dei clic dall'interno di una chat. Vive nel monorepo in packages/mcp-server, parla MCP su stdio e dialoga con la stessa API REST di tutto il resto.

Una correzione in anticipo, perché una versione precedente di questa guida sbagliava: il pacchetto non è su npm e non è ancora pubblico. Al 2026-11-11, npm view @elido/mcp-server restituisce un 404; una release pubblica arriverà presto. Fino ad allora lo esegui da una build locale. Tutto quanto segue è stato verificato sul codice in packages/mcp-server e services/api-core.

Cos'è MCP

Il Model Context Protocol è uno standard aperto per permettere a un client AI di chiamare tool che vivono fuori dal modello. Il client avvia o si connette a un server, gli chiede l'elenco dei tool e invia le chiamate ai tool come messaggi JSON-RPC. Il server fa il lavoro e restituisce testo che il modello legge. Il modello non possiede mai la tua chiave API; la possiede il server.

La specifica definisce due trasporti, stdio per i processi locali e Streamable HTTP per quelli remoti (specifica MCP, ultima revisione 2026-07-28, consultato il 2026-10-25). Il server di Elido implementa solo stdio.

Cosa fa il server

È scritto a mano, senza il @modelcontextprotocol/sdk ufficiale, per restare privo di dipendenze. In src/index.ts risponde a quattro cose: initialize (che riporta la versione di protocollo 2024-11-05), tools/list, tools/call e la notifica notifications/initialized. Tutto il resto riceve un errore "method not found". Non ci sono handler per resources, prompts o ping.

Ogni chiamata a un tool diventa una richiesta REST autenticata a ELIDO_API_BASE (predefinito https://api.elido.app) con Authorization: Bearer <key> e l'header User-Agent: elido-mcp-server/0.1.0. Le chiamate fallite tornano come un errore che include lo stato HTTP e i primi 400 caratteri della risposta.

Su generate_qr: api-core serve un POST /v1/qr/generate pubblico e un design per link a GET /v1/workspaces/{id}/links/{link_id}/qr, ma nulla al percorso che il tool chiama. Finché non sarà riconciliato, non costruirei un flusso di lavoro su di esso. È nel backlog.

Compilarlo e ottenere una chiave API

Il monorepo è privato, quindi i passaggi seguenti valgono quando hai il sorgente del pacchetto (una release pubblica arriverà presto). Compila il pacchetto:

pnpm install
pnpm --filter @elido/mcp-server build

Questo produce packages/mcp-server/dist/index.js. Ti serve Node 20 o più recente (engines nel suo package.json).

Per la chiave, apri Dashboard, poi API keys (/dashboard/api-keys), dai alla chiave il nome dell'agente e scegli un ruolo. Il modulo offre viewer, editor e admin, e editor è il predefinito. Le chiavi di Elido portano un ruolo del workspace, non scope per singolo tool. Una chiave viewer è l'opzione in sola lettura: può elencare e leggere gli analytics, e l'API rifiuta create_link. Imposta una scadenza se la chiave è per una prova. Copia la chiave quando viene mostrata e tienila fuori dal controllo di versione.

Configurare Claude Desktop

Claude Desktop legge claude_desktop_config.json. La posizione della configurazione e la scheda delle impostazioni Developer sono descritte nella documentazione MCP (connettere server locali, consultato il 2026-10-25). Su macOS il file è ~/Library/Application Support/Claude/claude_desktop_config.json, e su Windows %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "elido": {
      "command": "node",
      "args": [
        "/absolute/path/to/url-shortener/packages/mcp-server/dist/index.js"
      ],
      "env": {
        "ELIDO_API_KEY": "elido_your_key_here",
        "ELIDO_WORKSPACE_ID": "42"
      }
    }
  }
}

Usa un percorso assoluto. ELIDO_WORKSPACE_ID è facoltativo solo quando la chiave vede esattamente un workspace; il server chiama allora GET /v1/workspaces una volta e mette in cache l'id. Con due o più workspace genera un errore che ti dice di impostare la variabile, quindi impostala fin dall'inizio.

Riavvia Claude Desktop dopo il salvataggio. Se il server non compare, esegui prima lo stesso comando in un terminale. Una chiave mancante non ferma il processo, stampa un avviso su stderr e ogni chiamata a un tool poi fallisce.

Configurare Cursor e Claude Code

Cursor legge la stessa forma mcpServers da .cursor/mcp.json in un progetto, o da ~/.cursor/mcp.json per tutti i progetti (documentazione MCP di Cursor, consultato il 2026-10-25). Incolla il blocco qui sopra, aggiungi il file a .gitignore perché contiene una chiave attiva e controlla il server nelle impostazioni MCP di Cursor.

Claude Code aggiunge un server stdio dalla riga di comando (documentazione MCP di Claude Code, consultato il 2026-10-25):

claude mcp add --env ELIDO_API_KEY=elido_your_key_here --env ELIDO_WORKSPACE_ID=42 \
  --transport stdio elido -- node /absolute/path/to/packages/mcp-server/dist/index.js

Le chiavi in un file di configurazione sono in chiaro. Su una macchina condivisa, dai a ciascuno la propria chiave in modo che la traccia di audit significhi qualcosa.

Due sessioni, con le forme reali delle richieste

Sono conversazioni illustrative, non registrazioni, e i numeri sono inventati. Gli argomenti dei tool e i campi dei risultati corrispondono al codice.

Accorciare un link di campagna. Chiedi a Claude di accorciare https://shop.example.com/spring con slug spring e tag spring. Chiama create_link con destination_url, slug, title e tags. Poiché non è stato passato alcun domain_id, il server recupera prima GET /v1/workspaces/{id}/domains e usa il primo restituito. Se il tuo workspace ha più domini, passa tu domain_id. L'API risponde con il record del link che include short_url, e Claude lo mette nella bozza. Se lo slug è occupato, l'API restituisce 409 "slug already exists for this domain", e Claude può sceglierne un altro.

Leggere i clic della settimana scorsa. Chiedi i clic giornalieri di un link, in ora di Berlino. Claude chiama query_analytics con link_id, from, to, interval: "day" e tz: "Europe/Berlin". Le date sono YYYY-MM-DD, e l'API rifiuta un intervallo in cui from non è precedente a to, quindi passa come to il giorno dopo il tuo ultimo giorno. Se le ometti, l'intervallo sono gli ultimi 30 giorni. Il risultato è {"items": [{"ts": "...", "count": 312}, ...]}. Non c'è un campo total, quindi chiedi a Claude di sommare i conteggi. Solo clic: da questo tool non arriva alcun dettaglio per paese, dispositivo o referrer.

Sicurezza e limiti

Ruoli, non scope. Scegli il ruolo più basso che fa il lavoro. Viewer per gli agenti di reporting, editor per quelli che creano link, admin solo con un motivo specifico.

Cosa lascia la tua macchina. Il server invia richieste alla tua base API di Elido e a nessun altro posto. Ciò che il tuo client AI invia al proprio fornitore è coperto dalla policy di quel fornitore.

Traccia di audit. Creare una chiave emette un evento di audit api_key.created, e la creazione di un link emette link.created. Non ho verificato come un evento venga attribuito a una singola chiave, quindi non fare affidamento sul log di audit per distinguere due agenti. Dai a ciascuno la propria chiave e tieni d'occhio l'elenco delle chiavi.

Rate limit. Le chiamate contano contro il limite del workspace: 10 richieste al secondo su Free, 30 su Pro e 100 su Business, con margini di burst di 20, 60 e 200 (services/api-core/internal/httpserver/server.go). Un agente che crea centinaia di link dovrebbe usare POST /v1/workspaces/{id}/links/bulk tramite l'API, come in importazione in blocco da un Google Sheet.

MCP remoto. Sarebbe un endpoint ospitato con OAuth, così un connector di Claude potrebbe raggiungere Elido senza un processo locale. È pianificato, non costruito, e il catalogo delle integrazioni nella dashboard elenca solo il server locale. Per ora usa quello.

Deriva del protocollo. Il server dichiara 2024-11-05 mentre la revisione attuale della specifica è 2026-07-28. Non l'abbiamo testato con ogni release dei client, quindi controlla lo stato del server nel tuo client dopo un aggiornamento.

Dove va da qui

Le lacune sopra sono nel backlog: pubblicare il pacchetto, correggere generate_qr, aggiungere Streamable HTTP e l'endpoint remoto, aggiungere più tool (update, delete, dettagli geografici) e l'attribuzione di audit per chiave. Per un'altra strada verso la stessa idea di agente, vedi la guida a Gemini e la guida a ChatGPT; per l'igiene delle chiavi, permessi delle chiavi API per gli strumenti di link.

Correlati sul blog

• Permessi delle chiavi API per gli strumenti di link - ruoli, privilegio minimo e rotazione.

• Importare in blocco link corti da un Google Sheet - la strada giusta per centinaia di link.

• Shortener di URL con Gemini - dove funzionano le chiamate ai tool in Gemini.

• Shortener di URL con ChatGPT - cosa funziona e cosa finge.

• Link corti come Terraform - gestione dei link in stile infrastruttura.

• Rate limit e idempotenza dell'API di uno URL shortener - come si comportano i limiti per i client.

• Marius