power-automate-build

FlowStudio MCP で Power Automate フローを構築・デプロイする

FlowStudio MCP サーバーを使用して、Power Automate クラウドフローを プログラムで構築・デプロイするためのステップごとのガイドです。

前提条件：有効な JWT で FlowStudio MCP サーバーに接続できる必要があります。 接続の設定については、power-automate-mcp スキルを参照してください。 https://mcp.flowstudio.app で登録してください。

ワークフロー：

1. 現在のビルドツールを読み込む。
2. 既存のフローを確認する。
3. 接続参照を解決する。
4. 定義を構築する。
5. デプロイする。
6. 検証する。
7. テストする。

---

信頼できる情報源

最初に必ず list_skills / tool_search を呼び出し、利用可能なツール 名とパラメータスキーマを確認してください。ツール名やパラメータは サーバーのバージョンによって変わる場合があります。 このスキルでは、レスポンスの形式、動作に関する注意事項、ビルドパターンなど、 ツールスキーマからは分からない内容を説明します。このドキュメントの内容が tool_search または実際の API レスポンスと異なる場合は、API を優先してください。

---

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

---

0. 現在のビルドツールを読み込む

新しいフローを作成する場合は、サーバーの create-flow バンドルを読み込みます。 既存のフローを編集する場合は、build-flow を読み込みます。これにより、JSON を構築する前に エージェントが MCP サーバーの現在のスキーマに沿った状態になります。

schemas = mcp("tool_search", query="skill:create-flow")
# Includes list_live_environments, list_live_connections,
# describe_live_connector, get_live_dynamic_options, update_live_flow.

バンドルに含まれていないツールが必要な場合は、明示的に読み込みます。

mcp("tool_search", query="select:get_live_dynamic_properties")

---

1. 安全性の確認：フローはすでに存在しますか？

重複を避けるため、構築する前に必ず確認してください。

results = mcp("list_live_flows",
    environmentName=ENV,
    mode="owner",
    search="My New Flow",
    top=20)

# list_live_flows returns { "flows": [...], "mode": "...", ... }
matches = [f for f in results["flows"]
           if "My New Flow".lower() in f["displayName"].lower()]

if len(matches) > 0:
    # Flow exists — modify rather than create
    FLOW_ID = matches[0]["id"]   # plain UUID from list_live_flows
    print(f"Existing flow: {FLOW_ID}")
    defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
else:
    print("Flow not found — building from scratch")
    FLOW_ID = None

非常に大規模な環境では、list_live_flows が継続 URL を返すことがあります。 次のバッチを取得するには、同じ mode とともに continuationUrl として渡してください。 ユーザーが環境内のすべてのフローを必要としており、MCP ID に管理者権限がある場合に限り、 mode="admin" を使用してください。

---

2. 接続参照を取得する

すべてのコネクタアクションには、フローの connectionReferences マップ内のキーを 指す connectionName が必要です。このキーは、環境内の認証済み接続に紐づいています。

必須：最初に必ず list_live_connections を呼び出してください。接続名や GUID を ユーザーに尋ねてはいけません。API から必要な値が正確に返されます。 必要な接続が存在しないことを API が確認した場合に限り、ユーザーに確認してください。

2a — アクティブな接続を探す

conns = mcp("list_live_connections", environmentName=ENV)
active = [c for c in conns["connections"]
          if c["statuses"][0]["status"] == "Connected"]
conn_map = {c["connectorName"]: c["id"] for c in active}

使用するコネクタが決まっている場合は、search を渡すと出力を絞り込み、 貼り付けて使える connectionReferenceTemplate と hostTemplate の値を取得できます。

sp_conns = mcp("list_live_connections",
    environmentName=ENV,
    search="shared_sharepointonline")

2b — フローに必要なコネクタを特定する

一般的なコネクタの API 名：SharePoint shared_sharepointonline、Outlook shared_office365、Teams shared_teams、Approvals shared_approvals、 OneDrive shared_onedriveforbusiness、Excel shared_excelonlinebusiness、 Dataverse shared_commondataserviceforapps、Forms shared_microsoftforms。

Recurrence + Compose + HTTP のみなど、コネクタを必要としないフローでは、 connectionReferences を省略できます。

2c — 接続がない場合はユーザーを案内する

connectors_needed = ["shared_sharepointonline", "shared_office365"]  # adjust per flow
missing = [c for c in connectors_needed if c not in conn_map]
if missing:
    # STOP: connections require browser OAuth consent.
    # Ask the user to create the missing connector connections in the
    # selected environment, then re-run list_live_connections.
    raise Exception(f"Missing active connections: {missing}")

