power-platform-mcp

An MCP server that lets Claude create, run, and debug your Power Automate flows, and build Copilot Studio agents. Renamed from power-automate-mcp on 4 November 2026: it now covers both sides of the Power Platform an agent builder touches. Old links and clones keep working through GitHub's redirect. One file. Ten tools. Built as a teaching artifact for a community talk on why you should build your own MCP servers instead of waiting for someone to ship you one. Nine more tools for real work - environments, start and stop, cancel, resubmit, solutions - live in a second server, extras.py.

The short version

What it does. Claude can list, build, run and fix your flows. When a run fails, explain_run tells you why: it fetches the real error that Power Automate hides behind a link, and shows the value from an earlier step that caused it.

What you need. Python 3.10+, the Azure CLI, and a Power Platform environment. No app registration, no secret: it signs in with your own az login.

Set it up.

git clone https://github.com/OwnOptic/power-platform-mcp.git
cd power-platform-mcp
pip install -r requirements.txt
az login

Then add this to .mcp.json (Claude Code), with absolute paths:

{
  "mcpServers": {
    "power-platform":         { "command": "python", "args": ["/absolute/path/to/server.py"] },
    "power-platform-extras":  { "command": "python", "args": ["/absolute/path/to/extras.py"] },
    "power-platform-copilot": { "command": "python", "args": ["/absolute/path/to/copilot_studio.py"] },
    "microsoft-learn": { "type": "http", "url": "https://learn.microsoft.com/api/mcp" }
  }
}

power-platform alone is the ten-tool core. -extras adds environments, start and stop, cancel, resubmit and solutions; -copilot adds Copilot Studio agents. microsoft-learn lets Claude look up connector actions in Microsoft's documentation instead of guessing them. Use the same Python for all three - the venv one, if you made one. On Claude Desktop, put the local servers in claude_desktop_config.json and add the Learn URL under Settings > Connectors.

Everything runs locally: each person runs their own copy, signed in as themselves. There is no shared server and nothing to host.

Try it. Restart your client, then ask:

• "List my flows."

• "Why did flow name fail last night?"

• "Create a flow from demo-flow.json and run it." (It is meant to fail. Then ask why.)

Use a test environment. The server acts as you, so it can change anything you can. If your az is signed in to more than one tenant, give the server its own az profile for the demo tenant - see One az profile per tenant - and pin it with PA_TENANT_ID=<tenant id> in a .env file next to server.py.

For the skills that manage solutions, install the Power Platform CLI (pac) too. The MCP servers do not need it.

Everything below is the long version: how it works, the Power Automate traps it handles, and why you might build your own.

Related MCP server: web-automation-mcp

What it looks like

> Create a flow from demo-flow.json and run it.

  create_flow  -> DEMO - nightly batch (8a3f...), Started
  run_flow     -> accepted

> It failed. What happened?

  list_runs    -> 08d8...: Failed
  explain_run  -> Compute_batches failed:
                  "Unable to process template language expressions in action
                   'Compute_batches' inputs at line '0' and column '0':
                   'Attempt to divide an integral or decimal value by zero
                    in function 'div'.'."
                  Load_settings emitted {"region": "westeurope", "retries": 3,
                  "batch_size": 0} and Compute_batches divides 120 by batch_size.

> Fix it and run it again.

  get_flow                 -> definition retrieved
  update_flow_definition   -> batch_size: 0 -> 4
  run_flow                 -> accepted
  list_runs                -> 08d8...: Succeeded, output 30

That entire loop is four tool calls the model chose on its own, because the tools tell it what they are for.

Watch it, or present it

Click to play the three-minute explainer. En français : la version française.

• Three-minute explainer, voiced, captioned, built with Remotion from the outputs of a real run: English | français

• A 30-minute live demo script - install, build and debug a flow, give a Copilot Studio agent a tool, skills and solutions with pac, write your own skill: English | français

The video is generated, not recorded: video/narration.json holds the script in both languages, python video/make_voice.py voices it (neural voices, Swiss French for the French cut), and node video/render.mjs renders both. Change a sentence, re-run two commands, and the captions and timings follow.

And when the error is clear but the reason is not:

> This flow works most days. Why did it fail last night?

  compare_runs        -> diverged at Compute_batches, but Load_settings emitted
                         batch_size: 0 where the working run emitted 4.
                         Symptom and cause are different actions.
  analyze_flow_health -> 18% failure rate over 50 runs, 5 of 5 sampled failures
                         all in Get_items. Flaky and concentrated, not broken.

Table of contents

• Watch it, or present it

• Why this exists

• The tool that justifies the exercise

• Quick start - let Claude install it

• Architecture: the four layers - transport: run it over stdio

• Tool reference - companion server: Microsoft Learn MCP

• Gotchas this server encodes

• The demo flow

• Extending it - tests

• Skills: the layer above docstrings

• Troubleshooting

• Security

• What is deliberately missing

• Compared with Microsoft's plugin

• FAQ

Why this exists

Every useful MCP server is four layers. Only two of them are interesting.

Wrapping an API is not the point, and it is precisely the part you can automate. The value is in deciding what to hand the model, and in writing down what you learned so that you never learn it twice.

Two concrete examples from this repo.

Shaping. list_flows returns four fields per flow. The API returns about sixty, mostly GUIDs and internal plumbing. Handing the raw payload to a model burns context, buries the signal, and makes the model slower and less accurate. Deciding what to drop is a judgement call that no code generator can make for you, because it depends on what you actually do with flows.

Docstrings. create_flow documents that a connector flow will fail with HTTP 400 unless the definition declares $connections and $authentication, and that the error message blames the trigger, which sends you hunting in entirely the wrong place. That cost real hours to discover once. It now costs nobody anything, forever, including every future model that reads this docstring.

The code is regenerable. The accumulated knowledge in the docstrings is the asset.

The tool that justifies the exercise

explain_run is the tool a generic HTTP wrapper cannot give you, and it is worth understanding why before you read any other code here.

For connector failures, Power Automate does not put the error message on the action record. A failed connector action comes back looking like this - measured, against a real Teams action posting to a channel that does not exist:

{
  "name": "Post_message",
  "properties": {
    "status": "Failed",
    "code": "NotFound",
    "outputsLink": {
      "uri": "https://<env>.environment.api.powerplatformusercontent.com/.../ActionOutputs?...&sig=...",
      "contentSize": 285
    }
  }
}

There is no error property at all. The real message lives inside a blob behind that short-lived signed URL. The portal follows the link for you, which is exactly why the portal shows you a real error and a naive API wrapper shows you Failed and nothing else.

Which failures actually behave this way. This matters, and getting it wrong sends you chasing the wrong demo:

So an expression error needs no second hop, and a connector-free flow can never demonstrate this problem. demo-flow.json is the first kind; demo-flow-connector.json is the second, and it exists precisely to exercise this path.

And which field inside the blob. error.message is routinely just the code restated - a real Teams 404 gives {"code": "NotFound", "message": "NotFound"}, which tells you nothing. The diagnosis is one level down:

"innerError": {
  "message": "LocationLookupFailed-Location lookup failed for thread 19:...@thread.tacv2"
}

That names the offending value outright. _resolve_error prefers innerError, prefixes the HTTP status, and drops the code when it merely repeats the message, so you get one line: 404 NotFound: LocationLookupFailed-Location lookup failed for thread 19:...@thread.tacv2.

explain_run does two things a wrapper does not:

1. It follows the link. For every failed action, it fetches the outputs blob and digs the message out, so the model receives resolved error text rather than null.

2. It supplies upstream context. A failure is rarely explained by the failing action alone. The cause is almost always in what an earlier action produced. So the response pairs each failed action with the outputs of the actions that succeeded before it, in execution order.

One tool call. The equivalent of about a dozen clicks through the run history view. That gap is the entire argument for building your own MCP server.

Quick start

Let Claude install it

If you already have Claude Code or Claude Desktop, paste the prompt below and it will do the whole setup: check your prerequisites, clone, install, authenticate, wire the server into your MCP client, verify it, and optionally walk the demo debug loop.

It is written to stop and ask before anything that touches your tenant, and it never prints a token.

Set up the power-platform-mcp server on my machine, from
https://github.com/OwnOptic/power-platform-mcp

Work through the phases in order. After each phase, report what you found in one or
two lines. If a check fails in a way not covered below, stop and tell me rather than
improvising.

