Keboola

Serveur MCP Keboola

Connectez vos agents IA, clients MCP (Cursor, Claude, Windsurf, VS Code ...) et autres assistants IA à Keboola. Exposez des données, des transformations, des requêtes SQL et des déclencheurs de tâches, sans code de liaison. Fournissez aux agents les bonnes données, au bon endroit et au bon moment.

Présentation

Le serveur MCP Keboola est une passerelle open source entre votre projet Keboola et les outils d’IA modernes. Il transforme les fonctionnalités de Keboola — comme l’accès au stockage, les transformations SQL et les déclencheurs de tâches — en outils utilisables par Claude, Cursor, CrewAI, LangChain, Amazon Q et bien d’autres.

• Démarrage rapide
• Configuration locale

Fonctionnalités

Avec l’agent IA et le serveur MCP, vous pouvez :

• Stockage : interroger directement les tables et gérer les descriptions des tables ou des buckets
• Composants : créer, répertorier et examiner les extracteurs, les writers, les applications de données et les configurations de transformation
• SQL : créer des transformations SQL en langage naturel
• Tâches : exécuter des composants et des transformations, et récupérer les détails d’exécution des tâches
• Flux : créer et gérer des pipelines de workflow à l’aide de flux conditionnels et de flux Orchestrator.
• Applications de données : créer, déployer et gérer des applications de données Keboola qui affichent vos requêtes sur les données du stockage — des applications python-js sur un dépôt géré par Keboola ou sur un dépôt GitHub client (cloné via la connexion GitHub de l’organisation, sans identifiants stockés), ainsi que des applications Streamlit.
• Métadonnées : rechercher, lire et mettre à jour la documentation du projet et les métadonnées des objets en langage naturel
• Branches de développement : travailler en toute sécurité dans des branches de développement, hors production, où toutes les opérations sont limitées à la branche sélectionnée.

---

🚀 Démarrage rapide : serveur MCP distant (la méthode la plus simple)

La méthode la plus simple pour utiliser le serveur MCP Keboola consiste à passer par notre serveur MCP distant. Cette solution hébergée évite toute configuration ou installation locale.

Qu’est-ce que le serveur MCP distant ?

Notre serveur distant est hébergé sur chaque stack Keboola mutualisée et prend en charge l’authentification OAuth. Vous pouvez vous y connecter depuis tout assistant IA prenant en charge les connexions HTTP Streamable distantes et l’authentification OAuth.

Connexion

1. Obtenez l’URL de votre serveur distant : accédez à Paramètres du projet Keboola → onglet MCP Server
2. Copiez l’URL du serveur : elle ressemble à https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Configurez votre assistant IA : collez l’URL dans les paramètres MCP de votre assistant IA
4. Authentifiez-vous : vous serez invité à vous connecter avec votre compte Keboola. Le ou les projets à utiliser sont choisis ensuite, dans la conversation (par exemple, « répertorie mes projets Keboola » / « utilise le projet X »).

Clients pris en charge

• Cursor : utilisez le bouton « Install In Cursor » dans les paramètres du serveur MCP de votre projet ou cliquez sur ce bouton
• Claude Desktop : ajoutez l’intégration via Paramètres → Intégrations
• Claude Code : installez à l’aide de claude mcp add --transport http keboola <URL> (voir les détails ci-dessous)
• Windsurf : configurez-le avec l’URL du serveur distant
• Make : configurez-le avec l’URL du serveur distant
• Autres clients MCP : configurez-les avec l’URL du serveur distant

Configuration de Claude Code

Claude Code est un outil en ligne de commande qui vous permet d’interagir avec Claude depuis votre terminal. Vous pouvez installer l’intégration du serveur MCP Keboola à l’aide d’une simple commande.

Installation :

Exécutez la commande suivante dans votre terminal en remplaçant <YOUR_REGION> par votre région Keboola :

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

Commandes propres à chaque région :

Région	Commande d’installation
US Virginia AWS	claude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCP	claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWS	claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azure	claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCP	claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

Utilisation :

Une fois l’installation terminée, vous pouvez utiliser le serveur MCP Keboola dans Claude Code en saisissant /mcp dans votre conversation et en sélectionnant les outils Keboola que vous souhaitez utiliser.