2d — connectionReferences ブロックを構築する

connection_references = {}
host_templates = {}
for connector in connectors_needed:
    c = next(c for c in active if c["connectorName"] == connector)
    connection_references[connector] = c.get("connectionReferenceTemplate") or {
        "connectionName": c["id"],   # the connection id from list_live_connections
        "source": "Invoker",
        "id": f"/providers/Microsoft.PowerApps/apis/{connector}"
    }
    host_templates[connector] = c.get("hostTemplate") or {
        "connectionName": connector
    }

手順 3 のアクション JSON では、inputs.host.connectionName に GUID ではなく、 shared_teams のようなマップキーを指定する必要があります。GUID は connectionReferences[connector].connectionName の値の中にのみ設定します。既存のフローで 同じコネクタが使われている場合は、get_live_flow から properties.connectionReferences をコピーしてもかまいません。

---

3. フロー定義を構築する

定義オブジェクトを構築します。完全なスキーマについては flow-schema.md を、コピーして使えるテンプレートについては次のアクションパターンのリファレンスを参照してください。

• action-patterns-core.md — 変数、制御フロー、式
• action-patterns-data.md — 配列変換、HTTP、解析
• action-patterns-connectors.md — SharePoint、Outlook、Teams、Approvals

definition = {
    "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
    "contentVersion": "1.0.0.0",
    "triggers": { ... },   # see trigger-types.md / build-patterns.md
    "actions": { ... }     # see ACTION-PATTERNS-*.md / build-patterns.md
}

Recurrence+SharePoint+Teams、HTTP トリガーなどを網羅した、すぐに使える完全なフロー定義については build-patterns.md を参照してください。

JSONを推測する前に、コネクターの操作を確認する

コネクターに基づくトリガー／アクションでは、手書きのスキーマよりも、稼働中のコネクター記述ツールを優先してください。作成者が指定したヒント、標準的な例、バリアントキー、入力／出力、動的メタデータへのポインターを返すことができます。

# Search across connectors when you know the user's intent but not the API.
matches = mcp("describe_live_connector",
    environmentName=ENV,
    search="send email",
    top=5)

# Describe a specific operation before copying an exampleDefinition.
op = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_office365",
    operationId="SendEmailV2")
print(op.get("hint"))

操作に複数の作成済みバリアントがある場合は、フローに必要なバリアントをリクエストしてください。

teams_chat = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_teams",
    operationId="PostMessageToConversation",
    variant="flowbot_chat")

操作の説明に、パラメーターに動的オプションまたは動的プロパティがあると記載されている場合は、指定された次のツールを呼び出してください。

sp_op = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    operationId="GetItems")

sites = mcp("get_live_dynamic_options",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    connectionName=conn_map["shared_sharepointonline"],
    operationId="GetItems",
    parameterName="dataset",
    dynamicMetadata=sp_op["dynamicParameters"]["dataset"])

fields = mcp("get_live_dynamic_properties",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    connectionName=conn_map["shared_sharepointonline"],
    operationId="GetItems",
    parameterName="item",
    parameters={"dataset": "<site-url>", "table": "<list-id>"},
    dynamicMetadata=sp_op["dynamicProperties"]["item"])

SharePoint のサイト／リストや Teams のチーム／チャネルなど、ドロップダウンの ID には動的オプションを使用してください。SharePoint のリストアイテムの列など、スキーマ／フィールドの構造には動的プロパティを使用してください。

---

4. デプロイ（作成または更新）

update_live_flow は、1 つのツールで作成と更新の両方に対応します。

新しいフローを作成する（既存のフローがない場合）

flowName を省略してください。サーバーが新しい GUID を生成し、PUT で作成します。

definition["description"] = "Weekly SharePoint → Teams notification flow, built by agent"

result = mcp("update_live_flow",
    environmentName=ENV,
    # flowName omitted → creates a new flow
    definition=definition,
    connectionReferences=connection_references,
    displayName="Overdue Invoice Notifications"
)

if result.get("error") is not None:
    print("Create failed:", result["error"])
else:
    # Capture the new flow ID for subsequent steps
    FLOW_ID = result["created"]
    print(f"✅ Flow created: {FLOW_ID}")

既存のフローを更新する

PATCH を実行するには flowName を指定してください。

