Power Automate via FlowStudio MCP — Foundation

Cette compétence est la couche de plomberie. Elle permet à un agent IA de communiquer de manière fiable avec un serveur FlowStudio MCP, de découvrir les outils disponibles et de traiter les réponses correctement. Les véritables narratives de flux se trouvent dans quatre compétences spécialisées qui s'appuient toutes sur celle-ci.

Exemples de débogage réels : Expression error in child flow | Data entry, not a flow bug | Null value crashes child flow

Prérequis : Un abonnement MCP FlowStudio (ou serveur Power Automate MCP compatible). Vous aurez besoin de :

• Point de terminaison MCP : https://mcp.flowstudio.app/mcp (identique pour tous les abonnés)
• Clé API / jeton JWT (en-tête x-api-key — NON Bearer)
• Nom de l'environnement Power Platform (par ex. Default-<tenant-guid>)

Quelle compétence utiliser et quand

Les compétences sont organisées par intention de cas d'usage, non par les outils qu'elles appellent. Plusieurs compétences réutilisent les mêmes outils sous-jacents — choisissez en fonction de ce que l'utilisateur essaie d'accomplir.

Mêmes outils, perspectives différentes. power-automate-build et power-automate-debug appellent tous deux update_live_flow, get_live_flow et les outils d'erreur d'exécution — ils diffèrent par la direction (avant vs arrière) et l'intention (composer vs diagnostiquer). power-automate-monitoring et power-automate-governance appellent tous deux les outils Store — ils diffèrent par l'audience (ops vs conformité) et le résultat (lire l'état vs écrire les métadonnées). N'essayez pas de mémoriser « quels outils appartiennent à quelle compétence » ; choisissez la compétence en fonction de ce que l'utilisateur fait.

Source de référence

Si la documentation contredit une réponse API réelle, l'API gagne. Les schémas d'outils de cette compétence (ou d'une autre) peuvent être en retard sur le serveur — appelez tool_search pour confirmer la forme actuelle avant d'invoquer un outil que vous n'avez pas utilisé récemment.

Comment les agents découvrent les outils

Le serveur FlowStudio MCP (v1.1.5+) expose deux méta-outils non facturables qui permettent à un agent de charger uniquement les outils pertinents pour la tâche actuelle. Utilisez-les de préférence à tools/list (qui charge tous les 30+ schémas à la fois) ou à deviner les noms d'outils.

Les lots tool_search du serveur sont intentionnellement plus étroits que cette famille de compétences — ce sont des paquets de démarrage des outils les plus susceptibles d'être nécessaires par intention. Une compétence de flux de travail (par ex. power-automate-debug) peut extraire un lot, puis appeler tool_search à nouveau pour des outils supplémentaires au fur et à mesure de la progression du flux.

# Démarrage à froid — choisir un lot par intention
skills = mcp("list_skills", {})
# [{"name": "debug-flow", "description": "Investigate why a flow is failing...",
#   "tools": ["get_live_flow_runs", "get_live_flow_run_error", ...]}, ...]

# Charger les schémas pour le lot
debug_tools = mcp("tool_search", {"query": "skill:debug-flow"})

Langage recommandé : Python ou Node.js

Tous les exemples de cette famille de compétences utilisent Python avec urllib.request (stdlib — pas besoin de pip install). Node.js est tout aussi valide : fetch est intégré à partir de Node 18+, la gestion JSON est native, et async/await mappe proprement sur le modèle requête-réponse des appels d'outils MCP — le rendant naturel pour les équipes travaillant déjà dans une pile JavaScript/TypeScript.

TL;DR — utilisez l'assistant Core MCP (Python ou Node.js) ci-dessous. Les deux traitent l'encadrement JSON-RPC, l'authentification et l'analyse des réponses dans une fonction réutilisable unique.

Assistant Core MCP (Python)

Utilisez cet assistant tout au long de tous les opérations ultérieures :

import json, urllib.request

TOKEN = "<YOUR_JWT_TOKEN>"
MCP   = "https://mcp.flowstudio.app/mcp"

def mcp(tool, args, cid=1):
    payload = {"jsonrpc": "2.0", "method": "tools/call", "id": cid,
               "params": {"name": tool, "arguments": args}}
    req = urllib.request.Request(MCP, data=json.dumps(payload).encode(),
        headers={"x-api-key": TOKEN, "Content-Type": "application/json",
                 "User-Agent": "FlowStudio-MCP/1.0"})
    try:
        resp = urllib.request.urlopen(req, timeout=120)
    except urllib.error.HTTPError as e:
        body = e.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"MCP HTTP {e.code}: {body[:200]}") from e
    raw = json.loads(resp.read())
    if "error" in raw:
        raise RuntimeError(f"MCP error: {json.dumps(raw['error'])}")
    text = raw["result"]["content"][0]["text"]
    return json.loads(text)

Erreurs d'authentification courantes :

• HTTP 401/403 → jeton manquant, expiré ou mal formé. Obtenez un JWT frais sur mcp.flowstudio.app.
• HTTP 400 → charge utile JSON-RPC mal formée. Vérifiez Content-Type: application/json et la structure du corps.
• MCP error: {"code": -32602, ...} → arguments d'outil incorrects ou manquants. Appelez tool_search avec select:<toolname> pour confirmer le schéma.

Assistant Core MCP (Node.js)

Assistant équivalent pour Node.js 18+ (fetch intégré — aucun paquet requis) :

const TOKEN = "<YOUR_JWT_TOKEN>";
const MCP   = "https://mcp.flowstudio.app/mcp";

async function mcp(tool, args, cid = 1) {
  const payload = {
    jsonrpc: "2.0",
    method: "tools/call",
    id: cid,
    params: { name: tool, arguments: args },
  };
  const res = await fetch(MCP, {
    method: "POST",
    headers: {
      "x-api-key": TOKEN,
      "Content-Type": "application/json",
      "User-Agent": "FlowStudio-MCP/1.0",
    },
    body: JSON.stringify(payload),
  });
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`MCP HTTP ${res.status}: ${body.slice(0, 200)}`);
  }
  const raw = await res.json();
  if (raw.error) throw new Error(`MCP error: ${JSON.stringify(raw.error)}`);
  return JSON.parse(raw.result.content[0].text);
}