Authentification :

Lors de votre première utilisation du serveur MCP Keboola dans Claude Code, une fenêtre de navigateur s’ouvrira et vous invitera à :

1. Vous connecter avec votre compte Keboola
2. Autoriser la connexion

Après l’authentification, vous pouvez utiliser directement les outils Keboola depuis Claude Code. La sélection du projet se fait ensuite, dans la conversation : demandez simplement à Claude quel(s) projet(s) Keboola utiliser.

Pour obtenir des instructions détaillées de configuration et les URL propres à chaque région, consultez notre documentation de configuration du serveur distant.

Utilisation des branches de développement

Vous pouvez travailler en toute sécurité dans les branches de développement Keboola sans affecter vos données de production. Les serveurs MCP hébergés à distance respectent le paramètre KBC_BRANCH_ID et limitent toutes les opérations à la branche spécifiée. Vous trouverez l’ID de la branche de développement dans l’URL lorsque vous accédez à cette branche dans l’interface, par exemple : https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. L’ID de branche doit être inclus dans chaque requête à l’aide de l’en-tête X-Branch-Id: <branchId>, sinon le serveur MCP utilise par défaut la branche de production. Cette gestion doit être assurée par le client IA ou l’environnement qui gère la connexion au serveur.

Autorisation des outils et contrôle d’accès

Avec les transports basés sur HTTP (HTTP Streamable), vous pouvez contrôler les outils accessibles aux clients à l’aide d’en-têtes HTTP. Cette fonctionnalité est utile pour limiter les capacités des agents IA ou appliquer des politiques de conformité.

En-têtes d’autorisation

En-tête	Description	Exemple
X-Allowed-Tools	Liste des outils autorisés, séparés par des virgules	get_configs,get_buckets,query_data
X-Disallowed-Tools	Liste des outils à exclure, séparés par des virgules	create_config,run_job
X-Read-Only-Mode	Limiter l’accès aux outils en lecture seule	true, 1 ou yes

Comportement des filtres

Les filtres sont appliqués dans l’ordre suivant : autorisation → intersection avec les outils en lecture seule → exclusion des outils interdits. Des en-têtes vides n’imposent aucune restriction.

Outils en lecture seule

Les outils en lecture seule sont ceux annotés avec readOnlyHint=True. Ils récupèrent uniquement des informations, sans apporter de modifications à votre projet Keboola. Pour consulter la liste actuelle des outils en lecture seule, reportez-vous au fichier TOOLS.md, un instantané généré automatiquement de l’ensemble réel des outils.

Exemple : accès en lecture seule

X-Read-Only-Mode: true

Chargement différé des outils

En-tête	Description	Exemple
X-Deferred-Tools	Liste des outils à répertorier avec _meta["anthropic/alwaysLoad"] = false	run_sync_action,get_flow_schema

Les clients Claude Code / Claude Agent SDK qui enregistrent le serveur avec alwaysLoad: true gardent ces outils différés, accessibles via la recherche d’outils, au lieu de charger leurs définitions dès le départ. Cet en-tête ne modifie que les métadonnées tools/list : il ne masque pas les outils et ne les autorise pas. Un en-tête vide ou des noms d’outils inconnus n’entraînent aucun changement.

Pour obtenir une documentation détaillée, consultez developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Sécurité au niveau des lignes et des colonnes

Les politiques au niveau des lignes et des colonnes sont des objets Keboola Metastore (rls-policy, cls-policy), écrits via l’API Metastore (les commandes kbagent rls / kbagent cls ne sont encore disponibles dans aucune version de kbagent). Ce serveur ne les lit pas et ne les applique pas. Dans un projet doté de la fonctionnalité row-level-security, il crée son espace de travail (la configuration mcp-workspace-<hex> du composant keboola.mcp-server-tool) avec le type de connexion governed. Un espace de travail gouverné ne contient aucun identifiant : seul le Query Service peut le lire, et le Query Service filtre chaque résultat query_data selon les politiques du projet. Ce serveur n’effectue aucune réécriture et ne propose aucun mécanisme de secours : si le Query Service refuse une requête, query_data renvoie une erreur.

