power-automate-mcp

Overview Schema Source Related Servers Discussions Admin

create_flow

Creates a Power Automate flow from a workflow definition containing triggers and actions, with optional start. Use it to turn JSON definitions into runnable flows and surface missing connections.

Instructions

Create a flow from a workflow-definition dict.

definition is the same JSON the designer shows under Code view. It needs at least triggers and actions.

TWO RULES LEARNED THE HARD WAY:

Declare the magic parameters. If any trigger or action uses a connector (type OpenApiConnection / OpenApiConnectionWebhook / ...Notification), the definition must carry, at top level next to triggers and actions: "parameters": { "$connections": {"defaultValue": {}, "type": "Object"}, "$authentication": {"defaultValue": {}, "type": "SecureObject"} } Without them creation 400s complaining that the TRIGGER is missing '$authentication', which sends you hunting in the wrong place. Harmless to include on connector-free flows, so just always include it.
Creating does not bind connections. A 201 gives you a flow whose connectionReferences is {} and which will not start ("CannotStartUnpublishedSolutionFlow"). For connector flows the working sequence is create(start=False) -> update_flow_definition(with connection_references) -> a start call. Connector-free flows (Recurrence, Request, Compose, HTTP) start immediately, which is why the demo flow uses those.

If the environment has no Connected connection for a connector the definition uses, the result carries missing_connections: [{connector, create_url}]. Show the user create_url - the portal Connections page, where + New connection creates it - then call bind_connection once they have signed in.

Never inline a secret in a definition - it is stored in plaintext on the flow artifact. Use a Power Platform environment variable or Key Vault reference.

Look up connector operationIds and parameter keys rather than guessing them. Guessing produces a flow that saves fine and fails at runtime. With the Microsoft Learn MCP server connected: microsoft_docs_search, then microsoft_docs_fetch on https://learn.microsoft.com/connectors// (large, so search first). That page marks deprecated operations. Where a parameter is typed dynamic it stops at the top-level key - copy the nested shape from get_flow on a working flow.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "display_name": "<display_name>",
      "definition": "<definition>"
    },
    "name": "create_flow"
  }
}

Input Schema

Name	Required	Description	Default
`start`	No
`definition`	Yes
`display_name`	Yes

Output Schema

Name	Required	Description	Default
`state`	No
`actions`	No
`flow_id`	No
`modified`	No
`triggers`	No
`warnings`	No
`definition`	No
`display_name`	No
`missing_connections`	No
`previous_definition`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.1.0Nov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare it is a non-idempotent, non-destructive write; the description adds far more — the specific 400 caused by a missing $authentication, the fact that a 201 returns connectionReferences {} and a flow that will not start, and the `missing_connections` payload with create_url. It also flags a security trait (inlined secrets stored in plaintext) and recommends environment variables or Key Vault references.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with a one-line purpose, then two numbered rules and a security note, so the structure is easy to scan and the sequencing rule is separated from the connector-parameter rule. A few clauses are conversational filler ('which sends you hunting in the wrong place', 'learned the hard way'), but they reinforce the misleading-error point rather than waste space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter write tool with a nested free-form object and 0% schema coverage, the description covers the failure modes, the required definition skeleton, the post-create binding gap, and even return-shape details like missing_connections despite an output schema existing. An agent has everything needed to call this correctly and to recover from the two most common errors.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the load, and it does for the two important parameters: `definition` is specified as designer Code-view JSON requiring at least triggers and actions plus the $connections/$authentication top-level block, and `start` is given meaning through the create(start=False) sequence. `display_name` is never addressed, though its intent is self-evident from the name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Create a flow from a workflow-definition dict') and immediately clarifies what `definition` is by analogy to the designer's Code view. It also separates itself from siblings by naming the create -> update_flow_definition -> start sequence, so an agent knows this tool does not bind connections or start connector flows on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the branch conditions: connector flows require create(start=False) followed by update_flow_definition and a start call, while connector-free flows (Recurrence, Request, Compose, HTTP) start immediately. It also routes the agent to bind_connection only after the user has created a missing connection, and to microsoft_docs_search/fetch when operation IDs are unknown.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server