RULES THAT OVERRIDE EVERYTHING ELSE
- Never print, echo, log or write an access token anywhere. Pipe tokens into
  variables, never to stdout.
- Never run `az login --service-principal`, and never ask me for a password or a
  client secret. This setup needs neither.
- Do not create, update, run or delete any Power Automate flow until I have
  explicitly confirmed the tenant in PHASE 2 and said yes in PHASE 6.
- If a command fails, show me its actual error text. Do not paraphrase it.

PHASE 0 - Inspect only, change nothing
1. Detect my OS and shell.
2. Run `python --version` (and `python3 --version` if that fails). Need 3.10 or later.
   If it is older or missing, stop and tell me.
3. Run `az version`. If the Azure CLI is missing, stop and give me the install link
   for my OS: https://learn.microsoft.com/cli/azure/install-azure-cli
4. Report OS, Python version, az version, and the directory you propose to clone into.

PHASE 1 - Code and dependencies
5. Clone the repo into that directory. If it already exists, `git pull` instead.
6. Create a virtual environment inside it and use it for everything that follows.
   Tell me the exact interpreter path, I will need it in PHASE 4.
7. `pip install -r requirements.txt`. That file is a lockfile, so expect around
   forty pinned packages, not three - `mcp`, `httpx` and `python-dotenv` are the
   direct ones, the rest are their transitives. Confirm the install succeeded.
8. Sanity check the code imports and registers its tools without any environment
   variables set. It should report 10 tools:
   `python -c "import asyncio, server; print(len(asyncio.run(server.mcp.list_tools())))"`
   Run it from the repo directory. If this fails, stop.

PHASE 2 - Authenticate, then STOP for my confirmation
9. Run `az account show`. If it errors, or reports an expired session
   (AADSTS70043), run `az login` and let me complete it in the browser.
10. Show me the tenant id and the signed-in user, and ASK ME TO CONFIRM this is the
    tenant I want. Do not continue until I say yes.
    This matters: the server creates, edits and runs REAL flows with my delegated
    permissions. It can do anything I can do. If the account looks like a production
    or client tenant, say so explicitly and recommend I switch with
    `az login --tenant <id>`.
11. Once I confirm, check the Azure CLI is consented for the Flow audience WITHOUT
    printing the token:
    `az account get-access-token --resource "https://service.flow.microsoft.com/" --query expiresOn -o tsv`
    - A timestamp means it works. Continue.
    - AADSTS65001 (consent) means my tenant has not consented the Azure CLI for this
      audience. Stop and tell me. This server deliberately has no app-registration
      fallback, so setup cannot continue.
    - AADSTS70043 means the session aged out under Conditional Access. Run
      `az login` again.

PHASE 3 - Target environment
12. By default the server uses `Default-<tenantId>`, resolved automatically from the
    Azure CLI. Ask whether I want a different environment.
13. Only if I do: create a `.env` in the repo root containing a single line,
    `PA_ENV_ID=<the environment GUID>`. Otherwise create no .env at all. There is
    nothing else to configure and no secret to store.

