Endpoint MCP

Connecte un client MCP lorsqu'un agent doit découvrir les outils Tale, récupérer des connaissances ou concevoir et exécuter des automatisations. La connexion utilise la même clé API et le même périmètre d'organisation que REST. Tale joue le rôle de serveur : ton client externe appelle Tale.

Commence par initialize, consulte tools/list, puis appelle get_docs avant d'écrire une automatisation. L'installation fournit sa propre grammaire prise en charge ; le client n'a donc pas à inventer des types de nœuds ou des champs.

Connecter un client

Préparer la connexion

Crée une clé API et conserve-la dans la configuration sécurisée de ton client. La page Paramètres > API > MCP affiche le point d'accès, le slug d'organisation et une requête de découverte à copier.

Le client doit accepter un point d'accès HTTP distant avec des en-têtes personnalisés. Il n'y a ni flux SSE, ni session à supprimer, ni parcours d'autorisation OAuth. Les URL de découverte OAuth renvoient du JSON avec 404 ; un client qui exige ce parcours doit être configuré autrement. Un client limité aux serveurs stdio locaux ne peut pas utiliser directement cette URL. Utiliser Tale depuis ton éditeur ou un script fournit des configurations prêtes pour opencode et Claude Code.

Envoie toujours l'en-tête d'organisation dans une intégration réutilisable. Il n'est facultatif que si le titulaire de la clé appartient à une seule organisation. Avec plusieurs appartenances, son absence produit 400 ORG_SLUG_REQUIRED. Un slug inconnu produit 404 ORG_SLUG_INVALID, et une organisation dont le titulaire n'est pas membre produit 403 ORG_FORBIDDEN. Chacun de ces refus liste dans data.organizations les slugs que tu peux envoyer.

Initialiser et récupérer la référence

Les exemples supposent que TALE_URL, TALE_API_KEY et TALE_ORG_SLUG sont déjà définis dans ton environnement. TALE_URL est l'origine de l'application, sans /api/v1.

curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'

Le serveur s'identifie comme tale-platform et indique la version du contrat d’API dans serverInfo.version. Ses instructions sont un court guide pour travailler avec Tale, que ton client peut transmettre à son modèle. Lis result.protocolVersion puis envoie la valeur négociée dans MCP-Protocol-Version lors des appels suivants. L'exemple ci-dessous utilise 2025-11-25 ; remplace-la si l'initialisation a négocié une révision plus ancienne. Une révision que le point d’accès ne parle pas renvoie 400 avec JSON-RPC -32022, et data.supported liste celles qu’il parle.

curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2025-11-25' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_docs","arguments":{}}}'

Un résultat get_docs réussi contient la référence des automatisations en texte et ne porte pas d'indicateur d'erreur. Ajoute "arguments":{"topic":"triggers"} pour la référence des déclencheurs (les champs de chaque type de déclencheur, l’entrée avec laquelle ses exécutions démarrent et les événements), "validation" pour lire un résultat de validation et connaître chaque code d’erreur, "settings" pour chaque type de paramètre avec ses champs (Paramètres par MCP), ou "skill" pour le skill Tale. Pour consulter les schémas des outils, envoie plutôt method: "tools/list". Conserve l'id JSON-RPC pour associer chaque résultat à sa requête.

Transport et lots

Chaque appel d'outil, lecture ou liste de ressources ou prompt supplémentaire d'un lot consomme le même budget qu'un appel séparé. Si le lot épuise son budget, l'entrée refusée contient JSON-RPC -32000 avec data.retryAfterMs. La réponse HTTP reste 200, sans Retry-After. Une requête unique refusée à l'entrée HTTP reçoit le 429 REST. Gère les deux cas selon les limites de débit.

Le point d'accès ne fournit pas d'en-têtes CORS pour utiliser une clé dans une page web. Conserve la clé sur un serveur de confiance ou dans le stockage d'identifiants du client MCP. Une requête dont l’en-tête Origin nomme un site que le déploiement n’accepte pas est journalisée, et refusée avec 403 ORIGIN_FORBIDDEN là où l’opérateur impose cette vérification (référence de l’environnement). Les agents de code lancés dans un terminal n’envoient pas d’Origin.

Révisions du protocole

Le point d’accès sert deux générations du protocole sur la même URL avec la même clé, et décide pour chaque requête de laquelle il s’agit. Un client qui parle 2026-07-28 n’envoie pas d’initialize : chaque requête porte sa révision et les capacités du client, si bien que rien n’est conservé d’une requête à l’autre.

