@keolux/klx-mcp

Client MCP pour le serveur proxy-graphql KLX. Il expose un serveur MCP local sur stdio et relaie toutes les requêtes vers l'endpoint Streamable HTTP du proxy (/v1/mcp). Cela permet d'installer KLX dans n'importe quel hôte MCP qui parle stdio : Claude Desktop, Claude Code, Cursor, Codex CLI, Continue, Zed…

Ce que vous obtenez côté LLM

Une fois installé, votre assistant dispose des tools suivants :

| Tool | Rôle | |---|---| | login | Authentifie la session MCP (username / password). | | whoami | Contexte d'authentification courant. | | graphql_query | Exécute une query GraphQL (ACL appliquées). | | graphql_mutation | Exécute une mutation (ACL / flows / webhooks). | | list_tables | Liste les tables du modèle (sys_tables). | | describe_table | Détail d'une table (colonnes sys_fields). | | create_table | Crée une nouvelle table (enfant de root par défaut). | | add_field | Ajoute un champ à une table existante. | | list_root_fields | Introspection GraphQL (root fields). |

Toutes les opérations passent par le proxy avec votre JWT → les ACL du tenant sont automatiquement appliquées.

Installation

Option A — via npx (recommandée)

Rien à installer. Configurez simplement votre client MCP (voir plus bas) avec command: "npx". Il téléchargera le package au premier lancement.

Option B — installation globale

npm install -g @keolux/klx-mcp

Option C — depuis les sources (dev local)

cd /chemin/vers/proxy-graphql/klx-mcp-client
npm install
npm link   # expose `klx-mcp` dans votre PATH

Configuration

Toute la configuration passe par variables d'environnement.

| Variable | Défaut | Description | |---|---|---| | KLX_MCP_URL | http://localhost:4000/v1/mcp | Endpoint MCP du proxy. | | KLX_USERNAME | — | Login KLX pour auto-login au démarrage. | | KLX_PASSWORD | — | Mot de passe associé. | | KLX_TOKEN | — | JWT déjà obtenu (alternative au login/password). | | KLX_DEBUG | false | Active les logs sur stderr. |

Priorité : si KLX_TOKEN est défini, il est utilisé tel quel. Sinon, si KLX_USERNAME + KLX_PASSWORD sont définis, le client appelle automatiquement le tool login à la connexion. Sinon, la session démarre en anonyme et le LLM devra appeler login lui-même.

Configuration des hôtes MCP

Claude Desktop

Éditez ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "klx": {
      "command": "npx",
      "args": ["-y", "@keolux/klx-mcp"],
      "env": {
        "KLX_MCP_URL": "https://proxy.www.keolux.fr/v1/mcp",
        "KLX_USERNAME": "votre.login",
        "KLX_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}

Redémarrez Claude Desktop. L'icône 🔌 en bas de la fenêtre doit afficher klx avec 9 tools.

Claude Code

claude mcp add klx -- npx -y @keolux/klx-mcp
# puis definissez les env vars dans votre shell :
export KLX_MCP_URL="http://localhost:4000/v1/mcp"
export KLX_USERNAME="votre.login"
export KLX_PASSWORD="votre-mot-de-passe"

Alternative : si Claude Code supporte nativement les Remote MCP HTTP, vous pouvez aussi pointer directement l'URL du proxy sans ce client :

claude mcp add --transport http klx https://proxy.www.keolux.fr/v1/mcp \
  --header "Authorization: Bearer <JWT>"

Cursor

Dans Settings → Cursor Settings → MCP → Add new MCP Server :

{
  "mcpServers": {
    "klx": {
      "command": "npx",
      "args": ["-y", "@keolux/klx-mcp"],
      "env": {
        "KLX_MCP_URL": "https://proxy.www.keolux.fr/v1/mcp",
        "KLX_USERNAME": "votre.login",
        "KLX_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}

Codex CLI / Continue / Zed

Mêmes principes. Référez-vous à la doc de l'hôte : toute configuration acceptant un command + args + env fonctionne.

Test rapide

KLX_DEBUG=true \
KLX_MCP_URL="http://localhost:4000/v1/mcp" \
KLX_USERNAME="votre.login" \
KLX_PASSWORD="votre-mot-de-passe" \
  npx -y @keolux/klx-mcp

Rien ne s'affiche sur stdout (c'est normal, c'est un transport stdio). Sur stderr vous devez voir [klx-mcp] connected to … puis [klx-mcp] auto-login successful. Tapez Ctrl+C pour quitter.

Pour un test plus complet avec de vraies requêtes JSON-RPC, utilisez le MCP Inspector :

npx @modelcontextprotocol/inspector \
  env KLX_MCP_URL=http://localhost:4000/v1/mcp \
      KLX_USERNAME=… KLX_PASSWORD=… \
  npx -y @keolux/klx-mcp

Dépannage

cannot connect to … — le proxy n'est pas démarré ou l'URL est fausse. Vérifiez avec curl http://localhost:4000/v1/mcp (devrait renvoyer une erreur 400 JSON-RPC, pas un refus TCP).

auto-login failed — credentials invalides ou utilisateur désactivé. Testez manuellement la mutation login via le playground du proxy.

Le LLM ne voit aucun tool — redémarrez l'hôte MCP et vérifiez KLX_DEBUG=true pour lire les logs du bridge sur stderr.