Skip to main content
Le serveur zelinqa-mcp est disponible sur PyPI. Il tourne localement chez vous en stdio, utilise le SDK Python et appelle l’API publique. Il ne contient pas le moteur et n’accède pas directement à la base de données. Python 3.11+ et une clé runtime pour un domaine publié sont nécessaires.

Démarrer avec MCP

Configurez votre hôte, lancez une conversation et vérifiez les outils disponibles.

​
Installer dans votre outil

Préparez un domaine publié, une clé runtime et uv (uvx). Python 3.11+ est nécessaire.
Avec la clé déjà disponible dans la variable d’environnement ZELINQA_API_KEY de votre terminal :
Relancez Claude Code, puis utilisez /mcp pour vérifier la connexion. Guide officiel.
La clé donne accès à votre domaine. Les commandes CLI enregistrent sa valeur dans la configuration locale de l’hôte. Gardez ces fichiers privés, ne les commitez pas et ne transmettez jamais la clé dans une conversation. Utilisez un hôte de confiance.
Le serveur est local, en stdio : il n’y a pas d’URL MCP HTTP à coller. uvx installe le paquet depuis PyPI et le lance ; ce processus appelle ensuite l’API Zelinqa par HTTPS. Si l’hôte ne trouve pas uvx, utilisez son chemin absolu dans la configuration.
Pour mettre à jour une installation existante ou choisir entre @latest et une version fixe, consultez Versions et mise à jour MCP.

​
Versions

Une nouvelle publication ne met pas à jour un serveur MCP déjà lancé. Le comportement dépend de la commande enregistrée dans votre hôte : Dans la configuration JSON de l’hôte, gardez "command": "uvx" et remplacez seulement "args": ["zelinqa-mcp"] par "args": ["zelinqa-mcp@latest"] ou "args": ["zelinqa-mcp@1.0.1"]. Conservez les variables d’environnement et les autres options. Privilégiez une version validée en production. Le numéro 1.0.1 est un exemple de version fixe, pas une promesse de dernière version. Pour demander la dernière version et vérifier celle que cette commande lancerait, sans clé ni appel à l’API Zelinqa :
Pour vérifier une version fixe :
Ces commandes peuvent télécharger un paquet ; elles ne changent pas la configuration de l’hôte ni son processus déjà lancé. Si vous avez choisi une installation persistante avec uv tool install et lancez directement zelinqa-mcp, utilisez :
Cette dernière méthode respecte la contrainte d’installation. Pour changer une version exacte, réinstallez avec uv tool install "zelinqa-mcp==1.0.1". Voir les règles de version de uv.

​
Vérifier après une mise à jour

  1. Lisez les changements du serveur, puis mettez à jour la commande de l’hôte si nécessaire.
  2. Redémarrez son serveur MCP ou quittez puis rouvrez l’hôte. La nouvelle version ne remplace pas le processus en cours à chaud.
  3. Vérifiez les sept outils métier puis jouez une conversation de test sur un domaine de démonstration : question, réponse, zelinqa_status et arrêt. Ce test utilise vos quotas.
Le redémarrage efface les handles locaux. Pour reprendre une session, conservez son identifiant et son nom puis configurez les deux variables ZELINQA_SESSION_ID et ZELINQA_CONVERSATION avant le redémarrage ; voir la reprise. Ne comptez pas sur une reprise automatique.
Mettre à jour le SDK Python de votre application ne met pas à jour le MCP : son environnement isolé installe les dépendances déclarées par sa propre version.

​
Outils métier par défaut

L’hôte nomme une conversation ; le serveur conserve localement les identifiants de session, de question et de décision. Le modèle n’a pas à les inventer. Pour une question ouverte, zelinqa_next_question exige les mots de la personne dans user_text. Pour une question à choix, envoyez les libellés exacts dans choice_labels ; une semi-ouverte peut aussi porter free_text. refused ou asked_no_answer peuvent être envoyés sans texte. N’inventez pas de réponse. zelinqa_adjust n’est destiné qu’aux données vérifiées, pas à des suppositions. La vue renvoyée contient les questions candidates avec leur rang, leur texte et leurs choix, ainsi que la progression et les avertissements. Une limite de tours atteinte n’implique pas que l’objectif soit atteint. Le serveur ne renvoie pas les mécanismes internes de classement.

​
Transport, sécurité et reprise

  • Un processus stdio doit être réservé à un hôte/utilisateur de confiance ; l’hébergement HTTP n’est pas activé.
  • La clé ZELINQA_API_KEY reste dans l’environnement de l’hôte, jamais dans une conversation ou un dépôt. Elle est limitée à un domaine et au scope runtime.
  • Les noms de conversations et jusqu’à 128 handles sont conservés dans ce processus, sans éviction silencieuse. zelinqa_forget libère un handle.
  • Pour reprendre après redémarrage, l’hôte doit conserver l’identifiant de session hors du modèle et fournir les deux variables ZELINQA_SESSION_ID et ZELINQA_CONVERSATION. Cette dernière doit être exactement le nom transmis à zelinqa_start ou zelinqa_next_question (par exemple demo-42). Sinon, ce nom peut créer une nouvelle session au lieu de reprendre l’ancienne. Une session créée seulement dans un hôte de bureau n’est pas reprise automatiquement.
  • Sérialisez les mutations d’une même conversation. Après une coupure ou un conflit, appelez zelinqa_status avant de décider s’il faut renvoyer une réponse.
Le mode --advanced expose six outils proches de l’API brute et leurs identifiants techniques. La configuration des questions se fait dans Studio ou via le client de configuration du SDK, pas avec les outils MCP métier. Le serveur publie la ressource zelinqa://guide, le prompt zelinqa_integration_check et un skill portable. Les lire ne crée pas de session et n’appelle pas l’API. Consultez le dépôt public pour les exemples d’hôtes et les détails du mode avancé.