Une requête est servie selon 2026-07-28 quand son _meta nomme une révision ou que son en-tête MCP-Protocol-Version vaut 2026-07-28. Ses en-têtes doivent reprendre ce que dit le corps. Si un en-tête manque, ou s’il nomme une autre révision, une autre méthode, un autre outil, un autre prompt ou une autre adresse, la requête est refusée avec HTTP 400 et JSON-RPC -32020 avant que quoi que ce soit ne s’exécute. Envoie une valeur de Mcp-Name qui n’est pas en ASCII simple sous la forme =?base64?<texte UTF-8 en Base64>?=. Si _meta manque ou est mal formé, le point d’accès répond -32602 avec HTTP 400 et nomme les entrées concernées dans data.missing ou data.malformed.

curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"docs-client","version":"1.0.0"}}}}'

La réponse liste toutes les révisions dans supportedVersions et contient les mêmes capacités et instructions qu’initialize, avec le serveur sous _meta. ttlMs indique combien de temps ton client peut réutiliser une réponse : une heure pour server/discover, les listes d’outils, de prompts et de modèles d’adresse, et les références ; une minute pour resources/list et le catalogue des connecteurs ; 0 pour une automatisation ou une exécution, car elles peuvent changer dès le prochain enregistrement de ton agent. Chaque réponse appartient à la clé qui l’a demandée ; un cache ne doit donc jamais la partager avec une autre clé. Le nom indiqué dans io.modelcontextprotocol/clientInfo est enregistré avec chaque appel et avec les modifications qu’il apporte, si bien qu’une version enregistrée par un agent nomme le client qui l’a enregistrée.

Les outils

tools/list fournit le schéma d'entrée de chaque outil, et un outil de lecture décrit aussi sa réponse dans outputSchema. Les arguments sont vérifiés avant exécution : un argument manquant, vide, mal typé ou inattendu est refusé par un seul résultat d’outil marqué isError, dont le code est INVALID_ARGUMENTS et dont data.issues liste chaque problème avec son path, son code et son message. Le refus ne répète jamais la valeur d’un argument. Chaque résultat porte sa réponse sous forme de texte JSON compact, et la réponse réussie d’un outil de lecture arrive aussi comme structuredContent, le même objet. Le document passé à validate_automation, run_automation, test_automation ou save_automation garde volontairement une enveloppe ouverte : get_docs en explique la grammaire et le moteur valide son contenu.

Les outils exposent aussi readOnlyHint, destructiveHint, idempotentHint et openWorldHint. Un hôte peut s'en servir pour expliquer un appel, mais ces indications n'accordent aucun droit et ne garantissent pas sa sûreté. Les lectures sont marquées comme telles ; enregistrer écrit une version ; déployer, supprimer, installer, modifier un déclencheur ou modifier les paramètres peut remplacer un état existant. Les exécutions réelles et certaines modifications de paramètres peuvent joindre de vrais services. Mettre en service, supprimer, définir un déclencheur, installer une automatisation dans des projets, répondre à la question d’une exécution et modifier les paramètres portent aussi _meta["anthropic/requiresUserInteraction"] : un client qui en tient compte demande à la personne avant chacun de ces appels.

Écriture

Suis cet ordre : lire la grammaire et le catalogue, valider le document, l'exécuter avec les mocks, lancer ses tests d'acceptation, enregistrer une version, puis la déployer. Un test simulé réussi vérifie le chemin simulé. Il ne valide ni les identifiants du fournisseur, ni le réseau, ni les effets réels.

Enregistrer sans perdre de travail

Une version porte, à côté du document, le formulaire settings qu’affiche une tâche, le taskContract et la presentation dans la liste des automatisations. Un enregistrement qui en omet un garde celui de la dernière version ; null n’en enregistre aucun (pour presentation, la liste continue alors d’afficher la plus récente des précédentes) ; une valeur est vérifiée avec le schéma par lequel l’application la lit, et refusée comme INVALID_ARGUMENTS avec chaque problème quand elle ne convient pas. carried dans la réponse nomme ce qui a été gardé.