definition["description"] = (
    "Updated by agent on " + __import__('datetime').datetime.utcnow().isoformat()
)

result = mcp("update_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,
    definition=definition,
    connectionReferences=connection_references,
    displayName="My Updated Flow"
)

if result.get("error") is not None:
    print("Update failed:", result["error"])
else:
    print("Update succeeded:", result)

⚠️ update_live_flow は常に error キーを返します。 null（Python の None）は成功を意味します。キーが存在することを失敗とみなさないでください。

⚠️ フローの説明は definition["description"] にあります。現在のサーバーは、使用状況の追跡のために #flowstudio-mcp を追加します。有効なスキーマに tool_search で表示されない限り、トップレベルの description 引数を渡さないでください。

よくあるデプロイエラー

エラーメッセージ（次の文字列を含む）	原因	対処方法
missing from connectionReferences	アクションの host.connectionName が、connectionReferences マップに存在しないキーを参照しています	host.connectionName には、生の GUID ではなく connectionReferences のキー（例：shared_teams）を指定してください
ConnectionAuthorizationFailed / 403	接続 GUID が別のユーザーに属しているか、認証されていません	ステップ 2a を再実行し、現在の x-api-key ユーザーが所有する接続を使用してください
InvalidTemplate / InvalidDefinition	定義 JSON に構文エラーがあります	runAfter チェーン、式の構文、アクションの種類の表記を確認してください
ConnectionNotConfigured	コネクターアクションが存在しますが、接続 GUID が無効または期限切れです	list_live_connections で新しい GUID を再確認してください

---

5. デプロイを検証する

check = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)

# Confirm state
print("State:", check["properties"]["state"])  # Should be "Started"
# If state is "Stopped", use set_live_flow_state — NOT update_live_flow
# mcp("set_live_flow_state", environmentName=ENV, flowName=FLOW_ID, state="Started")

# Confirm the action we added is there
acts = check["properties"]["definition"]["actions"]
print("Actions:", list(acts.keys()))

---

6. フローをテストする

必須：テスト実行をトリガーする前に、必ずユーザーに確認してください。 フローの実行には実際の副作用があります。メールの送信、Teams メッセージの投稿、SharePoint への書き込み、承認の開始、外部 API の呼び出しなどが発生する可能性があります。フローが実行する内容を説明し、trigger_live_flow または resubmit_live_flow_run を呼び出す前に、明示的な承認を待ってください。

更新済みのフロー（以前の実行履歴がある場合）— トリガーの種類を問わない

まず resubmit_live_flow_run を使用してください。 Recurrence、SharePoint、コネクターの Webhook、Button、HTTP など、あらゆるトリガータイプで動作します。 元のトリガーペイロードを再実行します。ユーザーに手動でフローをトリガーするよう求めたり、次のスケジュール実行を待ったりしないでください。

runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1)
if runs:
    # Works for Recurrence, SharePoint, connector triggers — not just HTTP
    result = mcp("resubmit_live_flow_run",
        environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"])
    print(result)   # {"resubmitted": true, "triggerName": "..."}

HTTP、Button、PowerApps フロー — カスタムテストペイロード

元の実行とは異なるペイロードを送信する必要がある場合に限り、trigger_live_flow を使用してください。修正を検証する場合は、失敗の原因となった正確なデータを使用する resubmit_live_flow_run の方が適しています。

defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
triggers = defn["properties"]["definition"]["triggers"]
manual = next(iter(triggers.values()))
print("Expected body:", manual.get("inputs", {}).get("schema"))

result = mcp("trigger_live_flow",
    environmentName=ENV, flowName=FLOW_ID,
    body={"name": "Test", "value": 1})
print(f"Status: {result['responseStatus']}, via: {result['invocation']}")
print(result.get("warning"))   # set when a required input was missing: the run still ran, with null

新規の非 HTTP フロー

新規のRecurrenceフローに回避策は必要ありません。デプロイ後、body を指定せずに trigger_live_flow で直ちに実行します。ポータルの「フローを実行」ボタンと同じです。本文は拒否されます。スケジュールトリガーは入力を受け取りません。

新規のコネクタートリガー型フロー（SharePoint、Webhook）には実行履歴がなく、実際のソースイベントが発生しない限り起動できません。一時的な HTTP トリガーを使ってデプロイし、アクションをテストしてから、本番用トリガーに差し替えてください。

production_trigger = definition["triggers"]
definition["triggers"] = {
    "manual": {"type": "Request", "kind": "Http", "inputs": {"schema": {}}}
}
result = mcp("update_live_flow", environmentName=ENV,
    flowName=FLOW_ID,       # omit if creating new
    definition=definition, connectionReferences=connection_references,
    displayName="Overdue Invoice Notifications")
FLOW_ID = FLOW_ID or result["flowName"]

mcp("trigger_live_flow", environmentName=ENV, flowName=FLOW_ID,
    body={"sample": "payload"})
runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1)
if runs[0]["status"] == "Failed":
    err = mcp("get_live_flow_run_error",
        environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"])
    raise Exception(err["failedActions"][-1])

definition["triggers"] = production_trigger
mcp("update_live_flow", environmentName=ENV, flowName=FLOW_ID,
    definition=definition, connectionReferences=connection_references)

トリガーはエントリーポイントにすぎません。HTTP 経由のテストでも、同じアクションが実行されます。アクションが triggerBody() または triggerOutputs() を使用する場合は、本番トリガーのペイロードと同じ構造の代表的な body を渡してください。

---

よくある落とし穴

間違い	影響	防止策
デプロイ時に connectionReferences がない	400「Supply connectionReferences」	常に最初に list_live_connections を呼び出します
Foreach に "operationOptions" がない	並列実行により、書き込みで競合状態が発生します	常に "Sequential" を追加します
union(old_data, new_data)	古い値が新しい値を上書きします（先勝ち）	union(new_data, old_data) を使います
null の可能性がある文字列に split() を使う	InvalidTemplate エラーが発生します	coalesce(field, '') でラップします
result["error"] が存在するか確認する	常に存在します。実際のエラーは != null です	result.get("error") is not None を使います
フローをデプロイしたが、状態が「Stopped」になっている	フローはスケジュールどおりに実行されません	state: "Started" を指定して set_live_flow_state を呼び出します。状態変更に update_live_flow は使用しないでください
Teams の「Chat with Flow bot」の受信者をオブジェクトで指定する	400 GraphUserDetailNotFound	末尾にセミコロンを付けたプレーンな文字列を使います（下記参照）
Copilot／Skills のフローがソリューションに含まれていない	Copilot Studio がエージェントツールとして検出できない場合があります	デプロイ後、対象の solutionId を指定して add_live_flow_to_solution を呼び出します
MCP のテストに Button／Skills トリガーを使う	必須入力がない（null）場合でも実行されます	trigger_live_flow の body に入力を渡します。warning が出た場合はキャンセルし、完全な body を指定して再試行します
コネクタアクションに metadata.operationMetadataId がない	デザイナーや実行専用 UI の動作が不安定になる場合があります	既存の ID を保持し、新しいコネクタアクションには固定 GUID を追加します
Excel の scriptId がプレースホルダーのまま	保存時に動的検証に失敗します	デプロイ前に実際の Office Script ID を解決します
SharePoint の PatchItem で必須フィールドが省略されている	フィールドを変更しない場合でも保存に失敗することがあります	item/Title など、変更しない必須フィールドもそのまま含めます
Copilot Studio コネクタがドラフトのエージェントを呼び出す	コネクタ呼び出しが失敗したり、古い動作に遭遇したりすることがあります	フローをテスト／再送信する前に、エージェントを公開します

Teams PostMessageToConversation — 受信者の形式

body/recipient パラメーターの形式は、location の値によって異なります。

場所	body/recipient の形式	例
Chat with Flow bot	末尾にセミコロンを付けたプレーンなメールアドレス文字列	"[email protected];"
Channel	groupId と channelId を持つオブジェクト	{"groupId": "...", "channelId": "..."}

よくある間違い：「Chat with Flow bot」に {"to": "[email protected]"} を渡すと、
400 GraphUserDetailNotFound エラーが返されます。API はプレーンな文字列を想定しています。

---

参考ファイル

• flow-schema.md — フロー定義の JSON スキーマ全体
• trigger-types.md — トリガータイプのテンプレート
• action-patterns-core.md — 変数、制御フロー、式
• action-patterns-data.md — 配列変換、HTTP、解析
• action-patterns-connectors.md — SharePoint、Outlook、Teams、Approvals
• build-patterns.md — フロー定義の完全なテンプレート（Recurrence+SP+Teams、HTTP トリガー）

関連スキル

• power-automate-mcp — 基本的な接続設定とツールのリファレンス
• power-automate-debug — デプロイ後に失敗したフローをデバッグする