---
title: MCP
description: >-
  Serveur MCP distant à l'adresse https://api.linkdash.dev/mcp. Connectez-vous
  via OAuth depuis Claude, ChatGPT, Cursor et Codex, ou utilisez une clé API.
sidebar:
  label: MCP
  order: 5
---
Serveur MCP distant à l'adresse `https://api.linkdash.dev/mcp`. Ajoutez l'URL à votre client et connectez-vous avec votre compte Linkdash. Pour les agents qui s'exécutent sans personne devant un navigateur, utilisez plutôt une [clé API](#automation-and-headless-agents). Version Markdown brut : [mcp.md](https://linkdash.dev/mcp.md).

## Connexion

Indiquez au client uniquement l'URL `https://api.linkdash.dev/mcp`. Le client ouvre une page de connexion Linkdash, puis un écran de consentement qui affiche le nom de l'application et le site vers lequel elle vous renvoie. Autorisez l'accès : le client reçoit alors un jeton pour votre compte.

- **claude.ai et Claude Desktop :** ouvrez [Linkdash dans l'annuaire des connecteurs](https://claude.ai/directory/linkdash) (ou Customize → Connectors, puis recherchez Linkdash) et cliquez sur **Connect**.
- **ChatGPT :** Linkdash sera bientôt référencé dans l'annuaire des plugins ChatGPT. En attendant, dans [Plugins](https://chatgpt.com/plugins), choisissez **+** → **Add custom MCP server**, saisissez l'URL ci-dessus et choisissez OAuth.
- **Claude Code :** `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp`, puis `claude mcp login linkdash` (ou `/mcp` dans une session).
- **Cursor :** [Add to Cursor](https://cursor.com/install-mcp?name=linkdash&config=eyJ1cmwiOiJodHRwczovL2FwaS5saW5rZGFzaC5kZXYvbWNwIn0%3D) l'installe en un clic. Connectez-vous ensuite lorsque Cursor vous le demande. Vous pouvez aussi ajouter le serveur dans `mcp.json` avec `"url"` et sans `headers`.
- **Codex :** `codex mcp add linkdash --url https://api.linkdash.dev/mcp`, puis `codex mcp login linkdash`.

L'application obtient le même accès qu'une clé API. Les applications connectées sont listées dans [Tableau de bord → Clés API](https://linkdash.dev/dashboard/keys), où **Déconnecter** révoque leur accès immédiatement.

## Automatisation et agents headless

La connexion nécessite une personne devant un navigateur. Pour les jobs de CI, les agents planifiés, les serveurs et le code qui appelle MCP directement, envoyez plutôt une [clé API](https://linkdash.dev/dashboard/keys) : `Authorization: Bearer ldash_...`. Ce sont les mêmes clés que pour l'[API HTTP](/fr/api).

**Cursor** (`~/.cursor/mcp.json` ou `.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"` (en JSON, ajoutez `"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"`

En local : l'URL `.site` de Convex suivie de `/mcp`.

## Fichiers

N'envoyez pas les octets d'un fichier dans le JSON MCP. Générez une URL (`{uploadUrl,storageId}`), envoyez le fichier par PUT depuis l'hôte, puis créez le lien :

```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}'
```

Outils MCP : `files_upload_url` renvoie `{uploadUrl,storageId}` → l'hôte envoie le fichier par PUT vers `uploadUrl` → `links_create` avec ce `storageId`. Carte d'aperçu facultative : `previewName`, `previewDescription`, `previewImageStorageId` (même procédure d'upload). Le paramètre facultatif `maxOpenings` met le lien en pause après le nombre d'ouvertures indiqué. `links_update` permet d'augmenter cette limite ou de passer `clearMaxOpenings`. N'affichez pas `uploadUrl` à l'utilisateur.

## Outils

| 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` (sans id) | `GET /shares` | `links_shares` (sans `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 ou editor) |
| `links_unlock` | `{ id, variant?, password?, variantPassword? }` → la cible ; déverrouille une variante protégée par mot de passe pour un éditeur pendant 30 minutes |
| `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 par l'hôte après génération de 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_*` |

## Dossiers

Un dossier est un lien qui liste les éléments que vous y placez. Consultez [Dossiers](/fr/folders) pour le fonctionnement détaillé.

| Outil | Entrée |
| --- | --- |
| `links_create` | `{ kind: "folder", name, … }` crée un dossier ; toute création accepte `folder` (slug) et `folderDomain?` pour créer l'élément dans un dossier. La réponse inclut `folder` |
| `links_list` | Une page, `{ items, cursor }` (`limit` de 1 à 100, 50 par défaut ; renvoyez `cursor` jusqu'à ce qu'il vaille `null`). `q` recherche des mots ; `folder: "<slug>"` liste le contenu direct d'un dossier ; `folder: "root"` liste le niveau racine ; `kind` accepte en plus `folder`. Les lignes contiennent `folder`, et les lignes de dossier contiennent `items` |
| `links_move` | `{ id, domain?, folder: string \| null, folderDomain? }` → `{ id, folder }` |
| `links_copy` | `{ id, domain? }` → `{ id, url, access, kind, folder }` (même accès, nouvelle URL de partage, aucune personne) |
| `links_delete` | `contents?: "keep" \| "delete"` pour les dossiers (`keep` par défaut) |

`links_export` / `links_import` ajoutent les colonnes `folder` et `access`, et les lignes dont le `kind` vaut `folder` créent des dossiers.

## Accès et partage

Les nouveaux liens et dossiers sont restreints : `url` vaut `https://linkdash.dev/s/<token>`, que seuls vous et les personnes avec qui vous le partagez pouvez ouvrir. Passez `access` à `links_create` ou `links_update` : `restricted` (par défaut), `link` (toute personne disposant de l'URL de partage) ou `public` (tout le monde, via l'URL courte). Demandez `access: "public"` lorsque le lien sera publié publiquement. Consultez [Partage et accès](/fr/sharing).

| Outil | Entrée |
| --- | --- |
| `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? }` → une page de tout ce que vous avez partagé, `{ items, cursor }`, chaque élément avec `people` |
| `links_shared` | `{ limit?, cursor? }` → une page des éléments que d'autres personnes ont partagés avec vous, `{ items, cursor }`, avec l'`url` pour ouvrir chacun d'eux |
| `links_leave` | `{ id }` (l'`_id` ou l'URL de partage issus de `links_shared`) → `{ _id, left: true }` |
| `links_update` | `access?` modifie qui peut l'ouvrir ; `resetShareLink: true` génère une nouvelle URL de partage (l'ancienne cesse de fonctionner) |

Dans chaque réponse, `url` est l'URL de partage, sauf si le lien est public : c'est alors l'URL courte. Un partage, une annulation de partage, un changement d'accès et une réinitialisation comptent chacun pour un événement ; quitter un partage n'en compte pas.

## Variantes

Chaque lien est un conteneur d'une ou plusieurs **variantes** : un contenu (`url` | `file` | `text`) avec ses propres restrictions d'accès (`password`, `starts`, `expires`, `maxOpenings`, mise en pause), un `weight` et des conditions facultatives sur le visiteur, `when`. Sans `variants`, un lien possède une seule variante nommée `main`. Les restrictions du lien priment sur celles des variantes. Un visiteur reçoit une seule variante : les variantes dont la condition `when` correspond forment le pool (à défaut, les variantes sans condition), puis une variante est tirée selon les poids ; `sticky` (`true` par défaut) maintient un visiteur récurrent sur la même variante, et `restartSplit` relance la répartition. Le `kind` d'un lien vaut `group` lorsqu'il comporte plusieurs variantes ; son `status` vaut `mixed` lorsque les variantes diffèrent. Un lien peut avoir au maximum 20 variantes. Formats : [API HTTP](/fr/api#variantes).

`links_create` accepte `variants: [{ name, url | text | storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }]` à la place de la forme abrégée, ainsi que `sticky` et `forwardParams`. `links_update` accepte `sticky`, `forwardParams` et `restartSplit`. `links_list` filtre sur `kind` (ajoute `group`) et `status` (ajoute `mixed`). `links_stats` renvoie les totaux par `variants`. `links_export` / `links_import` utilisent le CSV des variantes (une ligne par variante).

| Outil | Entrée |
| --- | --- |
| `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? }` |

Clés de `when` : `countries`, `devices`, `os`, `browsers`, `languages`, `referrerHosts` (tableaux de chaînes ; chaque clé définie doit correspondre), ainsi que `params`.

**Règles sur les paramètres de requête.** `when.params` est un tableau de 10 règles au maximum portant sur la query string du visiteur ; toutes les règles doivent être satisfaites : `{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] }`. `op` : `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` est une liste séparée par des `|`) | `exists` | `missing` (pas de `value` pour ces deux derniers). Les clés sont sensibles à la casse et les valeurs sont comparées à l'identique. Les valeurs des paramètres ne sont jamais stockées dans les statistiques.

**Transmission des paramètres de requête.** `forwardParams` (booléen sur `links_create` / `links_update`, `false` par défaut) ajoute l'intégralité de la query string du visiteur aux variantes de type URL ; les valeurs du visiteur remplacent les valeurs enregistrées, `utm` compris. Uniquement pour les variantes de type URL. Il s'agit de routage, pas de contrôle d'accès.

`auth create` / `auth login` / `auth logout` ne sont pas des outils MCP. Correspondances : [api.md](https://linkdash.dev/api.md).