Passe baseVersion, la version dont ta modification est partie. Si quelqu’un a enregistré une version plus récente entre-temps, l’enregistrement est refusé avec AUTOMATION_VERSION_STALE et data.latestVersion ; lis cette version, reporte ta modification et enregistre à nouveau. Sans baseVersion, la version s’ajoute, et baseVersionChecked: false indique que la vérification a été sautée. Enregistre une nouvelle automatisation avec create: true : un nom qui existe déjà est refusé (AUTOMATION_NAME_TAKEN), pour qu’une nouvelle automatisation ne devienne jamais une version d’une autre. Un enregistrement est refusé de la même façon, avec ou sans create, quand le nom appartient à une automatisation que tu ne peux pas voir. projectId installe une nouvelle automatisation, avec sa première version, dans un projet que tu peux modifier ; l’enregistrement d’une automatisation existante l’ignore.

Comparer, restaurer et revenir en arrière

Chaque enregistrement ajoute une version dont le document et les données du paquet restent inchangés tant qu’elle est conservée. La suppression de l’automatisation ou une politique de conservation peut retirer des versions ; seule une version conservée peut être lue, comparée et restaurée. Sans limit, list_versions répond avec toutes les versions conservées, les plus récentes d’abord. Avec limit, la réponse est une page, et nextBefore est le before de la suivante. Chaque ligne dit qui a enregistré la version, par quel accès et avec quel client, de quelle version elle part et laquelle elle restaure, ce qu’elle a changé, comment ses tests se sont passés et si elle est en service.

Regarde ce qu’une version change avant de la déployer. get_automation avec against répond avec la version et, à côté, un diff par rapport à une autre : "previous" (celle enregistrée juste avant, par défaut), "deployed" (celle en service), "latest" ou un numéro. Le diff liste ce qui a changé nœud par nœud, dans le schéma de l’entrée, la sortie, la description et les tests ; avec diffFormat: "unified", la réponse est à la place un patch sur le YAML des deux versions, et avec "both" les deux.

Pour revenir en arrière, les deux voies laissent l’historique intact. save_automation avec name et restoreVersion enregistre le contenu d’une ancienne version comme version la plus récente, après les vérifications et les tests de tout enregistrement ; la version en service le reste. Quand la dernière version a déjà ce contenu, rien n’est enregistré et la réponse indique unchanged: true. deploy_automation d’une version plus ancienne fait revenir la version en service en arrière : la réponse porte kind: "rollback" et la previousVersion à redéployer. Passe expectedDeployedVersion pour qu’une mise en service n’annule jamais celle d’un collègue.

Essayer un brouillon et lancer des tests

run_automation exécute un document que tu n’as pas enregistré, avec les mocks déterministes : rien ne quitte Tale et rien n’est conservé. À côté de input, il accepte ce qu’utilisent aussi les tests et le test d’un seul nœud dans l’éditeur :

• mocks associe à l’identifiant d’un nœud une sortie simulée qui prend la place de son appel — celui d’un connecteur, d’un modèle, d’un agent, d’une automatisation appelée ou du code du nœud. L’entrée du nœud est tout de même calculée et son effet noté : l’exécution montre donc ce que le nœud enverrait. Pour un nœud qui s’exécute une fois par élément (forEach), donne une liste avec une sortie par élément.
• failures associe à l’identifiant d’un nœud un message avec lequel il échoue — tu vois ainsi ce que fait le reste de l’automatisation.
• upTo exécute un nœud et tout ce dont il a besoin, et laisse le reste de côté.
• only exécute un seul nœud, seul, sur les données que tu fixes dans mocks pour chaque nœud qu’il lit ; item choisit un élément d’un nœud forEach exécuté ainsi, en comptant à partir de 0.

La réponse dit où l’exécution s’est placée (focus) et quelles sorties simulées elle n’a jamais utilisées (unusedMocks), parce que leur nœud a été ignoré, laissé de côté ou jamais atteint. Des sorties simulées ou une portée que le document ne peut pas accepter sont refusées avec BENCH_INVALID — un nœud que le document n’a pas (le refus nomme le plus proche), ou des portées qui ne se combinent pas, comme item sans only — avec l’explication du moteur sous data.issue. Une sortie simulée de plus de 64 Ko, ou plusieurs de plus de 512 Ko ensemble, sont refusées avec INVALID_ARGUMENTS. Une exécution est arrêtée avant son étape suivante dès qu’elle a duré 20 secondes, et répond avec stoppedBy: "time_limit".

