Premiers pas avec les agents de codage IA
Le moyen le plus rapide de se connecter se trouve dans PlaidCloud lui-même : ouvrez le menu de l’avatar (utilisateur) et choisissez Connecter votre IA, sélectionnez le client que vous utilisez et suivez les étapes affichées, y compris l’URL du serveur MCP de votre espace de travail, déjà renseignée. Cette fonction est disponible dès que le droit d’utilisation de l’IA est activé pour votre espace de travail. Le reste de cette page, ainsi que les pages par client qui la suivent, restent la référence : poursuivez la lecture si vous n’êtes pas dans l’interface web, ou si vous voulez une vue complète de l’authentification et de ce que le serveur expose.
Qu’est-ce que le serveur MCP ?
Section intitulée « Qu’est-ce que le serveur MCP ? »Le Model Context Protocol est un standard ouvert qui permet aux agents IA de dialoguer avec des outils et des données externes. PlaidCloud exécute un serveur MCP sur chaque espace de travail, qui enveloppe les mêmes fonctions de base que l’API REST, regroupées par intention (find, describe, upsert, run, organize) afin qu’un agent puisse naviguer dans la surface sans charger plus de 1 000 noms de méthodes RPC de bas niveau.
Le serveur se trouve à l’adresse :
https://<your-workspace>.plaid.cloud/mcpRemplacez <your-workspace> par le sous-domaine de votre espace de travail (celui que vous utilisez pour vous connecter à l’interface PlaidCloud).
Ce qu’il expose
Section intitulée « Ce qu’il expose »Le catalogue couvre l’essentiel de la surface quotidienne dont un agent a besoin :
- Projets, workflows, étapes : find/describe/upsert/run/organize, y compris la ré-exécution au niveau de l’étape et l’historique des versions.
- Tables, vues, requêtes : introspection de schéma, exécution de requêtes, exports, instantanés, branches. Les vues sont les mêmes que celles que vous voyez dans PlaidCloud, que vous les ayez créées dans l’explorateur de tables ou qu’un workflow les ait créées.
- Dimensions : décrire, rechercher, upsert, versionner, gérer les nœuds, alias et propriétés.
- Connexions : rechercher, upsert et tester les connexions vers des systèmes externes.
- Lakehouse : branches, instantanés, opérations d’optimisation et de vacuum.
- Identité : membres, groupes, sessions, listes de distribution.
- Documents, tableaux de bord, UDF, éditeurs, agents, publications : outils propres à chaque domaine.
- Migration de workflows : convertissez les exports Alteryx (
alteryx_convert), KNIME (knime_convert), Prophecy (prophecy_convert) et Savant (savant_convert) déposés dans Document en workflows PlaidCloud, et coordonnez le travail de migration d’un portefeuille. - Documentation PlaidCloud :
docs_searchtrouve des pages de la documentation PlaidCloud par mot-clé, etdocs_fetchlit une page en entier, afin que votre agent puisse vérifier le fonctionnement d’une fonctionnalité avant de construire avec elle. - Journaux de workflow et suivi des exécutions :
workflow_logs,workflow_run_status,workflow_job_track.
Chaque outil renvoie une enveloppe uniforme {ok, data, next_cursor?, total?} ; les échecs utilisent {ok: false, error: {code, retryable, message, hint?}}. Les mutations acceptent dry_run=True pour une validation qui planifie sans écrire.
Garder les résultats petits
Section intitulée « Garder les résultats petits »Les résultats d’outils sont le plus gros consommateur du contexte d’un agent ; les outils find et describe renvoient donc par défaut une tranche modeste et vous laissent l’élargir :
- Lignes. Un find renvoie 25 correspondances par page (
step_finden renvoie 50). Une page plafonnée définitnext_cursor, et les outils find nomment en plus la liste tronquée danstruncated: l’un ou l’autre signifie « il y en a d’autres », et non « ce sont toutes ».totalindique toujours le nombre complet. Augmentezlimitou paginez avec le curseur. - Colonnes. Passez
fields=['id', 'name', 'update_time']pour ne récupérer que ces colonnes. Un nom de champ qui n’apparaît dans aucun enregistrement est une erreur qui liste les champs disponibles, et non une omission silencieuse : une faute de frappe échoue donc bruyamment au lieu de renvoyer discrètement moins que ce que vous avez demandé. Les outils qui proposent des ensembles prédéfinis acceptent aussifield_set='minimal' | 'default' | 'full'; appelezmcp_introspectpour voir les paramètres qu’accepte un outil donné. - Comptages.
count_only=Truedimensionne un ensemble de résultats sans le récupérer.
Les champs inconnus sont refusés
Section intitulée « Les champs inconnus sont refusés »Le spec qu’un outil accepte, comme celui de project_upsert ou de workflow_upsert, n’accepte que les champs qu’il liste. Un champ qu’il ne reconnaît pas est refusé avec une erreur qui nomme le champ, au lieu d’être ignoré et de vous laisser découvrir plus tard qu’il n’a rien fait. Corrigez le nom et renvoyez la requête. workflow_upsert prend la description d’un workflow sous la forme memo, et accepte description comme autre nom.
Regrouper les requêtes
Section intitulée « Regrouper les requêtes »mcp_batch regroupe plusieurs appels d’outils en une seule requête. Il accepte au plus 100 appels, en exécute un nombre limité à la fois et ne peut pas être imbriqué dans un autre mcp_batch ni dans une recette : listez plutôt les appels dans un seul lot à plat, ce qui ne coûte pas plus cher à envoyer. Un lot qui dépasse la limite est refusé avec un message qui la nomme, au lieu d’être silencieusement tronqué ; la limite borne le travail qu’une seule requête peut démarrer, non le total que vous pouvez effectuer ; répartissez donc un travail plus important sur plusieurs lots.
La recette paginate_through_listing s’arrête après 200 pages, quelle que soit la valeur de max_pages que vous lui passez, et signale partial: true lorsqu’elle s’arrête prématurément. Entre cette limite et sa limite max_items, un seul appel de pagination se termine toujours.
Une recette refuse une clé params qu’elle ne reconnaît pas, et le message liste les clés que cette recette accepte : un paramètre facultatif mal orthographié échoue donc bruyamment au lieu d’être abandonné, ce qui ferait répondre discrètement à l’appel à une autre question que celle que vous avez posée. Appelez mcp_recipes(name=...) pour connaître les clés d’une recette donnée.
Résultats orientés colonnes
Section intitulée « Résultats orientés colonnes »Un résultat volumineux dont toutes les lignes portent les mêmes champs est renvoyé orienté colonnes plutôt que sous forme de liste d’objets, de sorte que les noms de champs sont envoyés une seule fois au lieu d’une fois par ligne :
{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}La ligne i est dict(zip(cols, rows[i])). Les petits résultats, ainsi que tout résultat dont les lignes ne partagent pas un ensemble de champs identique, restent des tableaux d’objets ordinaires : les deux formes apparaissent donc, et le code qui lit directement ces réponses doit gérer chacune. L’enveloppe qui l’entoure est inchangée, et aucune valeur n’est convertie ni arrondie en chemin. Les agents sont informés de cette forme lorsqu’ils se connectent et la lisent sans que vous ayez à le leur demander ; le gain est d’environ 30 % des caractères et d’environ 15 % du budget de lecture d’un agent sur un trafic de listes typique, ce qui laisse du contexte pour votre véritable question. (Les deux chiffres diffèrent parce que les noms de champs répétés sont peu coûteux à lire pour un modèle ; le gain en caractères est toujours le plus élevé des deux.)
Pour le catalogue en direct, pointez votre agent vers le serveur et appelez mcp_introspect (sans argument) : il renvoie le nombre actuel d’outils, des résumés par domaine et les signatures des paramètres. Utilisez mcp_recipes pour des scénarios courants à plusieurs outils (pagination de grandes listes, instantané puis modification, ré-exécution d’une étape en échec, etc.).
Libellés et vues
Section intitulée « Libellés et vues »Chaque outil upsert qui définit des libellés, pour les tables, workflows, étapes, projets, dimensions, vues, éditeurs, UDF, connexions et entrepôts, prend deux paramètres : labels ajoute des libellés, et remove_labels les supprime. Les autres libellés de l’objet restent. Les suppressions s’appliquent avant les ajouts, de sorte qu’un seul appel peut renommer un libellé :
{"remove_labels": ["01"], "labels": ["001"]}Supprimer un libellé que l’objet n’a pas ne fait rien.
Les outils de vues fonctionnent avec les vues que vous voyez dans PlaidCloud :
view_findliste les vues, etview_describeen renvoie une par ID ou par nom.view_upsertcrée une vue ou en met une à jour sur place. Une mise à jour conserve l’ID et les libellés de la vue, et vous pouvez modifier uniquement ses libellés sans renvoyer la requête.view_organizesupprime, renomme, duplique et déplace des vues.- Écrivez les paramètres de requête sous forme de paramètres substituables
%(name)s.
Les vues partagent l’arborescence de dossiers des tables ; utilisez donc table_organize pour gérer leurs dossiers.
Créer des workflows avec des étapes natives
Section intitulée « Créer des workflows avec des étapes natives »Une fois vos données dans PlaidCloud, votre agent est orienté vers des étapes de table natives pour construire chaque transformation, à savoir Table Extract, les étapes de jointure, Table Melt, Table Union All et Table Lookup, plutôt que Extraire SQL. Une étape native substitue vos variables dans ses filtres et ses expressions, et PlaidCloud génère son SQL pour l’entrepôt de votre projet. Une étape Extraire SQL envoie sa requête à l’entrepôt telle qu’elle est écrite : elle ne substitue aucune variable, et son SQL est écrit pour un seul entrepôt.
Votre agent peut essayer une configuration Table Extract avec query_run(mode='config') (la configuration qu’il enregistrerait avec step_upsert) et voir ses lignes avant d’enregistrer l’étape. Lorsqu’il enregistre une étape Extraire SQL, step_upsert renvoie une entrée prefer_native_steps dans config_warnings qui nomme les étapes natives à utiliser à la place, et describe_step_operation porte la même note. Extraire SQL reste disponible pour ce qu’aucune étape native ne peut exprimer.
Lanceurs de tâches
Section intitulée « Lanceurs de tâches »Le serveur fournit un petit ensemble de lanceurs pour les tâches que les gens demandent par leur nom. Un client qui prend en charge les invites MCP les liste et les propose sous forme de menu (consultez la documentation de votre client pour savoir où il les place), ce qui vous permet de choisir la tâche plutôt que de décrire la séquence d’appels d’outils qu’elle suppose :
| Lanceur | Ce que vous lui fournissez |
|---|---|
| Importer un fichier CSV dans une table | Le fichier et, éventuellement, le projet, le dossier qui le contient et un nom pour la nouvelle table |
| Expliquer une variation de coût | La table de résultats et, éventuellement, le projet et les deux périodes |
| Déboguer un workflow en échec | Le workflow et, éventuellement, le projet |
| Explorer les données d’un projet | Ce que vous cherchez et, éventuellement, le projet |
Chacun est un message de départ, non une commande : votre agent le lit puis pilote lui-même les outils ; vous pouvez donc le modifier ou poursuivre la conversation à partir de là.
Importer un fichier sans connaître le modèle d’objets
Section intitulée « Importer un fichier sans connaître le modèle d’objets »Le lanceur d’importation est celui qui fait gagner le plus de travail, car la voie naïve exige quatre outils dans le bon ordre (trouver le compte de documents, parcourir jusqu’au fichier, créer la table cible, puis exécuter l’importation), et une mauvaise hypothèse sur l’un d’eux met fin au flux plusieurs appels plus loin.
Il lit du texte délimité : CSV, TSV et similaires. Un classeur Excel ou un fichier Parquet est rejeté plutôt que mal lu ; importez-les plutôt avec l’étape d’importation correspondante dans un workflow.
À la place, le scénario bulk_import_csv prend le compte par nom et le fichier par nom ou chemin :
mcp_recipe_run(name='bulk_import_csv', params={ 'project_id': '<project>', 'document_path': 'sales_2026.csv', 'document_account': 'Demo Data',})Il résout le compte en son identifiant, localise le fichier, crée la table avec les colonnes et les types lus dans le fichier lui-même, puis la charge : vous ne fournissez donc ni identifiant de compte ni spécification de colonnes. table_name correspond par défaut au nom du fichier sans son extension, et table_path à la racine du projet.
Indiquez le dossier lorsque vous le connaissez ('document_path': 'raw/sales_2026.csv') et la recherche y est confinée. Un fichier nommé dans un dossier n’est recherché que dans ce dossier : un fichier de même nom situé plus bas est proposé comme choix au lieu d’être importé à sa place.
Lorsqu’un argument est ambigu, le résultat pose la question au lieu de deviner :
{ "needs_choice": "document_account", "question": "More than one document account is named 'Archive'. Which one?", "candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]}Présentez les candidats à la personne que vous aidez, puis rappelez le scénario avec sa réponse, en renvoyant le candidat exactement tel qu’il a été donné. Lorsque le fichier est introuvable, la réponse liste les noms les plus proches et indique le nombre de fichiers parcourus, de sorte que « ce n’est pas là » puisse être distingué de « ce n’est pas là où j’ai cherché ».
Authentification
Section intitulée « Authentification »Le serveur MCP de PlaidCloud accepte deux modes d’authentification :
- OAuth 2.1 + PKCE via l’enregistrement dynamique de client (DCR). C’est ce qu’utilise l’interface de connecteur personnalisé de Claude.ai, et c’est aussi le mode par défaut du pont MCP de Claude Code. Le client s’enregistre lui-même et vous redirige vers la connexion Keycloak de PlaidCloud. Après votre connexion, PlaidCloud affiche une page Application Access Request qui nomme l’application et l’URI de redirection vers laquelle elle enverra les identifiants ; approuvez-la une fois par autorisation pour obtenir votre jeton. Il s’agit d’un contrôle de sécurité, non d’une formalité : vérifiez que le nom de l’application et l’URI de redirection correspondent au client auquel vous vous connectez réellement, et n’approuvez pas une demande que vous n’avez pas lancée.
- Jeton Bearer statique dans un en-tête
Authorization. Pour les environnements d’exécution d’agents qui n’ont pas de redirection de navigateur utilisable ou qui veulent un jeton de longue durée dans un fichier de configuration. PlaidCloud expose une page d’aide pour en générer un à votre place (voir ci-dessous).
Obtenir un jeton Bearer statique
Section intitulée « Obtenir un jeton Bearer statique »Ouvrez cette URL dans un onglet de navigateur où vous êtes déjà connecté à PlaidCloud :
https://<your-workspace>.plaid.cloud/mcp/setup/tokenLa page renvoie un extrait JSON prêt à coller dans la configuration MCP de votre agent. Chaque espace de travail a son propre extrait.
La durée de vie du jeton est régie par la politique de durée de vie des jetons d’accès de votre realm Keycloak (généralement de quelques heures à une journée). Pour l’actualiser, rechargez la même URL : votre session de navigateur génère à nouveau le jeton automatiquement.
Choisir un client
Section intitulée « Choisir un client »Le reste de cette section décrit la configuration pour des clients d’agents IA spécifiques :
- Claude Code : l’agent de codage d’Anthropic (CLI, extension VSCode, plug-in JetBrains).
- Claude Desktop et Claude.ai : l’application Claude grand public (bureau) et le web (
claude.ai) avec les « Custom Connectors ». - Cursor : l’éditeur de code natif IA.
- GitHub Copilot : le mode agent de Copilot dans VSCode.
- Google Gemini CLI :
gemini-cliet Gemini Code Assist. - ChatGPT : l’état actuel de la prise en charge et la solution de contournement recommandée.
- Grok : connexion des connecteurs personnalisés de Grok.
- Dépannage : erreurs courantes et manière de les corriger.