Nécessite Node.js 18+. Pour Node plus ancien, remplacez fetch par https.request de la stdlib ou installez node-fetch.

Vérifier la connexion

Un test rapide en 3 lignes qui confirme que le jeton, le point de terminaison et l'assistant fonctionnent tous :

skills = mcp("list_skills", {})
print(f"Connected — {len(skills)} skill bundles available:",
      [s["name"] for s in skills])

Sortie attendue :

Connected — 5 skill bundles available: ['build-flow', 'debug-flow', 'monitor-flow', 'discover', 'governance']

Si cela échoue, consultez la note Erreurs d'authentification courantes ci-dessus. Si cela réussit, transmettez à la compétence de flux de travail correspondant à l'intention de l'utilisateur.

Gérer les réponses surdimensionnées

Certaines réponses d'outils MCP sont assez grandes pour déborder de la fenêtre de contexte de l'agent :

Quand le dispositif se déverse dans un fichier

Les harnais d'agent (Claude Code, VS Code Copilot, etc.) enregistrent les réponses surdimensionnées dans un fichier temporaire (par ex. tool-results/mcp-flowstudio-describe_live_connector-NNNN.txt) et retournent le chemin au lieu du JSON en ligne. Le fichier est doublement enveloppé — l'enveloppe MCP externe plus la charge utile JSON-échappée interne :

[{"type":"text","text":"<JSON-escaped payload>"}]

Deux analyses pour atteindre un objet utilisable :

import json
with open(path) as f:
    raw = json.loads(f.read())
payload = json.loads(raw[0]["text"])

$payload = ((Get-Content $path -Raw | ConvertFrom-Json)[0].text) | ConvertFrom-Json

Règles pratiques

1. Extraire, ne pas afficher. Extrayez les champs spécifiques dont vous avez besoin (un operationId, les sorties d'une action) et jetez le reste avant de raisonner à ce sujet.
2. Toujours passer actionName à get_live_flow_run_action_outputs. L'omettre récupère chaque action × chaque itération — bon pour les scripts de débogage hors ligne, dangereux pour un agent qui ingère la réponse entière.
3. Réutilisez le fichier débordement dans une session. Refetcher le même swagger de connecteur coûte 30+ secondes et produit un autre débordement — mettez en cache le chemin.
4. Ne faites pas grep du fichier débordement pour les clés JSON directement. Les chaînes sont JSON-échappées à l'intérieur du fichier (\"OperationId\":), donc un grep brut pour "OperationId": ne correspondra pas. Analysez d'abord, puis filtrez.
5. Résumez la sortie d'outil à l'utilisateur. Affichez name + state + trigger pour les listes de flux et actionName + status + code pour les erreurs d'exécution — pas JSON brut, sauf demande contraire.

# Bon — explorer une opération dans un swagger de connecteur
conn = mcp("describe_live_connector", {"environmentName": ENV, "connectorName": "shared_sharepointonline"})
op = conn["properties"]["swagger"]["paths"]["/datasets/{dataset}/tables/{table}/items"]["get"]
print(op["operationId"], "—", op.get("summary"))

# Mauvais — garder le swagger entier de 500 Ko en contexte
print(json.dumps(conn, indent=2))   # ne faites pas cela

Notes d'authentification et de connexion

Fichiers de référence

• MCP-BOOTSTRAP.md — point de terminaison, authentification, format requête/réponse (lisez ceci en premier)
• tool-reference.md — formes de réponse et notes comportementales (les paramètres sont dans tool_search)
• action-types.md — modèles de types d'actions Power Automate
• connection-references.md — guide de référence des connecteurs