test_automation exécute les tests du bloc tests: du document, ceux que l’éditeur exécute. Sans tests, il les exécute tous ; avec une liste de noms, seulement ceux-là, par le nom que le document donne à chacun. Un nom qu’aucun test ne porte est refusé avec INVALID_PARAMS et les noms qui existent ; un nom que plusieurs tests portent l’est aussi, avec les places où ils se trouvent. Chaque résultat dit si son test a réussi et, pour un test qui a échoué, ce qui différait et où (failures). detail ajoute à chaque résultat ce que son exécution a renvoyé ("output"), aurait fait ("effects") et traversé ("trace", l’exécution étape par étape). Une exécution de plus de 256 Ko, ou des exécutions de plus de 384 Ko ensemble, sont omises et marquées detailOmitted ; lance alors ce test seul. Un test s’arrête au bout de 10 secondes, une suite au bout de 60.

La suite complète d’une version enregistrée, menée jusqu’au bout, est notée sur la version comme son verdict, établi à la main : la réponse dit recorded, et list_versions l’affiche. Une partie de la suite, un brouillon et une suite dont le temps est écoulé ne notent rien.

Les deux s’exécutent dans Tale et consomment le budget de l’organisation pour les exécutions jamais conservées, une unité par exécution ou par test — le budget que consomment aussi les essais et les tests lancés dans l’application —, en plus du budget d’exécution du détenteur de la clé. Quand l’un des deux est épuisé, ou que le serveur en exécute déjà autant qu’il peut, l’appel est refusé avec RATE_LIMITED et data.retryAfterMs.

Lire un résultat de validation

validate_automation répond avec valid, errors, warnings, analysis et types. Les erreurs empêchent d’enregistrer et de déployer, les avertissements jamais. save_automation renvoie les warnings de la version enregistrée, et un enregistrement refusé indique ses warnings à côté de ses errors : tu découvres ainsi les deux pendant ton travail.

analysis.nodes.<id> indique si un nœud est atteignable (reachable), s’il s’exécute toujours (alwaysRuns), comment il peut être ignoré (maySkip) et si son échec arrête l’exécution (failureHandling: "halts") ou la laisse continuer ("continues"). analysis.paths liste les chemins que peut prendre une exécution réussie — jusqu’à 32, avec count pour le total — et nomme les nœuds dont l’échec termine une exécution. types donne le JSON Schema de l’entrée de l’exécution, de la sortie de chaque nœud et du résultat de l’automatisation ; get_catalog donne de la même façon l’outputSchema de chaque capacité. Ce que Tale vérifie avant une exécution explique chaque famille de vérifications.

detail choisit ce qui accompagne les problèmes : ["analysis"], ["types"] ou [] pour les problèmes seuls ; sans detail, tu reçois les deux. Certains avertissements ne vérifient pas le document, ils le comparent à ton organisation : un skill qu’aucune exécution de l’automatisation ne peut atteindre (SKILL_UNKNOWN), un connector que personne n’a connecté (CONNECTOR_NOT_CONNECTED), un secret que personne n’a enregistré (SECRET_UNKNOWN, signalé seulement aux rôles Propriétaire, Admin et Développeur), un environnement d’agent que ce déploiement ne peut pas exécuter (HARNESS_UNKNOWN) et un déclencheur d’événement qui attend un événement que Tale n’émet pas (EVENT_UNKNOWN). Ils n’empêchent jamais d’enregistrer ; les outils de découverte listent ce qui existe.

Gestion des exécutions & déclencheurs

Pour corriger une exécution échouée, lis-la avec get_run {runId, include: ["record"]} : le failure.reason de l’étape échouée nomme ce qui n’a pas fonctionné et son explication montre les valeurs que l’expression a lues. get_run_node lit cette étape en entier. Corrige le document, essaie-le avec run_automation sur l’entrée de l’exécution et, une fois une nouvelle exécution terminée, compare_runs montre où elle a pris un autre chemin.

Les deux outils de version déployée utilisent le même moteur durable, avec les mêmes contrôles d'accès et traces d'exécution. start_run accepte un projectId facultatif. Une automatisation liée à des projets doit s'exécuter dans un projet où elle est installée ; une liaison unique peut être choisie automatiquement. Sans liaison, omettre le champ sélectionne le périmètre de l'organisation. Lis projectIds dans list_automations et le véritable projectId du résultat au lieu de deviner l'URL REST de suivi.

Découverte