• Ce qui l’active. Seul ce serveur vérifie la fonctionnalité du projet ; Connection n’a besoin d’aucune fonctionnalité ni d’aucun rôle pour créer un espace de travail gouverné (Snowflake ou BigQuery, sans clé publique). Connection de la stack doit accepter le type de connexion governed pour le backend du projet : une stack qui ne l’accepte pas refuse la création, puis tous les outils qui ont besoin de l’espace de travail échouent (il n’y a pas de solution de repli vers un espace de travail ordinaire). L’application de ces règles sur BigQuery n’a pas été vérifiée de bout en bout sur une stack de production. Un ancien espace de travail MCP ordinaire n’est pas supprimé : dès que la fonctionnalité est activée, il est ignoré. Lorsque la fonctionnalité est activée, une épingle workspace_schema ou X-Workspace-Id n’est acceptée que pour un espace de travail gouverné (un espace ordinaire contournerait les règles) ; une épingle vers l’ancien espace de travail ou vers l’espace de travail ordinaire propre à une application de données est donc refusée ; supprimez l’ancien espace.
• Refus par défaut. Une table qui n’est couverte ni par un rls-policy ni par un cls-policy est refusée à un administrateur (l’agent voit Row-level security does not allow this query) et ne renvoie aucune ligne à un lecteur ordinaire, tel qu’un utilisateur final d’application de données (une règle "*" ouvre une table à tous les lecteurs identifiés). Un cls-policy seul ouvre sa table : toutes les lignes, uniquement ses colonnes, pour les lecteurs qu’il nomme ; tout autre lecteur est refusé. Une instruction qui ne lit aucune table (SELECT 1) s’exécute.
• Instructions refusées. Une instruction gouvernée est refusée (403, avec le même texte générique quelle qu’en soit la raison) lorsqu’elle utilise IDENTIFIER(), TABLE() en dehors de FROM, une fonction d’IA (AI_*, BigQuery AI.*), TO_FILE, READ_CSV / READ_PARQUET, SECRET, une fonction de contexte de session (CURRENT_USER, CURRENT_ROLE, CURRENT_STATEMENT, ...), NEXTVAL, $x ou @@x, un caractère de contrôle, ou un nom non cité contenant un caractère non ASCII ou $$, ou lorsqu’elle dépasse 32 KiB, 200 CTE ou 300 références de tables. CURRENT_DATE, CURRENT_TIME et CURRENT_TIMESTAMP restent autorisés (à partir de Query Service 1.25 et policy engine 0.1.8). Une erreur 503 Row-level security could not be applied to this workspace signifie que rien n’a été exécuté, car les règles n’ont pas pu être appliquées ; elle peut être temporaire. Une instruction gouvernée qui échoue renvoie The statement failed. Its error text is not shown for a workspace with row-level security.
• Qui est le lecteur. Query Service détermine le lecteur à partir du propre jeton de l’administrateur pour le projet : le jeton programmatique transmis par ce serveur (kbc_at_ / kbc_pat_, y compris le PAT enfant d’une portée multi-projets, envoyé avec X-KBC-ProjectId) ou le propre jeton Storage principal de l’administrateur. Tout autre jeton (une intégration, une application de données, Kai) ne désigne aucun utilisateur final, n’a pas d’identité vérifiée et ne lit rien dans une table gouvernée. Le sujet de l’administrateur est keboola|<adminId> et l’identité ne comporte aucun groupe ; les règles de groupe ne correspondent donc jamais.
• Liaisons. Sans liaison, un espace de travail reçoit toutes les règles du projet, et ce serveur n’en crée jamais. Pour n’appliquer à un espace de travail qu’une partie des règles, liez-les à son KID : KID:<stack-id>:project-<project-id>:workspace-<workspace-id> (un espace de travail de la branche par défaut ; un espace de travail de branche comporte aussi branch-<branch-id> avant project). L’identifiant de la stack est celui configuré dans Query Service (QUERY_RLS_STACK_ID, par exemple dev-keboola-aws-eu-west-1), l’identifiant de l’espace de travail figure dans la sortie get_project_info, et un objet Metastore policy-binding avec ce KID écrit la liaison (aucune commande kbagent n’est encore disponible pour cela). Une liaison est une liste d’autorisation : elle ne conserve que les règles qu’elle énumère ; elle peut donc omettre n’importe quelle règle, y compris une règle de portée organisationnelle, et assouplir l’accès. Une liaison qui n’énumère aucun rls-policy supprime toutes les règles de lignes ; une table couverte par un cls-policy conservé s’ouvre alors avec toutes ses lignes. Une liaison s’applique à la requête suivante et ne suit pas la session vers un autre espace de travail : une session de branche, ou un espace de travail recréé, a un nouveau KID et repart avec toutes les règles.
• Limites. L’identifiant de l’espace de travail du serveur est également celui qu’une application de données reçoit comme WORKSPACE_ID lorsqu’aucun espace de travail distinct ne lui est provisionné ; l’application effectue ses requêtes avec son propre jeton, n’a pas d’identité vérifiée et ne lit rien dans les tables gouvernées.
• Métadonnées. Les outils de métadonnées n’affichent que ce que Query Service autorise le lecteur à lire. get_tables et search (qui n’utilise alors pas la recherche globale, car ses décomptes incluent les tables masquées) omettent une table que le lecteur n’est pas autorisé à lire, et get_tables signale comme introuvable une table recherchée par ID ; une table soumise à une règle de colonnes n’affiche que les colonnes de cette règle (également dans sa clé primaire et dans les correspondances de search). Une table lisible est affichée sans son nombre de lignes ni sa taille, car ces valeurs comptent les lignes masquées par une règle de lignes. get_buckets répertorie toujours tous les buckets, mais sans le nombre de tables ni leur taille, car ces valeurs comptent les tables masquées. Cela nécessite le point de terminaison Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope et échoue de manière sécurisée : lorsque Query Service ne peut pas se prononcer, un outil d’un projet gouverné renvoie une erreur avec un court message et aucune table. Un projet sans cette fonctionnalité n’est pas concerné et n’effectue aucun appel supplémentaire.

