FlowStudio MCP を使用した Power Automate フローの構築とデプロイ

FlowStudio MCP サーバーを通じて、Power Automate クラウドフローをプログラムで構築およびデプロイするためのステップバイステップガイド。

前提条件: 有効な JWT を持つ FlowStudio MCP サーバーが到達可能である必要があります。 接続のセットアップについては、flowstudio-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")
# 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 は { "flows": [...], "mode": "...", ... } を返します
matches = [f for f in results["flows"]
           if "My New Flow".lower() in f["displayName"].lower()]

if len(matches) > 0:
    # フローは存在します — 新規作成ではなく修正する
    FLOW_ID = matches[0]["id"]   # list_live_flows からの通常の UUID
    print(f"既存のフロー: {FLOW_ID}")
    defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
else:
    print("フローが見つかりません — ゼロから構築します")
    FLOW_ID = None

非常に大きな環境では、list_live_flows は継続 URL を返す場合があります。 同じ mode で continuationUrl として戻して、次のバッチを取得します。mode="admin" は、ユーザーがすべての環境フローを必要とし、MCP ID が管理者権限を持つ場合のみ使用します。

---

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"]  # フローに応じて調整
missing = [c for c in connectors_needed if c not in conn_map]
if missing:
    # 停止: 接続にはブラウザ OAuth 同意が必要です。
    # ユーザーに、選択した環境で不足しているコネクタ接続を作成してから
    # list_live_connections を再実行するよう依頼します。
    raise Exception(f"接続がありません: {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"],   # list_live_connections からの接続 id
        "source": "Invoker",
        "id": f"/providers/Microsoft.PowerApps/apis/{connector}"
    }
    host_templates[connector] = c.get("hostTemplate") or {
        "connectionName": connector
    }

ステップ 3 のアクション JSON では、inputs.host.connectionName は shared_teams などのマップキーである必要があり、GUID ではありません。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": { ... },   # trigger-types.md / build-patterns.md を参照
    "actions": { ... }     # ACTION-PATTERNS-*.md / build-patterns.md を参照
}

すぐに使用できるフロー定義を含む build-patterns.md を参照してください (Recurrence+SharePoint+Teams、HTTP トリガーなど)。

コネクタオブジェクトを JSON で推測する前に発見する

コネクタバックアップのトリガー/アクションについては、手書きの形状よりもライブコネクタ記述子を優先します。作成者のヒント、標準的な例、バリアントキー、入力/出力、および動的メタデータポインタを返すことができます。

# ユーザーの意図は知っているが API は知らない場合、コネクタ全体で検索します。
matches = mcp("describe_live_connector",
    environmentName=ENV,
    search="send email",
    top=5)

# 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 は、単一のツールで作成と更新の両方を処理します。

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

flowName を省略します — サーバーは新しい GUID を生成し、PUT で作成します:

definition["description"] = "エージェントによって構築された、毎週の SharePoint → Teams 通知フロー"

result = mcp("update_live_flow",
    environmentName=ENV,
    # flowName が省略されています → 新しいフローを作成
    definition=definition,
    connectionReferences=connection_references,
    displayName="期限切れ請求書通知"
)

if result.get("error") is not None:
    print("作成に失敗しました:", result["error"])
else:
    # 後続のステップ用に新しいフロー ID をキャプチャします
    FLOW_ID = result["created"]
    print(f"✅ フローが作成されました: {FLOW_ID}")

既存のフローを更新する

flowName を指定して PATCH します:

definition["description"] = (
    "エージェントによって更新されました。時刻: " + __import__('datetime').datetime.utcnow().isoformat()
)

result = mcp("update_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,
    definition=definition,
    connectionReferences=connection_references,
    displayName="更新されたフロー"
)

if result.get("error") is not None:
    print("更新に失敗しました:", result["error"])
else:
    print("更新に成功しました:", 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)

# 状態を確認
print("状態:", check["properties"]["state"])  # "Started" である必要があります
# 状態が "Stopped" の場合は、set_live_flow_state を使用します — update_live_flow ではありません
# mcp("set_live_flow_state", environmentName=ENV, flowName=FLOW_ID, state="Started")

