> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Serveur MCP
> Brancher Zelinqa à un hôte MCP avec des outils de conversation métier.
Le [serveur `zelinqa-mcp`](https://pypi.org/project/zelinqa-mcp/) est disponible sur PyPI. Il tourne localement chez vous en **stdio**, utilise le [SDK Python](/fr/integrations/sdk) 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.
```text theme={null}
Hôte MCP → zelinqa-mcp → SDK Python → api.zelinqa.ai
```
Configurez votre hôte, lancez une conversation et vérifiez les outils disponibles.
## Installer dans votre outil
Préparez un [domaine publié](/fr/quickstart/configure-domain), une clé [`runtime`](/fr/quickstart/generate-api-key) et [uv](https://docs.astral.sh/uv/getting-started/installation/) (`uvx`). Python 3.11+ est nécessaire.
Avec la clé déjà disponible dans la variable d'environnement `ZELINQA_API_KEY` de votre terminal :
```bash theme={null}
claude mcp add --scope user \
--env ZELINQA_API_KEY="$ZELINQA_API_KEY" \
--transport stdio zelinqa -- uvx zelinqa-mcp
claude mcp list
```
Relancez Claude Code, puis utilisez `/mcp` pour vérifier la connexion. [Guide officiel](https://code.claude.com/docs/en/mcp).
Avec la clé déjà disponible dans la variable d'environnement `ZELINQA_API_KEY` de votre terminal :
```bash theme={null}
codex mcp add zelinqa \
--env ZELINQA_API_KEY="$ZELINQA_API_KEY" \
-- uvx zelinqa-mcp
codex mcp list
```
Rouvrez votre session Codex après l'ajout. [Guide officiel](https://developers.openai.com/codex/mcp).
Ajoutez cette entrée à votre configuration MCP **personnelle**, `~/.cursor/mcp.json`, sans effacer les serveurs existants.
```json theme={null}
{
"mcpServers": {
"zelinqa": {
"command": "uvx",
"args": ["zelinqa-mcp"],
"env": {
"ZELINQA_API_KEY": "VOTRE_CLE_RUNTIME"
}
}
}
}
```
Remplacez la valeur d'exemple et vérifiez que le serveur est activé dans les réglages MCP de Cursor.
Ouvrez **Settings → Developer → Edit Config** et ajoutez ce serveur à `mcpServers`, sans effacer les autres entrées :
```json theme={null}
{
"mcpServers": {
"zelinqa": {
"command": "uvx",
"args": ["zelinqa-mcp"],
"env": {
"ZELINQA_API_KEY": "VOTRE_CLE_RUNTIME"
}
}
}
}
```
Remplacez la valeur d'exemple, enregistrez, puis redémarrez complètement Claude Desktop.
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](/fr/integrations/mcp#versions).
## 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 :
| Commande | Comportement au démarrage |
| - | - |
| `uvx zelinqa-mcp` | Peut réutiliser une version en cache ou installée avec `uv tool install` ; ne garantit pas la dernière version |
| `uvx zelinqa-mcp@latest` | Recherche la dernière version à chaque nouveau lancement ; pratique pour essayer, peut inclure une version majeure |
| `uvx zelinqa-mcp@1.0.1` | Utilise cette version précise du serveur ; changez le numéro après validation d'une mise à jour |
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 :
```bash theme={null}
uvx zelinqa-mcp@latest --version
```
Pour vérifier une version fixe :
```bash theme={null}
uvx zelinqa-mcp@1.0.1 --version
```
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 :
```bash theme={null}
uv tool upgrade zelinqa-mcp
zelinqa-mcp --version
```
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](https://docs.astral.sh/uv/concepts/tools/#tool-versions).
### Vérifier après une mise à jour
1. Lisez les [changements du serveur](https://github.com/Zelinqa/zelinqa-mcp/blob/main/CHANGELOG.md), 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](/fr/quickstart/mcp#vérifier-avec-une-première-conversation) 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](#transport-sécurité-et-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.
| Outil | Fonction |
| - | - |
| `zelinqa_start` | Créer ou retrouver une conversation nommée et sa question en attente |
| `zelinqa_next_question` | Envoyer une réponse et obtenir la question suivante ; sans réponse, réafficher la question en attente sans nouveau tour |
| `zelinqa_add_context` | Ajouter un résumé de contexte hors tour |
| `zelinqa_adjust` | Appliquer des données confirmées ou ajuster l'état d'une dimension / de l'objectif hors tour |
| `zelinqa_status` | Relire la progression et la question en attente |
| `zelinqa_feedback` | Enregistrer un résultat métier réellement observé |
| `zelinqa_forget` | Libérer la conversation locale ; **ne supprime pas** les données du serveur |
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](https://github.com/Zelinqa/zelinqa-mcp/tree/main/skills/zelinqa). Les lire ne crée pas de session et n'appelle pas l'API. Consultez le [dépôt public](https://github.com/Zelinqa/zelinqa-mcp) pour les exemples d'hôtes et les détails du mode avancé.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.