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.

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.

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-06-18","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'

Le serveur s'identifie comme tale-platform. Lis result.protocolVersion puis envoie la valeur négociée dans MCP-Protocol-Version lors des appels suivants. L'exemple ci-dessous utilise 2025-06-18 ; remplace-la si l'initialisation a négocié l'ancienne révision. Une valeur d'en-tête non prise en charge renvoie 400.

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-06-18' \
  --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. Pour consulter les schémas des outils, envoie plutôt method: "tools/list". L'inventaire actuel compte 22 outils. Conserve l'id JSON-RPC pour associer chaque résultat à sa requête.

Transport et lots

Chaque appel d'outil 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.

Les outils

tools/list fournit le schéma d'entrée de chaque outil. Un argument manquant, vide, mal typé ou inattendu reçoit JSON-RPC -32602 avant exécution. 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 ou modifier un déclencheur peut remplacer un état existant. Les exécutions réelles peuvent joindre de vrais services.

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

Gestion des exécutions & déclencheurs

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.

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 connecteurs, ni skills, ni serveurs MCP externes. Appeler une automatisation déployée correspond à la même opération réelle que run_deployed. Si une approbation est nécessaire, le résultat pending permet au client d'expliquer qu'une personne doit décider avant la poursuite.

Ce que la clé peut faire

La clé identifie son titulaire ; elle n'élargit ni son rôle ni son accès aux projets. Les appels réels via invoke_capability passent aussi par les contrôles d'exécution.

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

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