> ## 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.

# Connecter le MCP

> Installer Zelinqa MCP et conduire une conversation avec un hôte compatible.

Vous avez besoin de Python 3.11+, de `uvx` et d'une clé `runtime` créée dans Zelinqa Studio pour un domaine publié. Le paquet public est [`zelinqa-mcp` sur PyPI](https://pypi.org/project/zelinqa-mcp/).

## 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.

<Tabs>
  <Tab title="Claude Code">
    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).
  </Tab>

  <Tab title="Codex">
    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).
  </Tab>

  <Tab title="Cursor">
    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.
  </Tab>

  <Tab title="Claude Desktop">
    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.
  </Tab>
</Tabs>

<Warning>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.</Warning>

<Note>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.</Note>

Pour mettre à jour une installation existante ou choisir entre `@latest` et une version fixe, consultez [Versions et mise à jour MCP](/fr/integrations/mcp#versions).

## Vérifier avec une première conversation

Demandez à votre hôte :

> Utilise Zelinqa pour commencer une conversation nommée demo-42. Pose-moi la question renvoyée, attends ma réponse et continue une question à la fois. N'invente aucune réponse.

L'hôte doit appeler `zelinqa_start`, afficher une question de votre domaine, puis utiliser `zelinqa_next_question` après votre réponse. Vérifiez la présence des sept [outils métier](/fr/integrations/mcp). L'installation seule ne crée pas de conversation ; les appels métier utilisent votre API et ses quotas.

## Premier tour

Dans votre hôte, appelez les outils dans cet ordre :

```json theme={null}
{"tool":"zelinqa_start","arguments":{"conversation":"demo-42"}}
```

Affichez réellement la question renvoyée et attendez la personne. Si vous rappelez `zelinqa_next_question` sans réponse, il réaffiche seulement la question en attente. Après réception d'une réponse à une question ouverte :

```json theme={null}
{"tool":"zelinqa_next_question","arguments":{"conversation":"demo-42","user_text":"Je cherche un canapé pour mon salon."}}
```

Pour une question à choix, utilisez `choice_labels` avec le libellé exact affiché, par exemple `{"choice_labels":["Contemporain"]}`. Pour une semi-ouverte, ajoutez `free_text` seulement si la personne a apporté un complément. Pour un refus ou une absence de réponse réelle, utilisez `outcome: "refused"` ou `outcome: "asked_no_answer"` sans inventer de texte. La réponse de l'outil contient la question suivante, la progression et les avertissements.

`zelinqa_adjust` permet d'ajouter des données déjà confirmées sans poser une question ni consommer un tour. `zelinqa_feedback` sert au résultat métier observé, pas à une prédiction. Après une coupure, appelez `zelinqa_status` avant de renvoyer une réponse. `zelinqa_forget` nettoie le handle local, mais n'efface pas la session sur l'API.

<Warning>Les noms de conversations ne survivent pas seuls au redémarrage du processus MCP. Pour reprendre `demo-42`, conservez l'identifiant de session côté hôte/backend et fournissez **`ZELINQA_SESSION_ID` et `ZELINQA_CONVERSATION=demo-42`** au nouveau processus. Le nom doit correspondre exactement à celui passé à l'outil ; sinon, une nouvelle session peut être créée. Ne placez pas l'identifiant dans le prompt du modèle.</Warning>

Voir la [description complète du MCP](/fr/integrations/mcp) et son [guide source](https://github.com/Zelinqa/zelinqa-mcp/blob/main/README.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.