PHASE 4 - Wire it into my MCP client
14. Ask which client I use, or detect it.
15. For Claude Code, add to `.mcp.json` in my project root. For Claude Desktop, use
    `%APPDATA%\Claude\claude_desktop_config.json` on Windows or
    `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS.
16. Back up the file before editing if it already exists.
17. Add this entry, with the venv interpreter from step 6 and an ABSOLUTE path to
    server.py:

    {
      "mcpServers": {
        "power-platform": {
          "command": "<absolute path to the venv python>",
          "args": ["<absolute path to server.py>"]
        },
        "microsoft-learn": {
          "type": "http",
          "url": "https://learn.microsoft.com/api/mcp"
        }
      }
    }

    The second entry is the Microsoft Learn MCP server, which the model uses to look
    up connector operationIds instead of guessing them. It is hosted by Microsoft,
    read-only, and needs no sign-in. For Claude Desktop, leave it out of the JSON and
    add https://learn.microsoft.com/api/mcp under Settings > Connectors > Add custom
    connector instead - the JSON file is for local servers.

18. Show me the exact file path you changed and the exact block you added. If the
    file already had other MCP servers, merge into the existing mcpServers object
    rather than replacing it.

PHASE 5 - Verify, read-only
19. Tell me to fully restart my MCP client, and wait for me to confirm I have.
20. Ask me to run: "List my flows."
21. Expect flow_id, display_name, state for each flow. Interpret the result:
    - Flows listed: setup is working, all four layers are live.
    - Empty list: auth works but the environment has no flows, or it is the wrong
      environment.
    - 404: wrong environment. Get the GUID from the make.powerautomate.com URL and
      set PA_ENV_ID as in step 13.
    - "Run `az login` first": the CLI session died. Re-run `az login`.
22. If Microsoft Learn was added, ask me to run: "What is the operationId for posting
    a message to a Teams channel?" Expect `PostMessageToConversation`, cited from
    learn.microsoft.com/connectors/teams. Anything else means the model answered
    from memory rather than calling the Learn server.

PHASE 6 - Optional end-to-end demo. ASK BEFORE STARTING.
23. Explain to me first, then wait for a yes:
    This creates a REAL flow called "DEMO - nightly batch" in the tenant I confirmed,
    from demo-flow.json in the repo. That flow is DELIBERATELY BROKEN: Load_settings
    emits batch_size 0 and Compute_batches divides 120 by it. The run is SUPPOSED to
    fail. That failure is the whole point of the demo.
    It is connector-free (button trigger plus two Compose actions), so it needs no
    connection binding and touches no business data.
24. On my yes, in order: create_flow from demo-flow.json, run_flow, list_runs,
    then explain_run on the failed run.
25. Expected result, tell me whether it matches: explain_run names Compute_batches as
    the failed action, resolves the error to "The template language function 'div'
    was invoked with a divisor of zero", and shows Load_settings outputting
    batch_size 0. Symptom and cause are different actions, which is the point.
26. Then offer to close the loop: update_flow_definition setting batch_size to 4,
    run_flow again, list_runs. Expect Succeeded with output 30.
27. Finally, remind me the demo flow still exists and this server has no delete tool
    on purpose, so I should remove "DEMO - nightly batch" from the maker portal when
    I am done.

When everything is done, give me a short summary: where the repo lives, which
interpreter runs it, which tenant and environment it is pointed at, which config
file you edited, and anything that needed a workaround.

Prerequisites

• Python 3.10 or later

• A Power Platform environment you can create flows in

• The Azure CLI, signed in with az login. That is the entire auth story: no app registration, no admin consent, no client id, no secret

• An MCP client: Claude Code, Claude Desktop, or anything else that speaks MCP

Use a demo or development tenant. This server creates, edits, and runs real flows with your delegated permissions. It can do anything you can do.

1. Sign in

az login

That is the entire setup.

The server needs a token for the https://service.flow.microsoft.com audience. The Azure CLI is itself a Microsoft first-party app that your tenant already trusts, so it will hand you one. No app registration, no admin consent, no device code, no client id, no secret. The server reads your tenant and default environment from whatever the CLI is signed in to.

This is the same trick the Microsoft.PowerApps.PowerShell module uses when Add-PowerAppsAccount followed by Get-Flow lists your flows without you having registered anything.

Check you are pointed at the right place before going further:

az account show --query "{tenant:tenantId, user:user.name}"

One caveat, worth knowing up front. Being first-party is not automatically sufficient in every tenant. Conditional Access and pre-authorization policies vary, and Microsoft's own Work IQ CLI app, for instance, does not carry service.flow.microsoft.com in its allowed resources at all. If your tenant refuses the Azure CLI for this audience you will see a consent error such as AADSTS65001, and you would need your own app registration - which this server deliberately does not implement, to keep Layer 1 down to one shell call.

2. Install

git clone https://github.com/OwnOptic/power-platform-mcp.git
cd power-platform-mcp
pip install -r requirements.txt

Three direct dependencies - mcp, httpx, python-dotenv - plus the Azure CLI. (typing-extensions is declared too, because server.py imports it, but it arrives with mcp anyway.)

requirements.txt is a lockfile: every package pinned to an exact version, transitives included, so you get the same tree this was tested against rather than whatever resolves today. Edit requirements.in to change a dependency, then regenerate:

uv pip compile requirements.in --universal --python-version 3.10 -o requirements.txt

--universal resolves for every OS at once and emits environment markers, so one lockfile covers Windows, macOS and Linux.

This runs on mcp 2.x. If you are upgrading an older clone and see No module named 'mcp.server.fastmcp', your code and your installed SDK are a major version apart: git pull, then pip install -r requirements.txt again. The port itself was a one-line rename plus one behaviour change worth knowing about before you port your own server; see gotcha 9.

3. Configure

There is nothing to configure. The server resolves your tenant and default environment from the Azure CLI, and there is no client id, no secret and no .env required. Skip to step 4.

Two optional settings, both about which tenant and environment you land in:

# Optional. Find the GUID in the make.powerautomate.com URL after switching environment.
PA_ENV_ID=Default-00000000-0000-0000-0000-000000000000

# Strongly recommended if you have ever run `az login` against more than one tenant.
PA_TENANT_ID=00000000-0000-0000-0000-000000000000

Set PA_TENANT_ID if you are a consultant, or on any machine with more than one tenant in az. Borrowing the CLI's token means borrowing whichever account is active, and az holds many at once. az account show on a consultant's laptop is quite often a client's production service principal - at which point this server will cheerfully create and run flows in that client's tenant. Pinning makes the server declare the tenant it is for; if the active account cannot reach it you get a loud AADSTS50020 instead of a quiet write in the wrong place.

It is a guard, not a switch. It will not go and find the right logged-in account for you - it only stops you using the wrong one. Unset is fine on a single-tenant machine and a live grenade on any other.

One az profile per tenant

The switch is a separate Azure CLI profile. az keeps everything in one folder, and AZURE_CONFIG_DIR points it at another, so the server can live in the demo tenant while your own terminal stays wherever your day job is:

$env:AZURE_CONFIG_DIR = "$HOME\.azure-demo"
az login --tenant <demo tenant id>
az account show --query "{tenant:tenantId, user:user.name}"

Then give each server the same folder in .mcp.json:

"power-platform": {
  "command": "python", "args": ["/absolute/path/to/server.py"],
  "env": { "AZURE_CONFIG_DIR": "C:/Users/you/.azure-demo" }
}

Your everyday az (and its active account) is untouched; the servers only ever see the demo profile. If you are already signed in to the demo tenant in your main profile, copy ~/.azure to the new folder and az account set there instead of signing in again.

There is no secret anywhere in this design. The only credential involved is the refresh token the Azure CLI already holds on your machine, which this repo never reads or writes.

4. Connect it to your client

This is a stdio server: your client launches server.py as a local child process and speaks MCP over stdin/stdout. There is nothing to host and no port to open. See Transport: run it over stdio for why that is the right default here.

Claude Code - add to .mcp.json in your project root, or to your user config:

{
  "mcpServers": {
    "power-platform": {
      "command": "python",
      "args": ["C:/path/to/power-platform-mcp/server.py"]
    },
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

The microsoft-learn entry is optional and recommended. See Companion server: Microsoft Learn MCP.

Claude Desktop - the power-platform entry, in claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

That file is for local servers. Add Microsoft Learn under Settings > Connectors > Add custom connector with the URL https://learn.microsoft.com/api/mcp instead.

Use an absolute path to server.py. The server resolves .env relative to its own file, so the working directory does not matter.

5. Verify

Ask your client:

List my flows.

You should get back flow IDs, display names, and states. If you do, all four layers are working.

Then run the full demo:

Create a flow called "DEMO - nightly batch" using the definition in
demo-flow.json, then run it and tell me what happened.

That flow is meant to fail. See The demo flow.

Architecture: the four layers

The whole server is server.py, deliberately kept in one file so it can be read top to bottom in a few minutes. The four layers appear in order.

Transport: run it over stdio

Run this as a stdio MCP server. Your client spawns server.py as a local child process and talks to it over stdin/stdout. Every config block in this README is a stdio config, and that is a recommendation rather than an accident of the example.

It follows directly from Layer 1. The server has no credential of its own - it borrows the Azure CLI session already sitting on your machine. A token in your local CLI keyring can only be read by a process running as you, on that machine. So the transport has to be local, and stdio is the local transport.

What you get by not putting this behind HTTP:

• Nothing to host. No container, no TLS certificate, no public endpoint, no tunnel.

• No second auth layer. A remote server needs its own authentication in front of it, plus a way to map callers back to Power Platform identities. Over stdio the process already runs as you and the API call already carries your delegated permissions.

• Nothing new to leak. The token never crosses a network boundary.

• Lifecycle for free. The client starts the server when you need it and stops it when the session ends.

Reach for a hosted transport (Streamable HTTP) only when something genuinely remote has to call you - a cloud-hosted agent, Copilot Studio, a shared team service. The moment you do, Layer 1 changes completely: you own an app registration, a secret and a consent flow, because there is no local CLI session to borrow. That is a real project, not a config change.

Layer 1: Auth (_az, _token, env_id)

Getting the token is one shell call. That is the single most transferable idea in this repo. The layer around it is another forty lines of caching, error handling and lazy environment resolution, but none of that is the interesting part.

PA_RESOURCE = "https://service.flow.microsoft.com"

token = _az(["account", "get-access-token", "--resource", PA_RESOURCE,
             "--query", "accessToken", "-o", "tsv"])

You are borrowing a Microsoft first-party app your tenant already trusts, which removes the app registration, the admin consent and the device-code dance in one move. Change PA_RESOURCE and the same three lines authenticate you against Microsoft Graph, Dataverse, or Azure Resource Manager. When you build an MCP server against any Azure-fronted API, try this before you go near the Entra portal.

Two implementation notes worth copying:

• shell=True is not laziness. On Windows az is a .cmd shim that CreateProcess will not resolve on its own. Every argument passed here is an internal constant, never user-supplied text.

• env_id() resolves lazily, not at import. If tenant lookup ran at import, a logged-out CLI would kill the server before it registered a single tool and your client would report nothing more useful than "server failed to start". Resolved on first use, the same failure arrives as a readable error inside a tool result telling you to run az login.

The trade-off, stated plainly: the CLI's session lives under your tenant's Conditional Access policy, so it can expire mid-session. You get AADSTS70043 and az login fixes it. That is the price of not owning an app registration, and for a demo server it is obviously worth paying.

Layer 2: Transport (_call, _list)

One request helper handling the four things that always come up:

• 401 once, with a force-refreshed token, then retry

• 429 with Retry-After honoured

• 503 / 504 with exponential backoff

• Terminal errors re-raised carrying the API's own message, because the model can frequently act on it directly. They are raised as PowerAutomateError, a ToolError: on mcp 2.x that is the only kind of exception whose text reaches the model at all (gotcha 9)

Plus _list, which follows nextLink for collection endpoints up to a cap.

BASE        https://api.flow.microsoft.com/providers/Microsoft.ProcessSimple
api-version 2016-11-01

Layer 3: Shaping (_flow_summary, _run_summary, _resolve_error, _trim)

Where the judgement lives. Every tool returns a hand-picked subset of the API response.

The rule of thumb: if you would not read the field while debugging, the model does not need it either.

_trim caps any single field at 2000 characters so one enormous action payload cannot blow up the context window. _resolve_error is the SAS-blob second hop described above.

Layer 4: Tools and docstrings

Ten @mcp.tool() functions. The docstrings are not documentation for humans, they are the prompt the model reads to decide what to call and how. They carry:

• what the tool returns and which field feeds which other tool

• the API's non-obvious constraints

• the failure modes and what they actually mean

• explicit instructions such as "look connector operationIds up on Microsoft Learn rather than guessing"

Everything you get wrong twice belongs in a docstring. That is the practice this repo is arguing for.

Tool reference

Ten tools in server.py, nine in extras.py, nine in copilot_studio.py, plus a companion server for the documentation lookups none of them can do.

Which one to reach for:

The same choices as a table, with the tool most often confused with each one. Getting that pair wrong is the mistake a model actually makes, so each docstring spends its words on exactly that distinction.

list_flows(state="", top=25)

List flows in the environment.

Returns a list of {flow_id, display_name, state, modified}. Use flow_id with every other tool.

get_flow(flow_id)

Get one flow with its complete definition, the JSON behind the designer's Code view.

Returns {flow_id, display_name, state, modified, triggers, actions, definition} where triggers and actions are name lists for quick scanning and definition is the full dict.

Call this before update_flow_definition: the API has no partial update semantics, so you must send the entire definition back with your modification applied.

create_flow(display_name, definition, start=True)

Create a flow from a workflow-definition dict.

The definition is checked locally before it is sent, against the rules the API enforces with misleading messages (missing $authentication, a runAfter naming an action that does not exist, an approval typed as a plain connector call). An error there means nothing was created.

Returns the flow summary, plus warnings for anything accepted but likely to disappoint, and missing_connections - [{connector, create_url}] - when a connector it uses has no connection in the environment yet.

See Gotchas for the two rules that make the difference between a 201 and an afternoon of confusion.

update_flow_definition(flow_id, definition, connection_references=None)

Replace a flow's definition. Send the complete definition, not a fragment.

connection_references is required for connector flows and is shaped like:

{
  "shared_office365": {
    "connectionName": "shared-office365-8f3a...",
    "source": "Embedded",
    "id": "/providers/Microsoft.PowerApps/apis/shared_office365"
  }
}

Can be left out on a flow bound by bind_connection: the tool reads the live bindings itself (get_flow shows {} for them, so there is nothing to copy).

Returns the flow summary plus previous_definition, the definition it just replaced. There is no undo endpoint, and a definition missing an action deletes that action, so the model that made the bad edit gets the old value back to restore it.

Works on flows in My flows, including ones built in the maker portal. Does not work on solution flows: use update_solution_flow_definition. See gotcha 4.

bind_connection(flow_id, connector, connection_name="", start=True)

Bind an existing connection to a flow and start it. The missing step of create_flow.

create_flow returns 201 but leaves connectionReferences empty, so a connector flow cannot be started. Binding is a separate PATCH that must carry both the full definition and the connection reference. This tool does the whole sequence in one call: resolve the connection, PATCH definition plus reference, start the flow.

It resolves the connection from the environment's full connection list, so a connection created in the portal a minute ago binds even though no flow uses it yet. Only Connected connections count. A flow with several connectors is bound in one save, because the API rejects a save that leaves any connector action unbound, and existing bindings are merged rather than dropped.

Returns one of five statuses:

It deliberately does not guess when several connections match, because binding the wrong account is a silent failure you would discover in production.

The connection must already exist. No API reachable with a Flow token can create and authenticate a new connection. That is a portal action, permanently.

run_flow(flow_id, trigger_name="manual", inputs=None)

Trigger a flow immediately rather than waiting for its schedule. Requires flow ownership.

trigger_name is the trigger's internal name from get_flow. It is manual for button flows, which is why the demo flow uses a button trigger.

Returns immediately. The run is asynchronous, so poll list_runs for the outcome.

For Request / HTTP-trigger flows this management endpoint does not forward a body, so @triggerBody() evaluates to null. Call the flow's real HTTP URL if it depends on its payload.

list_runs(flow_id, status="", top=10)

Recent runs, newest first.

Returns {run_id, status, start_time, end_time, error}. Feed a failed run_id straight into explain_run.

explain_run(flow_id, run_id)

Diagnose a run. The reason this repo exists.

Returns:

{
  "run_id": "08d8...",
  "status": "Failed",
  "started": "2026-08-04T14:22:01Z",
  "failed_actions": [
    {
      "name": "Compute_batches",
      "status": "Failed",
      "error": "The template language function 'div' was invoked with a divisor of zero.",
      "inputs": "..."
    }
  ],
  "succeeded": [
    {
      "name": "Load_settings",
      "status": "Succeeded",
      "outputs": {"region": "westeurope", "retries": 3, "batch_size": 0}
    }
  ],
  "hint": "Compute_batches failed. Its error is resolved above; check the outputs of the succeeded actions for the value that caused it."
}

If failed_actions is empty while status is Failed, the failure was in the trigger, not the body. Inspect the trigger's condition and inputs.

SAS URLs expire. Debugging a run from several days ago may return [error blob unavailable]. Re-run the flow to produce a fresh failure.

compare_runs(flow_id, failed_run_id, baseline_run_id="")

Diff a failed run against a working one.

Use this when explain_run gives you an error that is technically clear but does not explain why this run differed: intermittent failures, "it worked yesterday", data-dependent bugs. baseline_run_id is optional; left empty the tool finds the most recent Succeeded run itself.

{
  "failed_run": "08d8...",
  "baseline_run": "08d7...",
  "diverged_at": "Compute_batches",
  "status_changes": [
    { "action": "Compute_batches", "baseline": "Succeeded", "failed": "Failed" }
  ],
  "output_changes": [
    { "action": "Load_settings", "baseline": {"batch_size": 4}, "failed": {"batch_size": 0} }
  ],
  "only_in_failed": [],
  "only_in_baseline": []
}

Read it in this order: diverged_at tells you where the run broke, and output_changes usually tells you why. Above, the run diverged at Compute_batches but the cause is upstream in Load_settings, whose output changed from 4 to 0. Symptom and cause are different actions, which is the normal case.

only_in_failed and only_in_baseline being non-empty means a condition or branch evaluated differently between the two runs.

If output_changes is empty and the same action failed in both runs, the failure is deterministic. The fix is in the definition, not the data.

Output comparison uses contentSize when outputs are behind a outputsLink URI, since the URIs themselves differ per run by design and would otherwise always compare as changed.

analyze_flow_health(flow_id, last_n=50, sample_failures=5)

Analyse recent run history: reliability, failure patterns, duration.

{
  "runs_analysed": 50,
  "Succeeded": 41, "Failed": 9, "Cancelled": 0, "Running": 0,
  "failure_rate": 0.18,
  "duration_seconds": { "mean": 4.21, "p95": 11.80, "max": 14.02 },
  "failures_sampled": 5,
  "failing_actions": [
    { "action": "Get_items", "count": 5, "sample_error": "The response is not in a JSON format." }
  ],
  "verdict": "Flaky, concentrated in 'Get_items' - that one action explains almost every failure."
}

Action-level detail costs one request per run, so only sample_failures of the failed runs are opened. failing_actions is a sample, not an exhaustive tally, and the response states how many runs it came from so you can see that for yourself.

The verdict distinguishes the two cases that call for different responses: failures concentrated in one action mean a targeted fix, while failures spread across many actions usually mean the trigger data or a connection rather than the logic.

The extras.py tools

A second server, so the core stays at ten. Same auth, same transport, same error handling: it imports all of it from server.py. See Running extras.py.

list_environments()

Every environment the signed-in account can reach. Use it before setting PA_ENV_ID, rather than after a 404.

Returns [{environment_id, display_name, sku, region, is_default, has_dataverse, current}]. environment_id is exactly what PA_ENV_ID takes, and current marks the one every other tool is pointed at now. has_dataverse says in advance whether the three solution tools can work there: several environments, often the Default one, have no Dataverse instance.

set_flow_state(flow_id, state)

Start or stop a flow. state is Started or Stopped.

Returns {flow_id, requested, state, ok}. Trust ok, not the 200. The start and stop endpoints return a receipt, so the tool reads the flow back and reports whether the state actually moved.

Stopping a flow does not stop a run already in progress (that is cancel_run). Starting an unbound connector flow fails with CannotStartUnpublishedSolutionFlow: that is bind_connection's job, and it starts the flow too.

cancel_run(flow_id, run_id)

Cancel a run that is still Running: a loop that will not end, a wait that never returns. Nothing is undone - actions that already ran stay done. The run ends as Cancelled, and explain_run on it shows what had completed. If the flow will just fire again, stop it first with set_flow_state.

resubmit_run(flow_id, run_id)

Replay a run with its original trigger payload. This is how you prove a fix: run_flow starts a fresh run with no payload, so a green result there says nothing about the data that broke it.

Returns {status, source_run, trigger}; poll list_runs for the new run. Same blast radius as the original run. The route is not the obvious one, see gotcha 8.

get_trigger_url(flow_id)

The HTTP callback URL for each request-style trigger, the one the portal shows on the trigger card. Blocked by the API on Button triggers (kind: "Button"), so useful on real HTTP-triggered flows and useless on the demo one. Treat the result as a secret: the URL carries its own signature and is enough to run the flow.

delete_flow(flow_id, confirm=False)

Permanently delete a flow and its run history. Refuses unless confirm=True. If the runs are evidence for a failure you are still diagnosing, look at them first.

list_solutions(top=50, include_hidden=False)

The environment's solutions, read from Dataverse (there is no Power Automate route for them: it 404s for every environment). Use it to answer "is this flow in a solution, and is that solution managed?" before editing: a managed solution's flows are read-only by design.

Returns [{solution_id, unique_name, display_name, version, publisher, is_managed, installed_on}].

get_solution_flow_clientdata(flow_id)

A solution flow's real, stored definition, from the Dataverse workflow row. get_flow cannot give you an editable copy of these, because the Power Automate API rewrites the connection hosts on the way out. Base every solution-flow edit on this one.

update_solution_flow_definition(flow_id, definition, connection_references=None)

Replace a solution flow's definition by read-modify-write on that Dataverse row. A write there deactivates the flow; the tool reactivates it if it was on, and says so under reactivated. Leave connection_references out unless you mean to change them. Returns previous_definition, as update_flow_definition does.

The copilot_studio.py tools

A third server, and the FAQ's "same four layers, different API" made real. Copilot Studio agents are Dataverse rows - a bots row plus one botcomponents row per topic, tool, knowledge source and instruction set - so the az session that runs flows edits agents too, with a token for the environment's org URL. It imports its auth, transport and Dataverse helpers from the other two files and adds no auth code of its own.

The loop it exists for: Claude builds a flow, plugs it into an agent as a tool, tells the agent when to use it, and publishes. The agent-tool skill walks it.

Both harnesses. Copilot Studio now creates agents on two runtimes, and they store an agent in different places (gotcha 11). Every tool here reads the agent's template first and does the right thing for each: standard (URL .../bots/<id>, topics) or github_copilot (URL .../agents/<id>, skills). The URL also gives you both ids: copilotstudio.microsoft.com/environments/<environment_id>/bots|agents/<agent_id>.

list_agents() and get_agent(agent_id, environment_id="")

list_agents returns [{agent_id, name, schema_name, last_publish, published_on}]. get_agent reads an agent the way its maker thinks about it: harness, instructions as plain text (the Instructions box), model, web_browsing, tools (each with its kind, and its flow_id when it is a flow), knowledge, files, skills, work_iq (Microsoft 365 capabilities and their access level), child_agents, custom_topics apart from the system_topics every agent ships with, test_cases and last_publish. environment_id reads an agent in another environment than the server's.

export_agent(agent_id, environment_id="", include_test_cases=False)

The raw source: the bot row (with configuration parsed) and every component as stored, each with its YAML kind. The starting point for reproducing an agent in another environment or on the other harness, without a solution export. It says plainly what is not there: uploaded knowledge files have no bytes in their row, and a new harness agent's suggested prompts are in no column at all (gotcha 15).

create_agent_flow(display_name, definition, solution="", start=True)

Creates a flow an agent can call. Use it instead of create_flow for agent tools: Copilot Studio only calls solution flows, and a flow made through the Power Automate API has no Dataverse workflow row at all (gotcha 10). This writes that row - definition in clientdata, optionally in a named solution - and turns the flow on. The definition needs the agent trigger (Request, kind Skills) and reply (Response, kind Skills); demo-agent-flow.json is a working one. Returns a flow_id that every other tool accepts.

add_flow_tool(agent_id, flow_id, display_name, description)

Adds the flow to the agent as a tool. Inputs and outputs are read from the flow itself. description is what the agent's orchestrator reads to decide when to call it, so it is the most important argument. Refuses a flow the agent cannot call, with the reason. Calling it again for the same flow refreshes the tool instead of adding a second.

update_agent_instructions(agent_id, instructions)

Replaces the instructions and returns previous_instructions, the only undo there is. On the standard harness it rewrites the instructions: key of the gpt.default component and leaves every other byte alone; on the GitHub Copilot harness it writes the StaticSegment in the bot's configuration and leaves the model and web settings alone. Refuses { and }: Copilot Studio parses braces in instructions as Power Fx, and the agent then fails on every message while the save itself succeeds.

upsert_agent_skill(agent_id, name, description, instructions)

GitHub Copilot harness only. Adds a skill, or replaces the one with that name, including one made in the designer under a different schema name. You pass the body; the front matter is built from name (lowercase words joined by hyphens, 64 characters at most) and description (1024 at most). The description is the trigger the agent reads before loading the skill, so write it as "use this when". Returns the previous body when it replaced one.

remove_agent_component(agent_id, schema_name, confirm=False)

A dry run until confirm=True: first it returns the component, data included, which is the backup, because a deleted component has no recycle bin. Typical use is the Work IQ capabilities a new harness agent can be created with (gotcha 13). Refuses the standard-harness instructions component.

publish_agent(agent_id, wait_seconds=120)

Publishes and waits for the real result: Succeeded, Failed, timeout, or no_change for an agent with nothing new to publish (which records no new publish operation, so a naive wait never ends). Changes are drafts until this runs: the test pane sees them, Teams and Microsoft 365 Copilot do not.

Companion server: Microsoft Learn MCP

The ten tools build, run and diagnose flows. None of them can tell you what goes inside a connector action: its operationId, its parameter keys, whether it has been deprecated. Guessing those produces a flow that saves cleanly and fails at runtime (gotcha 7). That knowledge already has an official MCP server, so this repo connects it rather than rebuilding it.

The Microsoft Learn MCP Server is hosted by Microsoft, free, read-only, and needs no sign-in and no API key:

https://learn.microsoft.com/api/mcp

It is the one exception to run it over stdio. That recommendation exists because this server borrows a local credential. The Learn server has no credential to protect, so a remote transport costs nothing.

Install. This repo ships a .mcp.json containing only the Learn entry, so opening the repo in Claude Code offers it (approve it on first use). In another project, add the microsoft-learn block from step 4, or:

claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp

Microsoft also publishes it as a Claude Code plugin, microsoft-docs, which adds three general-purpose Learn skills on top. See their getting-started page.

Where it sits in the authoring loop:

1. get_flow on a working flow that does something similar

2. microsoft_docs_search, then microsoft_docs_fetch, for the operationId and keys

3. create_flow, then bind_connection if it uses a connector

4. run_flow, list_runs, explain_run if it failed

What it will and will not tell you, measured against the Teams connector on 2026-09-10:

• The operationId and top-level keys, not the body. "Post message in a chat or channel" is PostMessageToConversation, with keys poster, location and body, and body is typed dynamic. The nested paths a working definition actually uses, such as the doubled body/body/messageBody from gotcha 7, are not on the page. Learn tells you which operation. get_flow on a working flow tells you how to fill it. You need both.

• Deprecated operations are labelled. The page marks SubscribeChannelFlowContinuation and SubscribeUserFlowContinuation as [DEPRECATED], a few lines from their replacement, PostCardAndWaitForResponse. Check before you copy an action out of an old flow.

• Fetching a connector page is expensive. The Teams reference came back at about 157,000 characters, more than a single tool result holds. Search first, and fetch only when the excerpt is not enough. Appending ?maxTokenBudget=2000 to the endpoint URL caps search responses only, not fetches.

• Search by operationId finds the wrong page. Searching PostMessageToConversation returned the .NET Azure.Connectors.Sdk reference and a Power Automate how-to, not the connector reference. Once you know the connector, go straight to learn.microsoft.com/connectors/<connector>/. The slug is usually the logical name without shared_, e.g. shared_teams becomes teams.

Why a companion server instead of an eleventh tool: it is the same argument as extras.py, from the other side. Build the layer nobody ships you, and connect the one somebody already maintains. Looking up documentation is a commodity. Knowing that body stops at dynamic and the real shape lives in a working flow is not.

Gotchas this server encodes

These are the hours this repo saves you. Each one is also written into the relevant docstring so the model sees it at call time, which is the entire point.

1. Failed actions carry error: null

Covered above. The message is in a SAS-signed blob at outputsLink.uri. explain_run follows it.

2. Connector flows need the two magic parameters

If any trigger or action is an OpenApiConnection, OpenApiConnectionWebhook, or OpenApiConnectionNotification, the definition must declare, at top level alongside triggers and actions:

"parameters": {
  "$connections":    { "defaultValue": {}, "type": "Object" },
  "$authentication": { "defaultValue": {}, "type": "SecureObject" }
}

Omit them and creation fails with HTTP 400 stating that the trigger is missing $authentication. That message is misleading: there is no trigger-versus-action asymmetry, connector triggers and connector actions both fail identically without the block. Add only $authentication and it then complains about $connections.

They are harmless on connector-free flows, so just always include them.

3. Creating a flow does not bind its connections

A 201 Created gives you a flow whose connectionReferences is {}, whose /connections endpoint is empty, and which cannot be turned on:

CannotStartUnpublishedSolutionFlow: Please authenticate the flow connections
and save the flow to enable activation.

Passing connectionReferences on the create call does not help. The service rewrites it into a solution-style connectionReferenceLogicalName binding that stays unstartable.

The working headless sequence for a non-solution flow reusing a connection that already exists in the environment:

1. create_flow(..., start=False)

2. update_flow_definition(flow_id, definition, connection_references={...})

3. Start the flow

bind_connection does all three in one call, which is exactly the kind of thing your own MCP server should absorb. An API that requires a three-step dance to reach a working state is an API whose tool layer should expose the destination, not the dance.

Nothing in any of these APIs can create and authenticate a brand new connection. Make that one in the portal first.

4. Solution flows cannot be updated through this API

A flow inside a solution binds its connections through Dataverse connection references, and there is a read/write shape mismatch that cannot be reconciled through the Power Automate API:

• get_flow reports the host as connectionName

• the PATCH wants connectionReferenceName

• supplying connectionReferenceName fails with "connection reference could not be found", because minting the Dataverse reference is not possible through this endpoint

So go round it: the stored definition lives in the clientdata column of the Dataverse workflow row, and extras.py reads and writes it there (get_solution_flow_clientdata, update_solution_flow_definition).

This used to say "portal-bound flows", and that was too broad. A flow built in the maker portal under My flows, not in a solution, keeps Embedded references, and a PATCH carrying them as stored succeeds (measured 28 July 2026). The line that matters is solution or not, not portal or not. list_solutions tells you which side of it you are on.

5. The obvious connections endpoint does not exist

This one is worth reading even if you never touch Power Automate, because it is the purest example of why a hand-built tool layer beats a generated one.

To bind a connection you need its connectionName. The obvious way to get it is to list the environment's connections, and the obvious routes are all closed:

• /environments/{env}/connections returns 404 under the Microsoft.ProcessSimple provider and under Microsoft.PowerApps

• the per-environment route on the PowerApps host, api.powerapps.com/providers/Microsoft.PowerApps/environments/{env}/connections, returns 403 InvalidPath with a Flow token

The route that works is the top-level collection on that same host, filtered by environment, with a token for the PowerApps audience, which az mints like any other. A second token, not a second app registration:

GET https://api.powerapps.com/providers/Microsoft.PowerApps/connections
    ?api-version=2016-11-01&$filter=environment eq '<env>'
Token audience: https://service.powerapps.com/

Measured on a live tenant: 200 and the full list, including connections no flow uses yet - which is what makes "create the connection in the portal, then bind it" work in one go. bind_connection and create_flow use it, and keep only Connected connections, because a broken one binds fine and then fails every run.

If that call fails, the server falls back to the per-flow route, /environments/{env}/flows/{flow_id}/connections, which does work with a Flow token, and unions what the environment's flows reference. The fallback cannot see a connection that no flow uses yet, so on that path a brand new connection comes back not_found.

How this was found is the actual lesson. The first version of this server shipped the flow walk as the only route, with a note saying the PowerApps listing needed a second app registration. That note was wrong, and it took reading someone else's code to find out. Nothing in any of these APIs tells you which route is the real one.

No code generator produces that route. It only exists because someone hit the 404, then hit the 403, then shipped the flow-walk workaround, then found out the workaround was unnecessary.

6. Never inline a secret in a definition

Flow definitions are stored in plaintext on the flow artifact. An API key written into a definition is readable by anyone with access to the flow. Use a Power Platform environment variable or a Key Vault reference and resolve it at runtime.

7. Look connector operationIds up, do not guess them

Connector actions need the exact operationId and the exact parameter names. Guessing produces a flow that saves cleanly and fails at runtime, which is the worst possible failure mode.

Connect the Microsoft Learn MCP server and the model does the lookup itself, against the connector reference. That gives you the operationId and the top-level keys. Where a parameter is typed dynamic, the page stops there, and the nested shape has to come from get_flow on a working flow built in the portal.

A representative example of how non-obvious these get: the Teams "post adaptive card and wait for a response" action is PostCardAndWaitForResponse, its parameters use a doubled prefix (body/body/messageBody), and the submitActionId it returns is the title of the button the user clicked rather than the button's data payload.

8. Resubmit belongs to the trigger, not to the run

Replaying a failed run is the honest way to test a fix, and the route reads like it should be:

POST /environments/{env}/flows/{flow}/runs/{run}/resubmit        404

It sits right next to /runs/{run}/cancel, which does exist. It returns 404 all the same. Resubmit hangs off the trigger's history:

POST /environments/{env}/flows/{flow}/triggers/{trigger}/histories/{run}/resubmit

The history name is the run id - the Logic Apps reference says it "corresponds to the run name for triggers that resulted in a run" - and the trigger name is on the run record, so resubmit_run reads the run first and needs only the run_id from you.

And it only replays runs the service started. Measured on 3 November 2026: a run fired by its own Recurrence trigger resubmitted fine; a run started through run_flow was refused with 403 This flow run was started by someone else and you can only resubmit runs that you've initiated. For a Button flow that costs nothing - there is no payload to replay - so run_flow again is the retest.

This one is in here because this repository got it wrong twice: extras.py shipped calling the 404 route, and so did the example in Extending it, which taught the wrong route to everyone who copied it. A docstring is only an asset while it is true.

9. mcp 2.x hides the text of every exception that is not a ToolError

Relevant to anyone porting an MCP server from mcp 1.x to 2.x, not just this one.

The port is mostly a rename: FastMCP became MCPServer, and the decorators, annotations and output schemas carry over. The change that matters is silent. In 1.x, any exception a tool raised reached the model as its error text. In 2.x the SDK splits them in two:

This server raises on purpose, with the API's own message, because the model can usually act on it: a 400 naming the bad property, "run az login", the local validator's rule names. Ported naively, every one of those becomes a bare "Error executing tool", while the import check, the tool count and every happy-path demo still pass.

The fix is one class. Every deliberate error here is a PowerAutomateError, which subclasses ToolError (so 2.x forwards its text) and RuntimeError (so every existing except RuntimeError keeps working). Dataverse calls go through a helper that raises it with Dataverse's own message instead of calling raise_for_status(), whose HTTPStatusError would count as a crash. Three tests pin it down: one that a ToolError's text arrives, a control test showing a plain exception's text does not, and one that fails the build if a bare raise RuntimeError( comes back.

10. An agent can only call a solution flow

Microsoft's FAQ says it in one line: to add a flow to an agent, "it must be a solution flow". What it does not say is that a flow created through the Power Automate API never is one, even in an environment with Dataverse. Measured on 3 November 2026:

create_flow(...)                          -> flow_id a0179a97-...
GET {org}/api/data/v9.2/workflows(a0179a97-...)
                                          -> 404 Entity 'workflow' ... Does Not Exist

No workflow row means no solution, and a Copilot Studio tool pointing at it has nothing to point at. The trap is that nothing complains early: the tool component saves, and the agent even publishes successfully. It only fails when a user's question makes the agent call it.

So copilot_studio.py creates agent flows on the Dataverse side instead: POST workflows with category: 5 (a modern cloud flow), the definition in clientdata, and MSCRM.SolutionUniqueName to put it in a named solution, then statecode: 1 to turn it on. The Power Automate API sees the result as an ordinary flow with the same id, so run_flow, list_runs and explain_run all work on it. And add_flow_tool checks for the workflow row first and refuses with the reason, because "saves, publishes, then fails in front of a user" is the most expensive kind of failure there is.

11. Two harnesses, two storage layouts

Since September 2026 Copilot Studio creates agents on a runtime of your choice, the harness, and it cannot be changed afterwards. Measured on 4 November 2026 on two agents in the same environment, read with the same GET bots and GET botcomponents:

A tool written for one silently does nothing useful on the other: a gpt.default search finds no row on the new harness and "the agent has no instructions" is a lie. So every tool here reads template first. Writes through Dataverse show up in the designer after a refresh; an already open designer tab saves its stale copy over them.

12. --tenant is a guard; --subscription is the switch

Layer 1 pins the tenant with --tenant, which asks the active az account for a token in that tenant. On a consultant machine with eight az accounts, the active one was a client's, and the pinned tenant failed with AADSTS90072: User account ... does not exist in tenant although a valid login for it sat in the same cache. --subscription <tenant id> selects that login, because a tenant-level account (N/A(tenant level account) in az account list) uses its tenant id as its subscription id. _access_token now tries the guard, then falls back to the switch, on exactly AADSTS90072 and AADSTS50020 and nothing else. The token is for the pinned tenant either way.

13. A new agent can start with write access to the user's mailbox

A GitHub Copilot harness agent created in the designer on 4 November 2026 came with six Work IQ capabilities, all at access: Write: mail, calendar, files, Teams, people and sites (type 9, kind: IQCapability, under a <prefix>_draft_<id> schema name). An HR assistant that answers questions about a process has no reason to write a user's mail. get_agent lists them under work_iq; remove_agent_component removes them, dry run first.

14. The evaluation grader fails every refusal you asked for

Copilot Studio's "General quality" grader checks first that each question is answered. An agent that correctly refuses (pay, another employee's rating, harassment, out of scope) is marked Fail with "question not answered", and the grader stops there. On a 10-conversation run, all 4 failures were refusals the client had specified. Read the failures before the score, and grade refusal turns with a criterion that compares to an expected answer. Second trap from the same run: a test set imported from CSV with an Expected Response column came back with that column empty in the results export, so check the export before trusting a comparison grader.

15. Not everything an agent shows is in Dataverse

Knowledge files uploaded in the designer are type 14 rows with no bytes in data: an export cannot carry them, re-upload them. The suggested prompts of a new harness agent were in no column of bots or botcomponents at all, saved or not. And when you query Dataverse yourself, encode the $filter: a raw curl with spaces in the URL fails before it reaches the server, with nothing useful in the error.

16. The source you are asked to copy may be a shell

"Reproduce the DEV agent in PROD" pointed at a DEV agent with empty instructions, no knowledge and only default topics, last edited months earlier, while the real agent, with every recent change, lived in PROD. export_agent on the source first, and a near-empty result is a reason to ask which agent is meant, not to faithfully rebuild nothing.

17. A managed environment can block a model change after publishing

In a managed production environment, switching a published agent's model was refused with a generic server error that does not name the cause. Pick the model before the first publish, and pin it rather than leaving Auto, which also keeps evaluation scores comparable from one run to the next.

The demo flow

demo-flow.json is deliberately broken, and deliberately connector-free.

"Load_settings":   { "type": "Compose", "inputs": { "batch_size": 0, ... } },
"Compute_batches": { "type": "Compose", "inputs": "@div(120, outputs('Load_settings')['batch_size'])" }

Load_settings emits batch_size: 0. Compute_batches divides by it. The run fails at the second action, and the reason is visible only in the first action's output, which is precisely the shape explain_run is built to handle.

It uses a button trigger plus two Compose actions, so it involves no connector at all. That means it creates and starts headlessly with no connection binding, sidestepping gotchas 2 and 3 entirely. If you are building your own demo, copy that choice: connector-free flows are the only ones you can reliably create end to end from an API.

The second demo flow, and why it had to exist

demo-flow-connector.json posts to a Teams channel that does not exist.

It exists because demo-flow.json cannot demonstrate the tool this repository is built around. A divide-by-zero is an expression error, and Power Automate returns those inline: the failed action carries a complete error and no outputsLink at all, so _resolve_error returns on its first branch and the blob hop never happens. The headline feature was unexercised by the headline demo, and nothing short of running it against a live tenant would have revealed that.

The connector flow produces the other shape - no error property, everything in the blob - and it is the one to run when you want to see explain_run earn its keep. It costs you a connection that must already exist in the environment, and therefore a bind_connection call, which is a fair demonstration of gotchas 2 and 3 rather than a way around them.

Keep both. They prove different things.

Extending it

Adding a tool takes three steps.

1. Find the endpoint. The Power Automate management API is the Microsoft.ProcessSimple provider. Browser devtools on make.powerautomate.com is an effective way to discover the exact shape of a call the portal makes.

2. Write the shaping function. Call the endpoint once, look at the response, and decide what is worth the model's context. Be aggressive. You can always add a field back.

3. Write the docstring like a prompt. State what it returns, which field feeds which other tool, and every constraint you discovered while building it.

@mcp.tool(annotations=ToolAnnotations(title="Resubmit Run", readOnlyHint=False,
                                      destructiveHint=True, openWorldHint=True))
def resubmit_run(flow_id: str, run_id: str) -> dict:
    """Re-run a failed run with its ORIGINAL trigger payload.

    Different from run_flow: this replays the exact data that caused the failure,
    which is what you want after fixing a definition. run_flow starts a fresh run
    with no payload and will not reproduce the case you just fixed.

    The route hangs off the trigger's history, not the run: /runs/{run}/resubmit
    is a 404. The history name is the run id; the trigger name is on the run.
    """
    run = _call("GET", f"/environments/{env_id()}/flows/{flow_id}/runs/{run_id}")
    trigger = run["properties"]["trigger"]["name"]
    _call("POST", f"/environments/{env_id()}/flows/{flow_id}/triggers/{trigger}/histories/{run_id}/resubmit")
    return {"status": "resubmitted", "source_run": run_id,
            "hint": "Asynchronous. Poll list_runs for the new run, then explain_run it."}

Note what that docstring spends its words on: not what the tool does, but when to use it instead of the tool next to it, and the one fact about the API you would otherwise learn from a 404. Disambiguating two similar tools is the highest-value sentence you can write, because choosing wrong between them is the mistake a model actually makes.

The previous version of this example called /runs/{run}/resubmit. It read perfectly, and it was wrong; see gotcha 8. Run every route once against a real tenant before you write it into a docstring.

Natural next additions, roughly in order of usefulness: approvals (list and respond), environment variables (read and set, so definitions stop carrying values), connection references for solution flows, and desktop flow runs.

Tests

pip install pytest
python -m pytest

The suite runs offline: no az, no tenant, no network. It replaces Layer 2's _call with a fake that routes (method, path) to canned API responses and records every call, so Layers 3 and 4 run exactly as written. Tests assert on the routes a tool calls, not just on what it returns, because a wrong route is a bug no return value shows (gotcha 8 would have been caught by one).

• tests/test_shaping.py - the pure functions, one test per documented gotcha: the validator's rules, the designer schema fix, seven-digit timestamps, the SAS second hop and the innerError preference, payload shaping

• tests/test_tools.py - every Power Automate tool against the fake API

• tests/test_copilot_studio.py - the agent tools against a fake Dataverse: the three shapes the instructions YAML comes in, that only that key is rewritten, the brace guard, the TaskDialog built from a flow, refresh instead of duplicate, publish waiting

• tests/test_mcp_surface.py - what a client sees, through the SDK's own in-memory client: tool counts, annotations, output schemas, and that error text reaches the model

77 tests. CI runs them on Python 3.10 and 3.13 on Linux and 3.12 on Windows, along with the import check for all three servers and a check that requirements.txt is what requirements.in compiles to. What it cannot prove is that the API still answers the way the fakes say. That is what Verified, and not is for.

Skills: the layer above docstrings

Docstrings teach the model one tool at a time. They cannot teach it the loop: which tool to reach for first, when to move to the next one, and when to stop. That knowledge lives one layer up, in skills - markdown playbooks a coding agent loads when the task matches.

Five ship in .claude/skills/:

If you open this repo in Claude Code they load automatically. If you installed the server into another project, copy the skill folders into that project's .claude/skills/ (or ~/.claude/skills/ to have them everywhere).

The division of labour is the same one the four layers made: put per-tool constraints in the docstring, put cross-tool workflow in a skill. When the model gets a single call wrong, fix the docstring; when it picks the wrong tool or gives up too early, fix the skill.

Write your own skill

A skill is a folder with one file, SKILL.md:

---
name: solution-from-base
description: Take an existing Power Platform solution, unpack it, change it as a base,
  pack it and import it back with pac. Use when asked to export, import, copy, extend
  or modify a solution, or "start from this solution".
---

# Modify a solution as a base, with pac

## 0. Point pac at the right place - every time
...

• The description is the trigger. Claude reads every skill's description and loads the body only when the task matches, so write it as "what it does, then Use when" followed by the words people actually say. A vague description is a skill that never loads.

• The body is a procedure, not documentation. Numbered steps in the order they must happen, each with the exact command or tool, then what to check. Put the step that prevents damage first - in solution-from-base that is "point pac at the right environment", because the active pac profile on a consultant's laptop is often a client's production.

• Write down what went wrong, not what the docs say. "Bump <Version> or the import reports success and changes nothing" is worth more than a paragraph on what a solution is. Same rule as docstrings: everything you get wrong twice.

• Ship the tooling with it. A skill can call scripts in the repo (scripts/dataverse_schema.py) and point at working examples (schema/orders.example.json, demo-agent-flow.json). Examples beat descriptions.

• Test it like code. Start a fresh session, ask for the task the way a colleague would, and watch whether the skill loads and whether the model follows it. Every skill here was run end to end against a real tenant before it was committed.

Where it lives decides who gets it: .claude/skills/ in a repo (everyone who opens the repo), ~/.claude/skills/ (you, in every project), or a plugin (your whole team).

Troubleshooting

Security

• No secret, and no credential of its own. The only credential involved is the refresh token the Azure CLI already holds on your machine. This repo never reads, writes or stores it, which means there is no new secret to leak and nothing to rotate if you fork this.

• The server acts as you. Every call uses your delegated permissions, so it can do anything you can do in that environment, including deleting work. Point it at a demo tenant.

• .env holds no secrets by design. A client ID and tenant ID are public identifiers. It is gitignored anyway, because environment IDs leak tenant structure.

• Write tools are live. create_flow, update_flow_definition, bind_connection and run_flow change real state with no confirmation step, and so do set_flow_state, cancel_run, resubmit_run and update_solution_flow_definition in extras.py, and create_agent_flow, add_flow_tool, update_agent_instructions and publish_agent in copilot_studio.py - a published agent change reaches every user of that agent. Only delete_flow asks twice. Every tool carries MCP annotations (readOnlyHint, destructiveHint), so a client that honours them can ask before the write ones. If you want this in a production tenant, split the read tools and write tools into two servers and connect the write server only when you mean it.

• Check the tenant before every session on a shared machine. az holds many accounts and lends whichever is active. Set PA_TENANT_ID so the wrong one fails loudly instead of writing quietly.

• Never inline secrets in flow definitions. See gotcha 6.

What is deliberately missing

This is a teaching artifact, not a complete client. Left out of server.py on purpose: everything that is not on the author, bind, run, diagnose loop. Environment discovery, start and stop, cancel, resubmit, trigger URLs, delete and the solution tools live in extras.py, which runs as a second server so the teaching core stays at ten tools. Left out of both: desktop flows, approvals, and environment variables.

Ten tools is about the number that fits in a talk while still covering a real loop: author, bind, run, diagnose. The production server this was extracted from runs twenty-seven Power Automate tools alongside Microsoft Graph and Teams, and it is the same four layers throughout.

Running extras.py

extras.py is a second server, registered separately, so server.py stays at ten tools. It adds nine: list_environments, set_flow_state, cancel_run, resubmit_run, get_trigger_url, delete_flow (which requires confirm=True), list_solutions, get_solution_flow_clientdata and update_solution_flow_definition. They are described in the tool reference.

{
  "mcpServers": {
    "power-platform":        { "command": "python", "args": ["C:/path/to/power-platform-mcp/server.py"] },
    "power-platform-extras": { "command": "python", "args": ["C:/path/to/power-platform-mcp/extras.py"] }
  }
}

Use the same interpreter for both - the venv one, if you made one. The interesting line is not in that config, it is at the top of extras.py:

from server import PowerAutomateError, _az, _call, _flow_summary, _list, _tenant_args, _trim, env_id

Nine more tools, zero new auth code and zero new transport code. Layers 1 and 2 are commodity - write them once and reuse them forever. Layer 4 is the part that had to be learned. That is the argument of this whole repository, expressed as an import.

Compared with Microsoft's plugin

Microsoft ships power-platform-skills, whose power-automate plugin bundles a 56-tool MCP server (flowagent) plus ten skills. Install it: it is good, and for most work it is more useful than this.

Where theirs is straightforwardly better: connection lifecycle management, search_operations over connector metadata, surgical action-level edit_flow, a real backup and restore subsystem, templates, desktop flows, environment routing, a deprecated-operations table, and genuinely strong $connections / $authentication reference documentation. Their install is two slash commands; this one is a clone and a pip install. They ship MCP tool annotations and they handle solution clientdata. Their validateDefinition rule set is better than the one this repo had, so _validate_definition is a port of theirs.

Where this one wins, measured on the same failed run in the same environment on 2026-08-17 (a Teams post to a channel that does not exist):

Their diagnoseRun reads a.properties?.error?.message ?? "" straight off the action record and never follows a link, so on a connector failure the message is empty and the remediation is generic. Their get_run_actions drops action outputs entirely, get_run_details is run-level, and get_run_action_repetitions is loop-only - so there is no path from a failure to the value that caused it.

They tell you where it broke and what the error says. They cannot tell you why.

That is not a claim of general superiority; it is one tool, built by someone who hit that specific wall repeatedly, beating a much larger surface at the one question it was built to answer. Which is the entire argument of this repository.

Verified, and not

Everything in the table above was run live, not read from source, on 17 August 2026. The ten server.py tools were all exercised against a real tenant then, on mcp 1.x.

On 3 November 2026, on mcp 2.x, against a real tenant, driven over stdio by the SDK's own client exactly the way Claude Code launches the servers:

• the whole core loop: list_flows, create_flow, run_flow, list_runs, explain_run, get_flow, update_flow_definition, compare_runs, analyze_flow_health, plus API errors reaching the client as text

• list_environments, set_flow_state (stop, then start, read back), cancel_run (its refusal on a finished run), resubmit_run (works on a trigger-started run, 403 on a run_flow one, both recorded in gotcha 8), delete_flow

• all six copilot_studio.py tools on a real agent: instructions read and rewritten (and braces refused), an agent flow created in Dataverse, added as a tool, refreshed, and the agent published successfully; a My flows flow refused with its reason

• scripts/dataverse_schema.py: publisher, solution, table, six column types and a lookup created and published, then a re-run reporting everything as existing

• the solution-from-base round trip with pac 2.6.3: export, unpack, a column added by hand in Entity.xml, version bumped, pack, import, and the column confirmed in Dataverse

Not verified:

• an agent calling a tool in conversation. Publishing proves the tool is valid; only a question in the test pane proves the agent chooses it. The agent-tool skill ends with exactly that check

• update_solution_flow_definition against an actual managed-solution flow, and anything in an environment without a Dataverse instance

• get_trigger_url and bind_connection on mcp 2.x (both unchanged since their 1.x live runs)

FAQ

Why not just use an official Power Platform MCP server? Often you should - Microsoft's is 56 tools and covers far more ground. See Compared with Microsoft's plugin for a measured head-to-head. The reason to build your own is layer 4: no vendor can know that your connector always fails this way in your environment. The gap in that comparison is not a gap in their engineering, it is a gap in what a generic tool can know. You also frequently want three different APIs behind one server, which nobody ships for you.

Did Claude write this? Layers 1 and 2, yes, essentially first try. Layers 3 and 4 are hand-written, because they encode things the API does not document and a model could not know. That split is the entire argument.

How long did it take? The ten tools are an evening. The docstrings are months of hitting the same walls repeatedly. That is the honest answer, and it is the more useful one.

Can I use this against a production tenant? Technically yes, and you should think hard first. See Security.

Does this work with Copilot Studio, Dataverse, or Azure DevOps? Same four layers, different base URL and scope. Swap those two constants and the structure holds unchanged. That is why the file is organised the way it is - and copilot_studio.py is the proof for Copilot Studio: nine tools across both harnesses, no new auth code, the Dataverse audience borrowed from the same az session.

One caveat on transport. Pointing this server at Dataverse or Azure DevOps is the two-constant change above, and it stays a stdio server. Making it callable from Copilot Studio is a different job: a cloud-hosted agent cannot spawn a process on your laptop, so you need Streamable HTTP, which means hosting, your own app registration and a consent flow - there is no local CLI session out there to borrow. See Transport: run it over stdio.

Why one file instead of a package? So it can be read top to bottom in five minutes. A real server should be split into modules. This one is optimised for being understood, not extended.

Built by Elliot Margot - Microsoft MVP, M365 Copilot and Copilot Studio. Licensed MIT.