Chaque réponse porte un hint qui nomme l’outil ou le paramètre qui la fait changer.

Paramètres

Une modification indique son type (kind), l’id de la ressource (absent pour un type qui n’a qu’une ressource) et son opération (op) : set remplace la ressource par toute la config et la crée si elle n’existe pas ; delete la supprime ; act lance une des actions du type, avec ses args. Planifie d’abord, montre le plan à la personne, puis applique les mêmes modifications : apply_settings demande à la personne avant chaque appel et dispose de son propre budget.

Paramètres par MCP liste chaque type de paramètre, qui peut le modifier et ce qui reste dans Tale.

Aucun secret ne passe par ces outils. Un secret enregistré se lit {"masked": true, "preview": "…"} ; renvoie cette valeur telle quelle pour le garder. Une modification qui porte une autre valeur à la place d’un secret, ou des identifiants n’importe où dans sa configuration, est refusée avec SECRET_ARGUMENT_REFUSED ; une personne saisit un nouveau secret dans Tale.

Capacités & connaissances

Le registre de capacités contient actuellement les automatisations déployées. Il n'inclut ni outils intégrés, ni actions de connectors, ni skills, ni serveurs MCP externes. Appeler une automatisation déployée correspond à la même opération réelle que run_deployed et attend de la même façon jusqu’à 30 secondes la fin de l’exécution. Si une étape demande une approbation, l’exécution attend qu’une personne décide dans Tale : l’output de la réponse est l’exécution avec status: "waiting", et get_run indique waitingFor: "approval". Aucun outil ne l’approuve ni ne la rejette ; ton client doit donc prévenir la personne plutôt que réessayer. Arrêter l’exécution avec cancel_run retire l’approbation.

Ressources et prompts

En plus des outils, le point d’accès sert des ressources, qu’un client lit par leur adresse, et des prompts : des requêtes prêtes à l’emploi par lesquelles une personne commence un travail. Les deux lisent ce qu’un outil renvoie déjà, pour la même personne et avec les mêmes contrôles.

Lire par adresse

resources/list nomme d’abord les ressources fixes, puis chaque automatisation que le titulaire de la clé peut voir, 100 par page ; suis nextCursor pour la page suivante. resources/templates/list renvoie les modèles d’adresse, et resources/read le contenu d’une ressource.

Écris chaque / d’un nom d’automatisation sous la forme %2F : tale://automations/billing%2Fdunning. Une adresse qui ne trouve rien renvoie JSON-RPC -32002 (-32602 en 2026-07-28) avec le code du refus dans data.code, par exemple AUTOMATION_NOT_FOUND. Une automatisation que le titulaire de la clé ne peut pas voir renvoie la même erreur qu’une automatisation qui n’existe pas. Une adresse mal formée, par exemple une version qui n’est pas un nombre, renvoie -32602.

Partir d’un prompt

prompts/list nomme trois prompts, et prompts/get renvoie le message avec, en pièce jointe sous forme de ressource, ce dont il traite. Claude Code les affiche sous la forme /tale:edit_automation, et ainsi de suite.

Chaque argument est un seul mot, car des clients comme Claude Code séparent les arguments aux espaces. Un argument envoyé vide compte comme omis. Un prompt dont l’exécution ou l’automatisation n’est pas lisible par le titulaire de la clé renvoie -32602 avec le code de cette lecture.

Ce que la clé peut faire

La clé identifie son titulaire ; elle n'élargit ni son rôle ni son accès aux projets. Une automatisation installée uniquement dans des projets que le titulaire de la clé ne peut pas lire n’apparaît pas dans list_automations, et toute lecture de celle-ci répond AUTOMATION_NOT_FOUND, comme pour une automatisation qui n’existe pas. Les appels réels via invoke_capability passent aussi par les contrôles d'exécution.

Chaque modification qu’un appel MCP apporte à une automatisation — une version enregistrée, une mise en service, une suppression, un déclencheur défini ou retiré, une installation ajoutée ou retirée — figure dans le journal d’audit de l’organisation, marquée comme venue par MCP, avec l’outil et la clé API. Dans le détail de l’événement, Source affiche Agent de code, et Client nomme l’application de l’agent quand elle se nomme à chaque appel, comme en révision 2026-07-28 ; une application en révision 2025 ne se nomme qu’à initialize, et ses événements n’affichent donc pas de Client (Journaux d’audit).