# 追加したアクションがそこにあることを確認
acts = check["properties"]["definition"]["actions"]
print("アクション:", list(acts.keys()))

---

6. フローをテストする

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

更新されたフロー (以前の実行を持つ) — どのトリガータイプでも

最初に resubmit_live_flow_run を使用してください。 すべてのトリガータイプで機能します — Recurrence、SharePoint、コネクタウェブフック、Button、および HTTP。元のトリガーペイロードを再生します。 ユーザーにフローを手動でトリガーするか、次のスケジュール実行を待つよう求めないでください。

runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1)
if runs:
    # Recurrence、SharePoint、コネクタトリガーで機能します — HTTP だけではありません
    result = mcp("resubmit_live_flow_run",
        environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"])
    print(result)   # {"resubmitted": true, "triggerName": "..."}

HTTP がトリガーするフロー — カスタムテストペイロード

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("期待される本文:", manual.get("inputs", {}).get("schema"))

result = mcp("trigger_live_flow",
    environmentName=ENV, flowName=FLOW_ID,
    body={"name": "Test", "value": 1})
print(f"状態: {result['responseStatus']}")

真新しい非 HTTP フロー (Recurrence、コネクタトリガーなど)

真新しい Recurrence またはコネクタがトリガーするフローには、再送信する以前の実行がなく、呼び出すHTTP エンドポイントもありません。これは、以下の一時的な HTTP トリガーアプローチが必要な唯一のシナリオです。最初に一時的な HTTP トリガーを使用してデプロイし、アクションをテストしてから、本番トリガーに切り替えます。

コンパクトなレシピ:

production_trigger = definition["triggers"]
definition["triggers"] = {
    "manual": {"type": "Request", "kind": "Http", "inputs": {"schema": {}}}
}

result = mcp("update_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,       # 新規作成の場合は省略
    definition=definition,
    connectionReferences=connection_references,
    displayName="期限切れ請求書通知")
FLOW_ID = FLOW_ID or result["created"]

test = 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() を使用する場合、本番トリガーペイロードのような代表的な trigger_live_flow.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"	フローはスケジュール時に実行されません	set_live_flow_state を state: "Started" で呼び出します — update_live_flow を状態変更に使用しないでください
Teams "Chat with Flow bot" 受信者がオブジェクト	400 GraphUserDetailNotFound	末尾のセミコロン付きの通常の文字列を使用します (以下を参照)
Copilot/Skills フローがソリューション内にない	Copilot Studio はエージェントツールとして発見しないかもしれません	デプロイ後、add_live_flow_to_solution を呼び出して、ターゲット solutionId を指定します
Button/Skills トリガーが MCP テストに使用される	MCP は本番トリガーを直接起動できません	一時的な HTTP ツイン経由で同じアクションをテストしてから、トリガーを戻します
コネクタアクションが metadata.operationMetadataId を欠いている	デザイナー/実行のみの UI は矛盾して動作する可能性があります	既存の ID を保持します; 新しいコネクタアクションに安定した GUID を追加します
プレースホルダー Excel scriptId	動的検証は保存時に失敗する可能性があります	デプロイ前に実際の Office Script ID を解決します
SharePoint PatchItem が必須フィールドを省略	フィールドが変更されていない場合でも保存が失敗する可能性があります	item/Title などの変更されない必須フィールドをエコーします
Copilot Studio コネクタがドラフトエージェントを呼び出す	コネクタ呼び出しが失敗または古い動作に当たる可能性があります	テスト/再送信する前にエージェントを公開します

Teams PostMessageToConversation — 受信者形式

body/recipient パラメータ形式は location 値に応じて異なります:

Location	body/recipient 形式	例
Chat with Flow bot	末尾セミコロン付き通常のメール文字列	"user@contoso.com;"
Channel	groupId と channelId を持つオブジェクト	{"groupId": "...", "channelId": "..."}

一般的なミス: "Chat with Flow bot" に {"to": "user@contoso.com"} を渡すと、 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 トリガー)

関連スキル

• flowstudio-power-automate-mcp — コア接続セットアップとツールリファレンス
• flowstudio-power-automate-debug — デプロイ後の失敗したフローのデバッグ