---
title: MCP
description: >-
  MCP remoto su https://api.linkdash.dev/mcp. Accedi con OAuth da Claude,
  ChatGPT, Cursor e Codex, oppure usa una chiave API.
sidebar:
  label: MCP
  order: 5
---
MCP remoto su `https://api.linkdash.dev/mcp`. Aggiungi l'URL al tuo client e accedi con il tuo account Linkdash. Per gli agenti che girano senza una persona davanti a un browser, usa invece una [chiave API](#automation-and-headless-agents). Markdown semplice: [mcp.md](https://linkdash.dev/mcp.md).

## Connessione

Al client passa solo l'URL `https://api.linkdash.dev/mcp`. Si apre l'accesso a Linkdash e poi una schermata di consenso che indica il nome dell'app e il sito a cui ritorna. Se concedi l'autorizzazione, il client riceve un token per il tuo account.

- **claude.ai e Claude Desktop:** apri [Linkdash nella directory dei connettori](https://claude.ai/directory/linkdash) (oppure Customize → Connectors e cerca Linkdash) e clicca su **Connect**.
- **ChatGPT:** a breve arriverà una scheda nella directory dei plugin di ChatGPT. Nel frattempo, in [Plugins](https://chatgpt.com/plugins), scegli **+** → **Add custom MCP server**, inserisci l'URL qui sopra e scegli OAuth.
- **Claude Code:** `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp`, poi `claude mcp login linkdash` (oppure `/mcp` in una sessione).
- **Cursor:** [Add to Cursor](https://cursor.com/install-mcp?name=linkdash&config=eyJ1cmwiOiJodHRwczovL2FwaS5saW5rZGFzaC5kZXYvbWNwIn0%3D) lo installa con un clic, poi accedi quando Cursor te lo chiede. In alternativa, aggiungi il server a `mcp.json` con `"url"` e senza `headers`.
- **Codex:** `codex mcp add linkdash --url https://api.linkdash.dev/mcp`, poi `codex mcp login linkdash`.

L'app ottiene lo stesso accesso di una chiave API. Le app connesse sono elencate in [Dashboard → Chiavi API](https://linkdash.dev/dashboard/keys), dove **Scollega** le revoca immediatamente.

## Automazione e agenti headless

Per accedere serve una persona davanti a un browser. Per job di CI, agenti pianificati, server e codice che chiama MCP direttamente, invia invece una [chiave API](https://linkdash.dev/dashboard/keys): `Authorization: Bearer ldash_...`, le stesse chiavi dell'[API HTTP](/it/api).

**Cursor** (`~/.cursor/mcp.json` o `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "linkdash": {
      "url": "https://api.linkdash.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LINKDASH_API_KEY}" }
    }
  }
}
```

**Claude Code:** `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp --header "Authorization: Bearer $LINKDASH_API_KEY"` (il JSON richiede `"type": "http"`).

**Codex:** `codex mcp add linkdash --url https://api.linkdash.dev/mcp --bearer-token-env-var LINKDASH_API_KEY`

**OpenCode:** `opencode mcp add linkdash --url https://api.linkdash.dev/mcp --header Authorization="Bearer $LINKDASH_API_KEY"`

In locale: URL `.site` di Convex + `/mcp`.

## File

Non inviare byte tramite il JSON di MCP. Genera un URL (`{uploadUrl,storageId}`), fai il PUT del file dall'host, poi crea il link:

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"clip.mp4","fileType":"video/mp4","fileSize":12345}'
```

Tool MCP: `files_upload_url` restituisce `{uploadUrl,storageId}` → l'host fa il PUT su `uploadUrl` → `links_create` con quello `storageId`. Scheda di anteprima opzionale: `previewName`, `previewDescription`, `previewImageStorageId` (stesso upload). Il parametro opzionale `maxOpenings` mette in pausa il link dopo quel numero di aperture; `links_update` può aumentarlo o passare `clearMaxOpenings`. Non mostrare `uploadUrl` all'utente.

## Tool

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links` (`?q=&tag=&kind=&status=&folder=&limit=&cursor=`) | `links_list` |
| `links get <id>` | `GET /links/:id` (`?domain=`) | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id` (`?contents=keep\|delete`) | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares` (senza id) | `GET /shares` | `links_shares` (senza `id`) |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links_share_role` | `{ id, email, role }` → `{ id, email, role }` (viewer o editor) |
| `links_unlock` | `{ id, variant?, password?, variantPassword? }` → la destinazione; sblocca per 30 minuti una variante protetta da password per un editor |
| `links_activity` | `{ id, limit?, cursor? }` → `{ items: [{ action, detail?, actor, _creationTime }], cursor }` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update` (`resetShareLink: true`) |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| (PUT dall'host dopo aver generato l'URL) | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`, `GET/DELETE /webhooks/:id`, `POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`, `GET /domains/:host/connect`, `POST /domains/:host/verify`, `DELETE /domains/:host` | `domains_*` |

## Cartelle

Una cartella è un link che elenca gli elementi che ci metti dentro. Per il modello, vedi [Cartelle](/it/folders).

| Tool | Input |
| --- | --- |
| `links_create` | `{ kind: "folder", name, … }` crea una cartella; qualsiasi create accetta `folder` (slug) e `folderDomain?` per creare l'elemento al suo interno. La risposta include `folder` |
| `links_list` | Una pagina, `{ items, cursor }` (`limit` 1-100, default 50; ripassa `cursor` finché non è `null`). `q` cerca per parole; `folder: "<slug>"` elenca ciò che si trova direttamente al suo interno; `folder: "root"` elenca il livello principale; `kind` aggiunge `folder`. Le righe contengono `folder` e le righe delle cartelle contengono `items` |
| `links_move` | `{ id, domain?, folder: string \| null, folderDomain? }` → `{ id, folder }` |
| `links_copy` | `{ id, domain? }` → `{ id, url, access, kind, folder }` (stesso accesso, nuovo URL di condivisione, nessuna persona) |
| `links_delete` | `contents?: "keep" \| "delete"` per le cartelle (default `keep`) |

`links_export` / `links_import` aggiungono le colonne `folder` e `access`, e le righe con `kind` `folder` creano cartelle.

## Accesso e condivisione

I nuovi link e le nuove cartelle sono riservati: `url` è `https://linkdash.dev/s/<token>`, che possono aprire solo tu e le persone con cui lo condividi. Passa `access` su `links_create` o `links_update`: `restricted` (default), `link` (chiunque abbia l'URL di condivisione) o `public` (chiunque, tramite lo short URL). Richiedi `access: "public"` quando il link verrà pubblicato. Vedi [Condivisione e accesso](/it/sharing).

| Tool | Input |
| --- | --- |
| `links_share` | `{ id, domain?, emails: string[] (1–50), role? }` → `{ id, url, access, invited, alreadyShared }` |
| `links_unshare` | `{ id, domain?, email }` → `{ id, email, removed: true }` |
| `links_shares` | `{ id, domain? }` → `{ id, access, url, people: [{ email, role, accepted, invitedAt, viaFolder? }] }`; `{ limit?, cursor? }` → una pagina di tutto ciò che hai condiviso, `{ items, cursor }`, ciascuno con `people` |
| `links_shared` | `{ limit?, cursor? }` → una pagina degli elementi che altre persone hanno condiviso con te, `{ items, cursor }`, con l'`url` per aprire ciascuno |
| `links_leave` | `{ id }` (l'`_id` o l'URL di condivisione da `links_shared`) → `{ _id, left: true }` |
| `links_update` | `access?` cambia chi può aprirlo; `resetShareLink: true` genera un nuovo URL di condivisione (quello vecchio smette di funzionare) |

In ogni risposta, `url` è l'URL di condivisione, a meno che il link non sia pubblico: in quel caso è lo short URL. Condivisione, revoca della condivisione, modifiche all'accesso e reset contano ciascuno come un evento; uscire da una condivisione no.

## Varianti

Ogni link è un contenitore di una o più **varianti**: un contenuto (`url` | `file` | `text`) più un proprio gate (`password`, `starts`, `expires`, `maxOpenings`, in pausa), un `weight` e condizioni opzionali sul visitatore `when`. Senza `variants`, un link ha una sola variante chiamata `main`. Il gate del link ha la precedenza su quelli delle varianti. Ogni visitatore riceve una sola variante: le varianti il cui `when` corrisponde formano il pool (altrimenti quelle senza condizioni), poi si fa una scelta pesata; `sticky` (default `true`) mantiene un visitatore di ritorno sulla stessa variante e `restartSplit` rimescola la distribuzione. Il `kind` del link è `group` quando ci sono più varianti; lo `status` del link è `mixed` quando le varianti differiscono. Massimo 20 varianti per link. Strutture: [API HTTP](/it/api#varianti).

`links_create` accetta `variants: [{ name, url | text | storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }]` al posto della forma abbreviata, più `sticky` e `forwardParams`. `links_update` accetta `sticky`, `forwardParams` e `restartSplit`. `links_list` filtra per `kind` (aggiunge `group`) e `status` (aggiunge `mixed`). `links_stats` restituisce i totali di `variants`. `links_export` / `links_import` usano il CSV delle varianti (una riga per variante).

| Tool | Input |
| --- | --- |
| `variants_list` | `{ id, domain? }` |
| `variants_add` | `{ id, domain?, name, url \| text \| storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }` |
| `variants_update` | `{ id, name, domain?, newName?, url?, text?, storageId?, password?, clearPassword?, starts?, clearStarts?, expires?, clearExpires?, maxOpenings?, clearMaxOpenings?, status?, weight?, when?, clearWhen?, utm? }` |
| `variants_remove` | `{ id, name, domain? }` |

Chiavi di `when`: `countries`, `devices`, `os`, `browsers`, `languages`, `referrerHosts` (array di stringhe; ogni chiave impostata deve corrispondere), più `params`.

**Regole sui parametri di query.** `when.params` è un array di massimo 10 regole sulla query string del visitatore, e ogni regola deve essere soddisfatta: `{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] }`. `op`: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` è un elenco separato da `|`) | `exists` | `missing` (niente `value` per gli ultimi due). Le chiavi distinguono maiuscole e minuscole, i valori vengono confrontati in modo esatto. I valori dei parametri non vengono mai salvati nelle analytics.

**Inoltro dei parametri di query.** `forwardParams` (booleano su `links_create` / `links_update`, default `false`) aggiunge l'intera query string del visitatore alle varianti URL; i valori del visitatore sovrascrivono quelli salvati, `utm` compreso. Solo per le varianti URL. Serve al routing, non al controllo degli accessi.

`auth create` / `auth login` / `auth logout` non sono tool MCP. Mappatura: [api.md](https://linkdash.dev/api.md).
