Serveur MCP Elido pour Claude Desktop, Cursor et Claude Code

Le serveur MCP Elido est un petit processus Node qui permet à Claude Desktop, Cursor ou Claude Code de créer des liens courts, de les lister et de lire des séries temporelles de clics depuis un chat. Il vit dans le monorepo sous packages/mcp-server, parle MCP via stdio et s'adresse à la même API REST que tout le reste.

Une correction d'emblée, car une version antérieure de ce guide s'était trompée : le paquet n'est pas sur npm et pas encore public. Au 2026-11-11, npm view @elido/mcp-server renvoie un 404 ; une publication publique arrive bientôt. D'ici là, vous l'exécutez depuis une compilation locale. Tout ce qui suit a été vérifié dans le code de packages/mcp-server et services/api-core.

Ce qu'est MCP

Le Model Context Protocol est un standard ouvert qui permet à un client d'IA d'appeler des outils situés hors du modèle. Le client démarre un serveur ou s'y connecte, lui demande une liste d'outils et envoie les appels d'outils sous forme de messages JSON-RPC. Le serveur fait le travail et renvoie du texte que le modèle lit. Le modèle ne détient jamais votre clé d'API ; c'est le serveur qui la détient.

La spécification définit deux transports, stdio pour les processus locaux et Streamable HTTP pour les distants (spécification MCP, dernière révision 2026-07-28, consultée le 2026-10-25). Le serveur Elido n'implémente que stdio.

Ce que fait le serveur

Il est écrit à la main, sans le @modelcontextprotocol/sdk officiel, pour rester sans dépendances. Dans src/index.ts, il répond à quatre choses : initialize (en indiquant la version de protocole 2024-11-05), tools/list, tools/call et la notification notifications/initialized. Tout le reste reçoit une erreur "method not found". Il n'y a ni ressources, ni prompts, ni gestionnaire ping.

Chaque appel d'outil devient une requête REST authentifiée vers ELIDO_API_BASE (par défaut https://api.elido.app) avec Authorization: Bearer <key> et l'en-tête User-Agent: elido-mcp-server/0.1.0. Les appels échoués reviennent sous forme d'erreur incluant le statut HTTP et les 400 premiers caractères de la réponse.

À propos de generate_qr : api-core sert un POST /v1/qr/generate public et un design par lien à GET /v1/workspaces/{id}/links/{link_id}/qr, mais rien au chemin appelé par l'outil. Tant que ce n'est pas réconcilié, je ne bâtirais pas de workflow dessus. C'est dans le backlog.

Le compiler et obtenir une clé d'API

Le monorepo est privé : les étapes ci-dessous valent dès que vous disposez des sources du paquet (une publication publique arrive bientôt). Compilez le paquet :

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

Cela produit packages/mcp-server/dist/index.js. Il vous faut Node 20 ou plus récent (engines dans son package.json).

Pour la clé, ouvrez Dashboard, puis API keys (/dashboard/api-keys), nommez la clé d'après l'agent et choisissez un rôle. Le formulaire propose viewer, editor et admin, et editor est la valeur par défaut. Les clés Elido portent un rôle d'espace de travail, pas des portées par outil. Une clé viewer est l'option en lecture seule : elle peut lister et lire l'analytique, et l'API refuse create_link. Définissez une expiration si la clé sert à un essai. Copiez la clé quand elle s'affiche, et gardez-la hors du contrôle de version.

Configurer Claude Desktop

Claude Desktop lit claude_desktop_config.json. L'emplacement de la config et l'onglet de réglages Developer sont décrits dans la documentation MCP (connecter des serveurs locaux, consulté le 2026-10-25). Sur macOS, le fichier est ~/Library/Application Support/Claude/claude_desktop_config.json, et sur 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"
      }
    }
  }
}

Utilisez un chemin absolu. ELIDO_WORKSPACE_ID n'est facultatif que si la clé voit exactement un espace de travail ; le serveur appelle alors GET /v1/workspaces une fois et met l'id en cache. Avec deux espaces de travail ou plus, il lève une erreur qui vous demande de définir la variable : définissez-la donc dès le départ.

Redémarrez Claude Desktop après l'enregistrement. Si le serveur n'apparaît pas, exécutez d'abord la même commande dans un terminal. Une clé manquante n'arrête pas le processus, il affiche un avertissement sur stderr et chaque appel d'outil échoue ensuite.

Configurer Cursor et Claude Code

Cursor lit la même forme mcpServers depuis .cursor/mcp.json dans un projet, ou depuis ~/.cursor/mcp.json pour tous les projets (documentation MCP de Cursor, consultée le 2026-10-25). Collez le bloc ci-dessus, ajoutez le fichier à .gitignore puisqu'il contient une clé active, et vérifiez le serveur dans les réglages MCP de Cursor.