---

Configuration du serveur MCP local (méthode personnalisée ou de développement)

Exécutez le serveur MCP sur votre propre machine pour garder le contrôle et faciliter le développement. Choisissez cette méthode si vous souhaitez personnaliser les outils, déboguer localement ou itérer rapidement. Vous installerez le serveur, vous vous authentifierez (une seule connexion via navigateur — aucun jeton à coller), puis vous le démarrerez. Cette approche offre une flexibilité maximale (outils personnalisés, journalisation locale, itérations hors ligne), mais nécessite une configuration manuelle et vous devrez gérer vous-même les mises à jour et les secrets.

Le serveur prend en charge plusieurs options de transport, sélectionnables en fournissant l’argument --transport <transport> au démarrage du serveur :

• stdio - Valeur par défaut si --transport n’est pas spécifié. Entrée/sortie standard, généralement utilisée pour un déploiement local avec un seul client.
• streamable-http - Exécute le serveur à distance sur HTTP avec un canal de diffusion bidirectionnel, permettant au client et au serveur d’échanger des messages en continu. Connectez-vous via /mcp (par exemple, http://localhost:8000/mcp).
• http-compat - Alias de streamable-http, conservé pour assurer la rétrocompatibilité.

Pour utiliser votre projet Keboola, le serveur a besoin de deux éléments : votre région Keboola (KBC_STORAGE_API_URL) et un moyen de vous authentifier. La méthode recommandée est une connexion unique via navigateur : vous n’avez jamais à créer, copier ou coller de jeton. Vous pouvez définir KBC_BRANCH_ID pour travailler dans une branche de développement.

Certaines variables ne sont pas récupérées dans les en-têtes de requête :

• KBC_STORAGE_API_URL : un serveur démarré avec sa propre URL Storage API (le paramètre --api-url ou la variable d’environnement KBC_STORAGE_API_URL) ne dessert qu’une seule stack Keboola. Un en-tête X-Storage-Api-Url demandant un autre hôte est ignoré (un avertissement est consigné) : le serveur conserve sa propre URL pour la requête. Démarrez le serveur sans URL Storage API propre si vous souhaitez que chaque requête puisse choisir sa stack.
• KBC_KUBERNETES_TOKEN_PATH (serveurs déployés uniquement, voir docs/kubernetes-sa-auth.md) : lu uniquement depuis l’environnement, jamais depuis un en-tête.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA : même principe que pour l’URL Storage API ci-dessus : un serveur démarré avec sa propre épingle d’espace de travail (via l’une ou l’autre variable, ou --workspace-id) conserve cette épingle pour chaque requête ; un en-tête X-Workspace-Id ou X-Workspace-Schema demandant un autre espace de travail est ignoré (un avertissement est consigné). Un serveur sans épingle propre (cas partagé multi-utilisateur) continue de récupérer l’épingle dans chaque requête, comme décrit ci-dessous.

Connexion

Connectez-vous une fois avec votre navigateur ; le serveur enregistre la session et la renouvelle automatiquement, vous n’avez donc aucun jeton à gérer :

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Cette commande ouvre votre navigateur pour vous connecter à Keboola, puis enregistre la session valable pour toute la stack dans ~/.keboola/mcp/credentials.json (lisible uniquement par vous, une entrée par stack). Ensuite, démarrez le serveur en définissant uniquement KBC_STORAGE_API_URL — aucun jeton n’est requis. Le ou les projets sur lesquels travailler sont choisis ensuite, dans la conversation (get_accessible_projects / set_project_scope), et non pendant la connexion.

Commande	Fonction
login --api-url <url>	Se connecter à une stack
login --force	Se reconnecter / changer de compte
login --show-token	Afficher le jeton de session actuel (débogage)
logout [--api-url <url>] [--all]	Supprimer la session enregistrée pour une stack (ou pour toutes les stacks)

Lorsque vous démarrez le serveur sur stdio dans un terminal interactif sans session enregistrée, il lance automatiquement cette connexion par navigateur au premier démarrage. Les clients MCP (Claude, Cursor, …) lancent le serveur en arrière-plan, où un navigateur ne peut pas s’ouvrir ; exécutez donc d’abord login vous-même.

Démarrer sans compte Keboola

Vous pouvez également démarrer le serveur avec uniquement KBC_STORAGE_API_URL et sans aucun identifiant. Il démarre en mode d’amorçage : les outils qui nécessitent un accès à Keboola expliquent comment obtenir un identifiant, et un outil fonctionne sans identifiant — create_project. Il crée un nouveau projet Keboola, y connecte la session et renvoie une URL de confirmation. En ouvrant cette URL dans un navigateur et en vous connectant, le projet devient définitivement le vôtre ; jusque-là, il est temporaire et Keboola peut le récupérer. Une fois la confirmation effectuée, la session créée par l’outil est révoquée et vous continuez avec votre propre login.

Cette fonctionnalité nécessite une stack sur laquelle le provisionnement par agent est activé ; sinon, l’outil indique qu’elle n’est pas disponible.

La même chose est possible sans exécuter de serveur, sur un serveur MCP hébergé à distance dont l’opérateur a activé cette fonctionnalité (KBC_ALLOW_ANONYMOUS_PROVISIONING) : un tel déploiement propose également https://mcp.<stack>/mcp-anonymous, qui n’accepte aucun identifiant. Configurez votre client pour utiliser cette URL sans authentification, appelez create_project et continuez à travailler dans le projet créé par cet appel : le serveur conserve vos identifiants et l’outil vous renvoie un scope_token opaque à renvoyer lors des appels suivants. Il s’agit d’une URL distincte, car le point de terminaison ordinaire /mcp doit continuer à refuser les requêtes non authentifiées : ce refus permet aux clients MCP de savoir qu’ils doivent lancer la connexion OAuth. Une fois le projet revendiqué, passez à /mcp et connectez-vous avec le compte qui en est désormais propriétaire.

Authentification sans navigateur

Pour les conteneurs ou les environnements CI où la connexion par navigateur est impossible, fournissez directement un jeton d’accès ou un jeton d’accès personnel Keboola : définissez KBC_STORAGE_TOKEN (variable d’environnement) ou envoyez l’en-tête X-StorageAPI-Token, ainsi que KBC_PROJECT_ID (ou l’en-tête X-KBC-ProjectId) pour sélectionner le projet. Avec les transports HTTP, ces valeurs peuvent être fournies sous forme d’en-têtes par requête, afin que chaque requête transporte ses propres identifiants.

KBC_WORKSPACE_ID

Épingle les requêtes à un espace de travail spécifique, déjà existant, à l’aide de son ID plutôt que de la recherche basée sur le schéma décrite ci-dessus ; cette option est prioritaire sur KBC_WORKSPACE_SCHEMA lorsque les deux sont définies. C’est l’option qu’un appelant Data App / kai-agent fournit dans l’en-tête X-Workspace-Id, afin que Kai intégré à cette application n’effectue des requêtes que via son propre espace de travail.

À définir avec la variable d’environnement KBC_WORKSPACE_ID, l’option CLI --workspace-id ou, par requête dans les déploiements multi-utilisateurs, l’en-tête X-Workspace-Id.

KBC_WORKSPACE_SCOPE

strict limite une session à son espace de travail épinglé, pour Kai dans une Data App dont l’espace de travail utilise un mappage d’entrée par attribution directe. La session :

• ne propose que query_data, get_buckets, get_tables, get_project_info et docs_query, quels que soient les en-têtes d’autorisation (ils peuvent encore réduire cette liste, mais pas l’élargir) ;
• ne recherche ni ne crée jamais l’espace de travail géré par MCP et ne répartit jamais les requêtes entre plusieurs projets ;
• refuse un espace de travail disposant d’un accès en lecture seule à l’ensemble de Storage et refuse les aperçus de configuration. Il nécessite un épinglage de l’espace de travail (KBC_WORKSPACE_ID / X-Workspace-Id). strict est la seule valeur acceptée : une requête peut donc renforcer une session, mais jamais assouplir une strict côté serveur. Définissez-la à l’aide de la variable d’environnement KBC_WORKSPACE_SCOPE ou, pour chaque requête, de l’en-tête X-Workspace-Scope.

KBC_STORAGE_API_URL (région Keboola)

L’URL de l’API de votre région Keboola dépend de votre région de déploiement. Pour déterminer votre région, consultez l’URL affichée dans votre navigateur lorsque vous êtes connecté à votre projet Keboola :

Région	URL de l’API
Amérique du Nord AWS	https://connection.keboola.com
Europe AWS	https://connection.eu-central-1.keboola.com
UE Google Cloud	https://connection.europe-west3.gcp.keboola.com
États-Unis Google Cloud	https://connection.us-east4.gcp.keboola.com
UE Azure	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (facultatif)

Pour travailler sur une branche de développement Keboola spécifique, définissez l’ID de la branche à l’aide du paramètre KBC_BRANCH_ID. Le serveur MCP limite ses fonctionnalités à la branche spécifiée, ce qui garantit que toutes les modifications restent isolées et n’affectent pas la branche de production.

• Si cette valeur n’est pas fournie, le serveur utilise la branche de production par défaut.
• Pour le développement, définissez KBC_BRANCH_ID sur l’ID numérique de votre branche (par exemple, 123456). Vous trouverez l’ID de la branche de développement dans l’URL lorsque vous accédez à cette branche dans l’interface, par exemple : https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Avec les transports distants, vous pouvez remplacer cette valeur pour chaque requête à l’aide de l’en-tête HTTP X-Branch-Id: <branchId> ou KBC_BRANCH_ID: <branchId>.

Installation

Assurez-vous de disposer des éléments suivants :

• Python 3.11+ installé
• Accès à un projet Keboola avec des droits d’administrateur
• Votre client MCP préféré (Claude, Cursor, etc.)

Remarque : assurez-vous que uv est installé. Le client MCP l’utilisera pour télécharger et exécuter automatiquement le serveur MCP Keboola. Installation de uv :

macOS/Linux :

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows :

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

Pour découvrir d’autres options d’installation, consultez la documentation officielle de uv.

Exécution du serveur MCP Keboola

Il existe quatre façons d’utiliser le serveur MCP Keboola, selon vos besoins :

Option A : mode intégré (recommandé)

Dans ce mode, Claude ou Cursor démarre automatiquement le serveur MCP.

1. Connectez-vous une fois dans un terminal afin qu’une session soit enregistrée (le client lance le serveur en arrière-plan, où un navigateur ne peut pas s’ouvrir) :

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. Configurez votre client MCP (Claude/Cursor) avec les paramètres ci-dessous — seul KBC_STORAGE_API_URL est nécessaire.
3. Le client lancera automatiquement le serveur MCP lorsque nécessaire.

Configuration de Claude Desktop

1. Accédez à Claude (coin supérieur gauche de l’écran) -> Settings → Developer → Edit Config (si le fichier claude_desktop_config.json n’apparaît pas, créez-le)
2. Ajoutez la configuration suivante :
3. Redémarrez Claude Desktop pour appliquer les modifications

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Emplacements du fichier de configuration :

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

Configuration de Cursor

1. Accédez à Settings → MCP
2. Cliquez sur « + Add new global MCP Server »
3. Configurez les paramètres suivants :

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Remarque : utilisez des noms courts et descriptifs pour les serveurs MCP. Comme le nom complet de l’outil inclut le nom du serveur et doit comporter moins d’environ 60 caractères, les noms plus longs risquent d’être filtrés dans Cursor et de ne pas s’afficher pour l’agent.

Configuration de Cursor pour Windows WSL

Lorsque vous exécutez le serveur MCP depuis le sous-système Windows pour Linux avec Cursor AI, utilisez cette configuration :

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Option B : mode de développement local

Pour les développeurs qui travaillent directement sur le code du serveur MCP :

1. Clonez le dépôt et configurez un environnement local
2. Configurez Claude/Cursor pour utiliser votre chemin Python local :

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Option C : mode CLI manuel (réservé aux tests)

Vous pouvez exécuter manuellement le serveur dans un terminal pour le tester ou le déboguer :

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

Remarque : ce mode sert principalement au débogage ou aux tests. Pour une utilisation normale avec Claude ou Cursor, vous n’avez pas besoin de lancer le serveur manuellement.

Remarque : le serveur utilisera le transport Streamable HTTP et écoutera sur localhost:8000 les connexions entrantes à /mcp. Vous pouvez utiliser les paramètres --port et --host pour le faire écouter ailleurs.

Option D : utilisation de Docker

Un conteneur ne peut pas ouvrir de navigateur. Authentifiez-vous donc avec un jeton (voir Authentification sans navigateur) : définissez KBC_STORAGE_TOKEN sur un jeton d’accès Keboola ou un jeton d’accès personnel, et KBC_PROJECT_ID sur le projet cible. (Avec HTTP, vous pouvez plutôt transmettre les en-têtes X-StorageAPI-Token / X-KBC-ProjectId pour chaque requête et omettre ces variables.)

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Remarque : le serveur utilisera le transport Streamable HTTP et écoutera sur localhost:8000 les connexions entrantes à /mcp. Vous pouvez modifier -p pour mapper le port du conteneur vers un autre port.

Dois-je démarrer le serveur moi-même ?

Scénario	Exécution manuelle nécessaire ?	Configuration à utiliser
Utilisation de Claude/Cursor	Non	Configurer MCP dans les paramètres de l’application
Développement local de MCP	Non (Claude le démarre)	Indiquer le chemin Python dans la configuration
Tests manuels de la CLI	Oui	Lancer le serveur dans un terminal
Utilisation de Docker	Oui	Exécuter le conteneur Docker

Utilisation du serveur MCP

Une fois votre client MCP (Claude/Cursor) configuré et lancé, vous pouvez commencer à interroger vos données Keboola :

Vérifier votre configuration

Vous pouvez commencer par une requête simple pour vérifier que tout fonctionne :

What buckets and tables are in my Keboola project?

Exemples d’utilisation

Exploration des données :

• « Quelles tables contiennent des informations sur les clients ? »
• « Exécute une requête pour trouver les 10 principaux clients par chiffre d’affaires »

Analyse des données :

• « Analyse mes données de ventes par région pour le dernier trimestre »
• « Trouve les corrélations entre l’âge des clients et la fréquence d’achat »

Pipelines de données :

• « Crée une transformation SQL qui joint les tables des clients et des commandes »
• « Lance la tâche d’extraction des données pour mon composant Salesforce »

Compatibilité

Prise en charge des clients MCP

Client MCP	État de la prise en charge	Méthode de connexion
Claude (Desktop et Web)	✅ pris en charge	stdio
Cursor	✅ pris en charge	stdio
Windsurf, Zed, Replit	✅ pris en charge	stdio
Codeium, Sourcegraph	✅ pris en charge	Streamable HTTP
Clients MCP personnalisés	✅ pris en charge	Streamable HTTP ou stdio

Outils pris en charge

Remarque : vos agents IA s’adapteront automatiquement aux nouveaux outils.

Pour obtenir la liste complète des outils disponibles, avec leurs descriptions détaillées, leurs paramètres et des exemples d’utilisation, consultez TOOLS.md.

Dépannage

Problèmes courants

Problème	Solution
Erreurs d’authentification	Relancez keboola_mcp_server login (ou, si vous vous authentifiez avec un jeton, vérifiez le jeton et KBC_PROJECT_ID)
Délai d’expiration de la connexion	Vérifiez la connectivité réseau

Développement

Installation

Configuration de base :

uv sync --extra dev

Avec la configuration de base, vous pouvez utiliser uv run tox pour exécuter les tests et vérifier le style du code.

Configuration recommandée :

uv sync --extra dev --extra tests --extra integtests --extra codestyle

Avec la configuration recommandée, les packages nécessaires aux tests et à la vérification du style du code seront installés. Les IDE comme VsCode ou Cursor pourront ainsi vérifier le code ou exécuter des tests pendant le développement.

Tests d’intégration

Pour exécuter les tests d’intégration localement, utilisez uv run tox -e integtests. REMARQUE : vous devrez définir les variables d’environnement suivantes :

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Pour obtenir ces valeurs, vous devez disposer de projets Keboola dédiés aux tests d’intégration. Chaque session de test crée son propre espace de travail en lecture seule ; aucun schéma d’espace de travail ne doit donc être configuré. Consultez integtests/README.md pour obtenir des instructions détaillées de configuration et la documentation de conception.

Mise à jour de uv.lock

Mettez à jour le fichier uv.lock si vous avez ajouté ou supprimé des dépendances. Pensez également à mettre à jour le fichier de verrouillage avec des versions plus récentes des dépendances lors de la création d’une version (uv lock --upgrade).

Mise à jour de la documentation des outils

Lorsque vous modifiez la description d’un outil (docstrings dans les fonctions des outils), vous devez régénérer le fichier de documentation TOOLS.md pour refléter ces modifications :

uv run python -m src.keboola_mcp_server.generate_tool_docs

Publication d’une version

Nous ne publions pas une version pour chaque PR fusionnée. Les modifications sont intégrées en continu dans la branche principale (main), et nous publions périodiquement une version après avoir retesté les modifications ensemble — cela évite de perturber les configurations fonctionnelles des utilisateurs.

Une version est publiée en poussant un ou deux tags git :

• vX.Y.Z — version du serveur MCP (toujours)
• agent-vX.Y.Z — version de l’agent In Platform (uniquement lorsque l’agent est également publié)

L’un ou l’autre de ces tags déclenche release.yml CI, qui crée et publie l’image Docker. KaiBench ne s’exécute que pour les tags vX.Y.Z de production (pas pour agent-vX.Y.Z, ni pour les préversions -dev.). Utilisez la compétence release-notes — elle prépare les notes de version et une PR brouillon, puis vous guide pour créer les tags de vX.Y.Z et agent-vX.Y.Z.

Assistance et commentaires

⭐ Le principal moyen d’obtenir de l’aide, de signaler des bugs ou de demander des fonctionnalités est d’ouvrir une issue sur GitHub. ⭐

L’équipe de développement suit activement les issues et y répondra aussi rapidement que possible. Pour obtenir des informations générales sur Keboola, consultez les ressources ci-dessous.

Ressources

• Documentation utilisateur
• Documentation développeur
• Plateforme Keboola
• Suivi des issues ← Principal moyen de contacter l’équipe du serveur MCP

Nous suivre

• LinkedIn
• Twitter
• Journal des modifications