Avant de configurer des outils privilégiés, lis GET /api/v1/me : capabilities.developer indique le droit lié au rôle actuel. deploymentEditor correspond à une liste opérateur distincte et n’autorise pas la création par MCP. Les erreurs d’outils gardent le format MCP décrit ci-dessous ; la lecture d’une capacité REST ne change pas leur traitement JSON-RPC.

Distinguer une erreur de protocole d'un refus d'outil

Les codes de refus comprennent AUTOMATION_NOT_FOUND, AUTOMATION_VERSION_UNKNOWN, AUTOMATION_NOT_DEPLOYED, RUN_NOT_FOUND, AUTOMATION_INVALID, AUTOMATION_TESTS_FAILING, AUTOMATION_VERSION_STALE, AUTOMATION_DEPLOYMENT_STALE, AUTOMATION_NAME_TAKEN, AUTOMATION_HAS_ACTIVE_RUNS, AUTOMATION_NOT_INSTALLED, HUMAN_ASK_NOT_FOUND, HUMAN_ASK_NOT_PENDING, HUMAN_ASK_EXPIRED, EMPTY_ANSWER, INVALID_CURSOR, BENCH_INVALID, LIVE_MODE_UNAVAILABLE et NOT_SUPPORTED. Ce dernier indique que l'hôte ne prend pas en charge l'opération sur les exécutions, versions ou déclencheurs. start_run refuse un idempotencyKey réutilisé avec d’autres arguments par IDEMPOTENCY_KEY_REUSED ; invoke_capability refuse un id que le registre ne tient pas — une automatisation seulement enregistrée n’y est pas — par CAPABILITY_NOT_FOUND et une entrée que son schéma rejette par CAPABILITY_INPUT_INVALID ; get_knowledge transmet les codes propres de la porte des connaissances (KNOWLEDGE_UNAVAILABLE quand la recherche elle-même a échoué). Les erreurs de plateforme conservent leur code, leur conseil et leurs données éventuelles ; par exemple, l'absence d'accès développeur renvoie FORBIDDEN_DEVELOPER_SETTINGS. INVALID_ARGUMENTS liste chaque problème d’argument ; une valeur hors d’un ensemble énuméré est refusée et le message nomme l’ensemble. RATE_LIMITED signifie que l’outil avait besoin d’une exécution, ou d’une modification de paramètres, et que le budget du détenteur de la clé pour celle-ci est épuisé : attends data.retryAfterMs. run_automation et test_automation sont refusés de la même façon quand le budget de l’organisation pour les exécutions jamais conservées est épuisé. INTERNAL_ERROR signifie que l’appel a échoué de façon inattendue ; communique son data.requestId à l’équipe qui exploite le déploiement. Les outils de paramètres ajoutent SETTINGS_STALE (une ressource a changé depuis ta lecture ; data.currentHash est son hash actuel), SECRET_ARGUMENT_REFUSED (une modification portait un secret ; data.places dit où, jamais quoi), SETTINGS_KIND_UNAVAILABLE (ce déploiement ne sert pas ce type par MCP), SETTINGS_NOT_FOUND (une action sur une ressource qui n’existe pas) et SETTINGS_DUPLICATE (une ressource modifiée deux fois dans un même appel).

Un nom d'automatisation inconnu est aussi une erreur pour list_versions, list_runs et list_triggers. Une liste vide signifie qu'une automatisation existante n'a pas d'éléments correspondants. La seule exception est l’historique des exécutions : une automatisation supprimée conserve ses exécutions, list_runs {name} les renvoie donc tant qu’elles existent, et seul un nom qui n’a jamais tourné donne AUTOMATION_NOT_FOUND. get_catalog restreint à un type de nœud de base (transform, llm, agent, subautomation) répond une liste vide accompagnée d’un hint renvoyant à get_docs, comme le fait search_catalog, et de la section de la référence consacrée à ce type de nœud sous reference. Un document invalide soumis à un outil qui exige un document valide, une recherche échouée ou un déploiement absent produisent isError: true. Seul l'outil de validation présente un document invalide comme son verdict normal.

Où ça se place

REST et MCP partagent les clés, le périmètre d'organisation et les objets d'exécution durables. Choisis REST pour des routes HTTP explicites, et MCP pour un client capable de découvrir et d'appeler des outils. Tale n'enregistre ni n'appelle de serveurs MCP externes par ce point d'accès.