Depuração do Power Automate com FlowStudio MCP

Um processo de diagnóstico passo a passo para investigar fluxos de nuvem do Power Automate que falham através do servidor FlowStudio MCP.

Exemplos reais de depuração: Erro de expressão em fluxo filho | Entrada de dados, não um bug do fluxo | Valor nulo trava fluxo filho

Pré-requisito: Um servidor FlowStudio MCP deve ser acessível com um JWT válido. Consulte a habilidade flowstudio-power-automate-mcp para configuração da conexão. Inscreva-se em https://mcp.flowstudio.app

Fonte da Verdade

Sempre chame list_skills / tool_search primeiro para confirmar os nomes de ferramentas disponíveis e os esquemas de parâmetros. Nomes de ferramentas e parâmetros podem mudar entre versões do servidor. Esta habilidade abrange formas de resposta, notas de comportamento e padrões de diagnóstico — coisas que os esquemas de ferramentas não podem lhe dizer. Se este documento discordar de tool_search ou de uma resposta real da API, a API prevalece.

Auxiliar Python

import json, urllib.request

MCP_URL   = "https://mcp.flowstudio.app/mcp"
MCP_TOKEN = "<YOUR_JWT_TOKEN>"

def mcp(tool, **kwargs):
    payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
                          "params": {"name": tool, "arguments": kwargs}}).encode()
    req = urllib.request.Request(MCP_URL, data=payload,
        headers={"x-api-key": MCP_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'])}")
    return json.loads(raw["result"]["content"][0]["text"])

ENV = "<environment-id>"   # e.g. Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Passo 1 — Localizar o Fluxo

result = mcp("list_live_flows", environmentName=ENV)
# Returns a wrapper object: {mode, flows, totalCount, error}
target = next(f for f in result["flows"] if "My Flow Name" in f["displayName"])
FLOW_ID = target["id"]   # plain UUID — use directly as flowName
print(FLOW_ID)

Passo 2 — Encontrar a Execução Falha

runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=5)
# Returns direct array (newest first):
# [{"name": "08584296068667933411438594643CU15",
#   "status": "Failed",
#   "startTime": "2026-02-25T06:13:38.6910688Z",
#   "endTime": "2026-02-25T06:15:24.1995008Z",
#   "triggerName": "manual",
#   "error": {"code": "ActionFailed", "message": "An action failed..."}},
#  {"name": "...", "status": "Succeeded", "error": null, ...}]

for r in runs:
    print(r["name"], r["status"], r["startTime"])

RUN_ID = next(r["name"] for r in runs if r["status"] == "Failed")

Passo 3 — Obter o Erro de Nível Superior

CRÍTICO: get_live_flow_run_error informa qual ação falhou. get_live_flow_run_action_outputs informa por quê. Você deve chamar AMBOS. Nunca pare apenas no erro — códigos de erro como ActionFailed, NotSpecified e InternalServerError são wrappers genéricos. A causa raiz real (campo incorreto, valor nulo, corpo HTTP 500, stack trace) só é visível nas entradas e saídas da ação.

err = mcp("get_live_flow_run_error",
    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID)
# Retorna:
# {
#   "runName": "08584296068667933411438594643CU15",
#   "failedActions": [
#     {"actionName": "Apply_to_each_prepare_workers", "status": "Failed",
#      "error": {"code": "ActionFailed", "message": "An action failed..."},
#      "startTime": "...", "endTime": "..."},
#     {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed",
#      "code": "NotSpecified", "startTime": "...", "endTime": "..."}
#   ],
#   "allActions": [
#     {"actionName": "Apply_to_each", "status": "Skipped"},
#     {"actionName": "Compose_WeekEnd", "status": "Succeeded"},
#     ...
#   ]
# }

# failedActions está ordenado de fora para dentro. A causa RAIZ é a ÚLTIMA entrada:
root = err["failedActions"][-1]

…