Claude Code ajoute un serveur stdio depuis la ligne de commande (documentation MCP de Claude Code, consultée le 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

Les clés dans un fichier de config sont en clair. Sur une machine partagée, donnez à chaque personne sa propre clé pour que la piste d'audit ait un sens.

Deux sessions, avec les vraies formes de requête

Ce sont des conversations illustratives, pas des enregistrements, et les chiffres sont inventés. Les arguments d'outil et les champs de résultat correspondent au code.

Raccourcir un lien de campagne. Vous demandez à Claude de raccourcir https://shop.example.com/spring avec le slug spring et le tag spring. Il appelle create_link avec destination_url, slug, title et tags. Comme aucun domain_id n'a été passé, le serveur récupère d'abord GET /v1/workspaces/{id}/domains et utilise le premier renvoyé. Si votre espace de travail a plusieurs domaines, passez vous-même domain_id. L'API répond avec l'enregistrement du lien incluant short_url, et Claude l'insère dans le brouillon. Si le slug est pris, l'API renvoie 409 "slug already exists for this domain", et Claude peut en choisir un autre.

Lire les clics de la semaine dernière. Vous demandez les clics quotidiens d'un lien, à l'heure de Berlin. Claude appelle query_analytics avec link_id, from, to, interval: "day" et tz: "Europe/Berlin". Les dates sont au format YYYY-MM-DD, et l'API rejette une plage où from n'est pas antérieur à to : passez donc le lendemain de votre dernier jour comme to. Si vous les omettez, la plage est les 30 derniers jours. Le résultat est {"items": [{"ts": "...", "count": 312}, ...]}. Il n'y a pas de champ total, demandez donc à Claude de sommer les compteurs. Des clics uniquement : aucune ventilation par pays, appareil ou référent ne passe par cet outil.

Sécurité et limites

Des rôles, pas des portées. Choisissez le rôle le plus bas qui fait le travail. Viewer pour les agents de reporting, editor pour ceux qui créent des liens, admin seulement avec une raison précise.

Ce qui quitte votre machine. Le serveur envoie des requêtes à votre base d'API Elido et nulle part ailleurs. Ce que votre client d'IA envoie à son propre fournisseur relève de la politique de ce fournisseur.

Piste d'audit. La création d'une clé émet un événement d'audit api_key.created, et la création d'un lien émet link.created. Je n'ai pas vérifié comment un événement est attribué à une clé individuelle : ne comptez donc pas sur le journal d'audit pour distinguer deux agents. Donnez à chacun sa propre clé et surveillez la liste des clés.

Limites de débit. Les appels comptent dans la limite de l'espace de travail : 10 requêtes par seconde en Free, 30 en Pro et 100 en Business, avec des tolérances de rafale de 20, 60 et 200 (services/api-core/internal/httpserver/server.go). Un agent qui crée des centaines de liens doit utiliser POST /v1/workspaces/{id}/links/bulk via l'API, comme dans l'import en masse depuis Google Sheets.

MCP distant. Il s'agirait d'un point de terminaison hébergé avec OAuth, pour qu'un connecteur Claude puisse atteindre Elido sans processus local. Il est prévu, pas construit, et le catalogue d'intégrations du tableau de bord ne liste que le serveur local. Utilisez-le pour l'instant.

Dérive du protocole. Le serveur déclare 2024-11-05 alors que la révision actuelle de la spécification est 2026-07-28. Nous ne l'avons pas testé avec chaque version de client : vérifiez donc le statut du serveur dans votre client après une mise à jour.

La suite

Les lacunes ci-dessus sont dans le backlog : publier le paquet, corriger generate_qr, ajouter Streamable HTTP et l'endpoint distant, ajouter d'autres outils (mise à jour, suppression, ventilations géographiques) et l'attribution d'audit par clé. Pour une autre voie vers la même idée d'agent, voir le guide Gemini et le guide ChatGPT ; pour l'hygiène des clés, permissions des clés d'API pour les outils de liens.

À lire aussi sur le blog

• Permissions des clés d'API pour les outils de liens - rôles, moindre privilège et rotation.

• Importer en masse des liens courts depuis Google Sheets - la bonne voie pour des centaines de liens.

• Raccourcisseur d'URL Gemini - où les appels d'outils fonctionnent dans Gemini.

• Raccourcisseur d'URL ChatGPT - ce qui marche et ce qui fait semblant.

• Liens courts en Terraform - gestion de liens façon infrastructure.

• Limites de débit et idempotence de l'API du raccourcisseur d'URL - comment les limites se comportent pour les clients.

• Marius