The A2A Connector Template fills that gap. It’s a two-file custom connector with no script.csx that you deploy with PAC CLI. Once deployed, it shows up in the same Add agent list as the built-in options, and Copilot Studio treats it as a native A2A agent.

When to use the template

Use the built-in A2A agent option when it covers your agent. It’s simpler. Use the template when you need any of these:

The last row matters more than it looks. The built-in option creates a connector for you in one environment. The template gives you a definition you can review, commit, and deploy to dev, test, and production with the same commands.

How this differs from the Power A2A Template

In May we published the Agent-to-Agent connector and Power A2A Template. That pair wraps A2A as Model Context Protocol (MCP) tools and REST actions through a script.csx. Your Copilot Studio agent calls them as tools, and Power Automate calls them as actions.

This template takes the other path. It has no script and no tools. Copilot Studio adds the external agent as an agent, sends it A2A requests directly, and the orchestrator delegates to it like any other connected agent. Pick the Power A2A Template when you need Power Automate or want to inspect the response as tool output. Pick this one when you want the external agent to behave like a native Copilot Studio agent.

One operation, marked as A2A

The whole connector is one operation:

"paths": {
  "/your-a2a-endpoint": {
    "post": {
      "operationId": "InvokeA2A",
      "summary": "Your A2A Agent",
      "description": "Describe what the agent does and which requests it should handle.",
      "x-ms-agentic-protocol": "a2a-1.0",
      "x-ms-a2a-card-endpoint": "https://your-agent.example.com/your-a2a-endpoint/.well-known/agent-card.json",
      "x-ms-a2a-card-json": "null",
      "responses": {
        "default": { "description": "default", "schema": {} }
      }
    }
  }
}

x-ms-agentic-protocol: a2a-1.0 is what puts the connector in the Add agent list. Copilot Studio sends every A2A request to this operation.

The operation path is the agent’s message endpoint, the url in its agent card. It isn’t the agent card URL. The Microsoft Learn article makes the same point for the built-in option.

Microsoft doesn’t document these x-ms-a2a-* fields. They match what Copilot Studio generates when you add an A2A agent in the portal, which is how the template was built.

Five authentication options

Each option has its own apiProperties.json in the auth folder. Copy the one you need over apiProperties.json, then paste the matching securityDefinitions block into the API definition.

Deploys means Power Platform accepts the connector and Copilot Studio lists it. Test sign-in and a real call before you rely on it.

The PKCE option uses oauth2pkcewithdcr, the same hidden identity provider covered in the MCP public-client PKCE post. It sends PKCE on sign-in, but it sends the client secret only on token refresh. Validate both sign-in and refresh against your authorization server before production.

The Entra ID option follows the standard Entra ID pattern for custom connectors: an app registration with a client secret, a delegated permission on the agent’s API, and admin consent. You set the API’s Application ID URI and scope in apiProperties.json:

"oAuthSettings": {
  "identityProvider": "aad",
  "clientId": "[YOUR_CLIENT_ID]",
  "scopes": [ "[YOUR_RESOURCE_URI]/[YOUR_SCOPE]" ],
  "properties": {
    "IsFirstParty": "False",
    "AzureActiveDirectoryResourceId": "[YOUR_RESOURCE_URI]"
  },
  "customParameters": {
    "resourceUri": { "value": "[YOUR_RESOURCE_URI]" },
    "loginUri": { "value": "https://login.microsoftonline.com" },
    "loginUriAAD": { "value": "https://login.microsoftonline.com" }
  }
}

Point the connector at your agent

Set-A2AAgentCard.ps1 reads the agent card and rewrites the API definition. It sets host and the operation path from the card’s endpoint and records the card URL in x-ms-a2a-card-endpoint.

# Card is public
.\Set-A2AAgentCard.ps1 -CardUrl 'https://agent.example.com/a2a/.well-known/agent-card.json'

# Card requires a token
.\Set-A2AAgentCard.ps1 -CardUrl $cardUrl -BearerToken $token

# No card; you know the endpoint
.\Set-A2AAgentCard.ps1 -Endpoint 'https://agent.example.com/a2a'

The script handles both card shapes. It reads the top-level url from A2A 0.3 cards, and the first JSON-RPC entry in supportedInterfaces from A2A 1.0 cards. It rejects endpoints that aren’t HTTPS and warns when it drops a query string.

Add -EmbedCard to store the card in x-ms-a2a-card-json. Copilot Studio takes the agent’s name and description from the connector either way, so embedding is optional. Re-run the script when the card changes.

Write the description for the orchestrator

When you add the agent, Copilot Studio copies two values from the connector:

The orchestrator reads the description to decide when to delegate. Say what the agent does and which requests it should handle, for example: “Answers questions about the signed-in user’s email, meetings, and files.” The Learn article links to guidance on writing effective metadata, and it applies here.

Copilot Studio copies these values once. Updating the connector later won’t change an agent you’ve already added. Edit the description on the agent’s Agents page instead.

Deploy with PAC CLI

Create the connector with pac connector create. Don’t pass --script-file.

pac connector create `
    --environment <YOUR_ENVIRONMENT_ID> `
    --api-definition-file .\apiDefinition.swagger.json `
    --api-properties-file .\apiProperties.json

For OAuth options, Power Platform generates a redirect URL that’s unique to this connector in this environment. Download the deployed connector to read it, then register it with your authorization server:

pac connector download `
    --environment <YOUR_ENVIRONMENT_ID> `
    --connector-id <CONNECTOR_ID> `
    --outputDirectory .\deployed

(Get-Content .\deployed\apiProperties.json -Raw | ConvertFrom-Json).
    properties.connectionParameters.token.oAuthSettings.redirectUrl

Register each environment’s URL separately.

The client secret never touches your working folder. The readme writes it to a temporary copy of apiProperties.json, runs pac connector update against that copy, and deletes it. That keeps the folder safe to commit. For more on swapping identity providers this way, see Update custom connector OAuth identity providers with PAC CLI.

Add the agent in Copilot Studio

Open your agent, go to Agents → Add agent, and select your connector by its info.title. Don’t select A2A agent, which creates a separate connector. Create a connection, sign in, and select Add and configure.

In the agent’s YAML, the result is an AgentToAgentTool:

kind: AgentToAgentTool
connectionReference: <your-agent-schema-name>.cr.<connection-reference>
connectorId: /providers/Microsoft.PowerApps/apis/<your-connector-api-name>
operationId: InvokeA2A

Because A2A connections run on the custom connector infrastructure, Learn notes you can also reach agents running on-premises or inside a virtual network.

When you test, ask for the task instead of naming the agent. “What meetings do I have today?” routes better than “Use My Agent to check my meetings.” Copilot Studio forwards your words to the external agent, and that agent doesn’t know the name you gave it. If the first question right after you add the agent isn’t routed, wait a minute and ask again.

Example: Work IQ

Work IQ is the end-to-end tested case. It’s a Microsoft 365 A2A agent behind Entra ID, and its card requires a token.

Since the card needs a token, run the script with -Endpoint 'https://workiq.svc.cloud.microsoft/a2a', or pass -CardUrl with a -BearerToken. Your tenant must be enabled for Work IQ.

Work IQ also shows why protocol version matters. Copilot Studio’s documented payload uses the A2A 0.3 message/send method. Work IQ supports both versions and falls back to 0.3 when the request has no A2A-Version header, so it works without changes. If your agent accepts only A2A 1.0, expect a “method not found” error.

For a PKCE example, see Workday A2A in the same repository.

Troubleshooting

Resources

• A2A Connector Template source code
• Connect an agent over the A2A protocol
• Add other agents overview
• Authenticate a connector with Entra ID
• pac connector reference
• Work IQ A2A quickstart
• Agent2Agent protocol
• Agent-to-Agent connector and Power A2A Template

Every call is permission-trimmed to the signed-in user. Work IQ returns only data that person can already open.

What the difference looks like in a flow

Work IQ MCP does show up in the Power Automate designer — it declares capabilities: actions. Its one usable operation takes an untyped queryRequest body and returns an untyped object. Sending a single email means composing the envelope by hand:

{"jsonrpc":"2.0","id":"...","method":"tools/call",
 "params":{"name":"do_action","arguments":{"actionUrl":"/me/sendMail","jsonBody":{...}}}}

Then you add a Parse JSON action with a schema you wrote, and handle the Server-Sent Events framing and the content versus structuredContent split yourself.

This connector exposes the same capability as a Do action step with named fields, and returns a flattened result you bind to as dynamic content.

When to use something else

Use the first-party options where they fit. This connector complements them.

The typed surface costs an Entra app registration and admin consent, which the first-party connectors don’t require. That’s a one-time setup cost against a per-flow authoring cost that recurs in every flow you build. The break-even is roughly two flows.

You gain no licensing advantage. Custom connectors are premium in Power Automate, as are eight of the nine first-party connectors. This connector doesn’t expose an MCP endpoint — the first-party connectors already do that nine times over.

Eleven operations

Ask Work IQ and Ask a Copilot agent differ in transport. Ask Work IQ uses the A2A endpoint and returns a Context ID you pass into a later step to continue the same conversation. Ask a Copilot agent uses the MCP ask tool, which targets a specific agent and attaches files.

Work with entities in the order Search entity paths → Get operation schema → read or write. Paths aren’t memorable and writes reject unexpected fields, so guessing tends to fail.

fetch_blob isn’t exposed. It returns base64 file bytes up to 4 MB, which a dedicated file connector handles better.

Write access is gated

Work IQ enforces a per-tenant policy allowlist over which paths a caller may write to. This is separate from the signed-in user’s own permissions and from Microsoft 365 Copilot licensing — a user who can create an event in Outlook may still be refused by Work IQ.

Where writes aren’t permitted, Create entity, Update entity, Delete entity, and Do action return Is Error true with:

Access denied for POST /me/events. Path is not in the policy allowlist.

Check before you build. Run Search entity paths and look at the operations array for each path. In a tenant with no write entitlement, every path lists fetch and nothing else, and all four write actions are unusable.

The read actions — Ask Work IQ, Ask a Copilot agent, List Copilot agents, Search entity paths, Fetch entities, and Call function — are unaffected.

Prerequisites

• A Microsoft 365 Copilot license for every user who connects. Work IQ runs on the Microsoft 365 Copilot Chat API and returns 403 without one.
• A tenant administrator who can grant admin consent. The required permission is admin-consent only.
• Work IQ MCP not blocked in your tenant.
• For the write actions, a tenant whose Work IQ policy allowlist permits writes.

Set up the Entra app registration

Work IQ requires the delegated permission WorkIQAgent.Ask. Power Platform needs a confidential client, so you can’t reuse the public client ID shipped with the workiq CLI — register your own app.

1. In the Azure portal, go to Microsoft Entra ID > App registrations > New registration.
2. Name it, choose Accounts in this organizational directory only, and register it.
3. Under Certificates & secrets, create a client secret and copy the value.
4. Under API permissions, select Add a permission > APIs my organization uses, search for Work IQ, choose Delegated permissions, and select WorkIQAgent.Ask.
5. Select Grant admin consent.

The Work IQ API is a Microsoft first-party multitenant application, so it appears under APIs my organization uses rather than Microsoft APIs. From the CLI:

az ad app permission add --id <your-app-id> `
    --api fdcc1f02-fc51-4226-8753-f668596af7f7 `
    --api-permissions 0b1715fd-f4bf-4c63-b16d-5be31f9847c2=Scope

az ad app permission admin-consent --id <your-app-id>

Leave the redirect URI alone for now. Power Platform generates one during deployment, and you register it afterwards.

Deploy the connector

Fill in your client ID and secret in a temporary copy of apiProperties.json rather than editing the committed file, which ships with placeholders:

pac auth create --environment <your-environment-id>
pac connector create `
    --api-definition-file "./apiDefinition.swagger.json" `
    --api-properties-file "./apiProperties.temp.json" `
    --script-file "./script.csx" `
    --environment <your-environment-id>

The --script-file argument is required. Every operation is implemented by the script — the /tools/* paths exist only there and have no counterpart on the Work IQ service. Deploy without it and the connector is created successfully but every action fails.

Register the generated redirect URI

Power Platform generates a redirect URI unique to this connector and environment, and OAuth consent fails until that exact URI is registered on your app. Read it back after deployment:

pac connector download --connector-id <connector-id> `
    --environment <your-environment-id> `
    --outputDirectory ./verify
# properties.connectionParameters.token.oAuthSettings.redirectUrl

Add it to the app registration, keeping the global redirect alongside it:

az ad app update --id <your-app-id> --web-redirect-uris `
    "https://global.consent.azure-apim.net/redirect" "<per-connector-url>"

Deploying the same connector to another environment produces a different redirect URI. Register each one.

Use it from a flow

Add Ask Work IQ, supply a Question, and read Answer from the output. Pass the returned Context ID into a later Ask Work IQ step to continue the same conversation.

For deterministic reads, use Fetch entities with a path such as /me/messages?$select=subject,from&$top=25. Keep reads small — entity paths accept OData, and a bare collection path can return very large responses.

To write, confirm the path is writable first:

1. Search entity paths with a filter such as events. Check the operations listed for the path you want.
2. Get operation schema for that path to discover the fields it accepts.
3. Create entity, Update entity, Delete entity, or Do action with a body matching that schema.

Why a script rather than policy templates

The /mcp endpoint won’t return JSON. It rejects any request that doesn’t accept Server-Sent Events, and always answers with them:

Every tool response arrives as data: lines wrapping a JSON-RPC message. Inside that message the payload is either content[0].text — a JSON-encoded string, not an object — or structuredContent, depending on the tool. search_paths and fetch use the latter.

No policy template decodes SSE or parses a JSON string into an object. Without the script, each action returns raw event-stream text and every flow repeats the same unwrapping by hand. Policies can solve the routing — routerequesttoendpoint maps the /tools/* paths onto /mcp — but not the response handling.

The A2A endpoint is different: /a2a returns application/json and needs no Accept header. Ask Work IQ is scripted only to flatten the artifact tree into Answer, Context ID, Task ID, and State.

Application Insights logging is present but disabled. Set APP_INSIGHTS_ENABLED to true and supply an instrumentation key to turn it on.

Troubleshooting

Preview status

Work IQ is in public preview, and Microsoft documents it as a proprietary service whose features and APIs may change. Treat this connector as preview-grade and expect breaking changes.

Microsoft is expanding this area quickly. If first-party typed actions ship for Power Automate, they’ll likely be the better choice and this connector becomes unnecessary.

The Work IQ API also exposes WorkIQSettings.Read.All and WorkIQSettings.ReadWrite.All. Those back the administrative settings in the Microsoft 365 admin center and the Power Platform admin center, and there’s no documented HTTP endpoint for them, so this connector doesn’t use them. Manage those settings through the admin centers.

Resources

• Work IQ for Power Automate source
• Work IQ API overview
• Work IQ MCP first-party connector
• Add Work IQ to a Copilot Studio agent
• Manage AI experience access to Business Applications in Work IQ

No table relationships, column logical names, or query syntax on your side. You define which tables can answer, then ask.

Not the Web API

The Ask APIs live at /api/iq/v1.0/ and are deliberately not an OData service. There’s no metadata document, and no $select, $filter, or $expand. Use the Web API when you need precise create, retrieve, update, delete, or query operations. Use this connector when the input is a question.

The connector makes one Web API call, to read your table list for the Tables picker, because the Ask API has no table endpoint of its own. That’s the only place /api/data/ appears.

Semantic models define what can be answered

A semantic model names the Dataverse tables that can answer a question. Create one, then ask questions against it. The service decides how to answer from those tables, and returns only data the signed-in user is allowed to read.

List semantic models returns more than the models you create here, and the source property tells them apart.

You can’t delete a model you didn’t create through this API, and the maker portal can’t create a brand-new one — creation is what this connector adds. Run List semantic models with Include app and agent usage set to botinfo to see which apps and agents depend on a model before you change or delete it.

Five operations and three pickers

A sixth operation, List tables, is marked internal and backs the Tables picker.

The Delete picker matters most: that operation is keyed by ID while everything else is keyed by name, so choosing from the list saves a lookup.

Table logical names are the only names Create accepts — account, contact, opportunity. Display names, entity set names, and collection names are rejected. The picker handles that for you, filtering out private and intersect tables, and falling back to the logical name when a table has no localized label.

Include only the tables relevant to the questions the model answers. Creating a model indexes those tables, and that index consumes Dataverse database storage. You can see how much in the DataverseSearch table, counted against database storage on the Summary and Dataverse tabs.

Five tools for an agent

Add the connector to a Copilot Studio agent and the MCP endpoint advertises:

The tool descriptions steer the agent to call list_semantic_models before ask_dataverse, because the model name has to match exactly, and list_tables before create_semantic_model, because table names must be logical names. Failures come back as tool results rather than protocol errors, so an agent that passes an invalid search mode is told the three valid values and retries instead of stalling.

ask_dataverse returns the summary, the rows, the citation links, and a hasMore flag. When more rows exist it also returns the paging token and tells the agent how to use it.

Try prompts such as Which open opportunities have the highest estimated revenue? or Summarize the opportunities for Contoso.

Working with the answer

Rows (rawResult) is an array of dynamic objects. Its shape depends on the question and on the query the service generated to answer it, so there’s no fixed schema and no design-time dynamic content for individual fields. Parse it with the property names you expect from the question, or run the question once and read the output to learn the shape.

Summary, Citation links, and Rows are all nullable. Display the summary when it’s there, but don’t require it before processing the rows.

Results are trimmed to the caller’s Dataverse privileges. Record ownership, business unit access, sharing, and column-level security all change what comes back, so two users asking the same question can get different answers.

Search mode controls the tradeoff between speed and depth:

ThinkDeeper can take noticeably longer. In a flow, raise the action timeout; in an app, show progress.

Set Row count to cap the page size. When more rows exist, the response carries a Paging token — send the same question, model, search mode, and count again with that token to get the next page, and continue until the token comes back null or empty. Pass the token back exactly as returned; don’t decode, edit, or construct one.

List and Ask are safe to retry after a transient failure. Create and Delete aren’t, because model names must be unique. List the models first to find out whether the original request actually succeeded, and treat a missing model after an uncertain delete as a completed delete. Retry 429, 500, 502, 503, and 504, honoring Retry-After when present and backing off exponentially with jitter otherwise.

Indexing takes time

A model doesn’t answer well the instant it’s created. Initial generation can take up to two hours; later incremental changes typically settle within 30 minutes. An Ask sent immediately after Create can return thin results or none. Models then regenerate automatically every 12 hours to pick up schema changes.

Semantic models don’t support ALM. Environment copy and move operations don’t carry them, and after either one an administrator has to turn the feature off and back on in the Power Platform admin center to force a restart.

Fine-tuning a model

Answer quality comes from more than the table list. The model extracts signals from metadata you already have — table relationships, public and sub-grid views, form display names, table and column description summaries, and optionally sample data rows. Sample rows are off by default. System views such as Quick Find, Advanced Find, Associated, and Lookup are excluded, as are personal views.

Well-written table and column descriptions are the cheapest way to improve answers, because the model reads them directly.

Once a model exists, tune it on the Semantic model page in Power Apps:

• Signals — turn inferred signal types on or off, exclude sensitive tables, disable views and relationships that mislead
• Glossary — add acronyms, synonyms, and organization-specific vocabulary the system can’t infer
• Refresh — trigger a manual regeneration to apply changes without waiting for the 12-hour cycle

Deploy it

You need a Dataverse environment, and Business Applications in Work IQ turned on for it in the Power Platform admin center. Without that feature, every call returns 400. The connection user also needs a security role that grants semantic model privileges: Dataverse Search Role, Environment Maker, System Customizer, or System Administrator. Ask API usage is billed through Copilot Credits.

Register an app in Microsoft Entra ID, add the delegated Dynamics CRM → user_impersonation permission, and add https://global.consent.azure-apim.net/redirect to its web redirect URIs. Copy the application ID and create a client secret.

In apiDefinition.swagger.json, set host to your environment hostname. In apiProperties.json, replace [YOUR_CLIENT_ID] with your application ID and replace https://org.crm.dynamics.com in both AzureActiveDirectoryResourceId and resourceUri with your environment URL. Leave redirectUrl as [YOUR_REDIRECT_URL], since the platform substitutes the real value at deploy time.

pac auth create --environment <your-environment-url>

pac connector create `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file apiProperties.json `
  --script-file script.csx

--script-file is required. Without it the connector deploys, but the MCP endpoint returns nothing usable, because the script is what answers the JSON-RPC calls.

pac has no parameter for the client secret. Paste it in Power Apps → Custom connectors → Dataverse Ask → Edit → Security, or set clientSecret in a temporary copy of apiProperties.json, deploy from that copy, and delete it afterwards. Never put a secret in the file you keep.

The platform generates a redirect URL unique to this connector and environment. Read it back and register it:

pac connector download --connector-id <connector-id> --outputDirectory ./verify

The value sits at properties.connectionParameters.token.oAuthSettings.redirectUrl. Add it to the app registration alongside the generic one. OAuth consent fails until it’s registered, and a second environment produces a different URL that also needs registering.

Test in the right order

Create a connection, then run List semantic models with no parameters. A 200 confirms auth, host, and feature enablement in one call, and it answers immediately without depending on indexing. An empty list is still a pass; the environment simply has no models yet.

Then run Create semantic model with a unique name and a couple of tables from the dropdown:

A populated Tables dropdown is a second check on its own: it proves the connection can read table metadata.

Don’t ask a question yet. Indexing starts on creation, and initial generation can take up to two hours. Come back afterwards and run Ask a question against Sales pipeline with something like Which open opportunities have the highest estimated revenue? Rows and a summary confirm the model is live.

To test the MCP endpoint without waiting on indexing, add the connector to a Copilot Studio agent and ask it what semantic models exist. That exercises discovery and a tool call.

When something comes back wrong

Telemetry is off by default. Set APP_INSIGHTS_ENABLED to true in script.csx and replace APP_INSIGHTS_KEY with your instrumentation key to log tool calls with their outcome and failures with their error code and message. Telemetry never fails a tool call.

Where it sits next to the others

Work IQ and Dataverse Ask complement each other. Once an administrator enables Business Applications in Work IQ, the Work IQ connector can also reach Dataverse. This connector is the direct path, and the only one that can create a semantic model.

Resources

• Dataverse Ask connector source
• Dataverse Ask APIs
• Work IQ API overview and licensing
• Manage feature settings
• Write code in a custom connector

The connector runs in two modes off one definition: 22 typed REST operations for Power Automate and Power Apps, and a /mcp endpoint that gives a Copilot Studio agent the same surface as tools.

Finding the API

There’s no published REST reference for this service yet, so the surface here was derived from the shipped CLI and then confirmed against the live tenant. The confirmation came from contrasting two responses on an environment-scoped host:

An unknown path is rejected by routing. /appframework/apps gets past routing and fails only on authorization, so the route is real and serving traffic. The 403 body names exactly what it wants:

{
  "code": "Forbidden",
  "innererror": {
    "code": "InsufficientDelegatedPermissions",
    "message": "Authorization denied: Application missing required delegated permissions: [PowerApps.Apps.Read, ManagedApps.ReadWrite.All, All.All.ReadWrite]"
  }
}

ManagedApps.ReadWrite.All is a published delegated scope on the first-party Power Platform API application 8578e004-a5c6-46e7-913e-12f58912df43, and it’s user-consentable. That makes this a supported surface rather than an internal backchannel.

The host isn’t the host

Copilot Managed Runtime calls don’t go to api.powerplatform.com. They go to an environment-scoped host derived from the environment ID: lowercase it, strip the dashes, then split the last two characters off into their own label.

b5e65502-f2e4-ecc7-8e66-df670e46b100
  → b5e65502f2e4ecc78e66df670e46b1.00.environment.api.powerplatform.com

The swagger declares api.powerplatform.com to satisfy Power Platform, and script.csx rewrites every request to the real host. That’s why every operation takes an environmentId and why all of them are listed in scriptOperations. Default environments carry a Default- prefix on the ID, and the same normalization handles them.

In the designer the environmentId comes from a dynamic dropdown, so you pick an environment by name.

What you get

Every operation except Get environment dropdown takes an environmentId.

Apps

Build and deploy

Sharing and access

Connectivity

Repository binding

Two ways to ship a build

The normal path is BuildApp, then poll GetBuildOperation, then DeployApp.

UploadBuild skips the server-side build. Send a zip of the built output, the service commits it and returns a commitSha, and you pass that SHA to DeployApp. It’s the one operation that writes code into the app’s repository, and it isn’t a substitute for Git — ordinary source control stays git add, git commit, git push, which is what the repository binding operations exist to authorize.

Watch the size. Power Platform caps the total payload through a custom connector at 100 MB while the service itself accepts 500 MB, so the connector ceiling is the one you hit first. The script checks before sending, so an oversized artifact fails immediately with a clear message instead of a late 413. Over MCP the effective limit is lower still, since the zip has to be base64 encoded and base64 adds roughly a third. For anything larger, run ms deploy --artifact <file>.zip.

Binding a GitHub repository

Pointing an app at your own repository requires the repository owner to authorize the Managed Apps GitHub App, which runs as a device code flow across two operations.

StartGitHubAuth takes a full repository URL such as https://github.com/owner/repo and parses out the owner, repository, and GitHub base URI. GitHub Enterprise Cloud hosts work too. Show the user the returned userCode and verificationUri, then poll GetGitHubAuthStatus no faster than pollIntervalSeconds until expiresIn elapses.

Pass the oauthBaseUri from StartGitHubAuth straight back into GetGitHubAuthStatus. It defaults to https://github.com, which is wrong for GitHub Enterprise Cloud repositories.

The agent side

The /mcp endpoint speaks JSON-RPC 2.0 and implements initialize, tools/list, tools/call, resources/list, ping, and the notifications/* methods. Tools carry a managedapps_ prefix and mirror the REST operations, plus one extra: managedapps_list_environments, so an agent can find the environmentId every other tool needs.

A few requests an agent handles end to end:

• “Which apps can I edit in the Contoso environment?” → managedapps_list_environments, then managedapps_list_apps with permission: "write"
• “Deploy the latest build of the expense tracker.” → managedapps_list_apps, managedapps_build_app, poll managedapps_get_build_operation, then managedapps_deploy_app
• “Why did that build fail?” → managedapps_get_build_log
• “Who has access to this app?” → managedapps_list_role_assignments and managedapps_list_share_links
• “Connect my app to github.com/contoso/expenses.” → managedapps_start_github_auth, show the code and URI, then poll managedapps_get_github_auth_status

managedapps_upload_build takes the zip as base64 in zipContentBase64.

A note on naming

The product was called Managed Apps before the rename to Copilot Managed Runtime, and the old name survives in identifiers that aren’t safe to change:

The connector’s operation IDs and MCP tool names keep the managedapps prefix for the same reason. Renaming them would break agents and flows already bound to them.

Licensing

Everyone who runs an app needs coverage, including you while you’re developing.

Without sufficient credits a user is warned first and can keep working, then blocked at 20 app operations or five minutes of use, whichever comes first. Power Apps Premium users aren’t subject to those limits.

Deploy it

Register an app in Microsoft Entra ID and add these delegated permissions from the Power Platform API (8578e004-a5c6-46e7-913e-12f58912df43):

All three are user-consentable, so admin consent is optional unless your tenant requires it.

Replace [YOUR_CLIENT_ID] in apiProperties.json with your application ID. Leave [YOUR_REDIRECT_URL] alone — the platform generates a per-connector redirect URL on deploy and discards whatever you supply.

Because scriptOperations is non-empty, the script and the definition must always travel together. Omit --script-file and you get InvalidScriptDefinitionUrlWithNonNullOperations.

Create the connector in two steps. A script-enabled connector needs a function app assigned from a regional pool when it’s first created, and requesting that during create frequently fails:

pac auth create --environment <environment-id>

# Step 1 - create without the script
$p = Get-Content apiProperties.json -Raw | ConvertFrom-Json
$p.properties.PSObject.Properties.Remove('scriptOperations')
$p | ConvertTo-Json -Depth 40 | Set-Content "$env:TEMP\noscript.json" -Encoding UTF8

pac connector create `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file "$env:TEMP\noscript.json"

# Step 2 - attach the script using the ID returned above
pac connector update `
  --connector-id <connector-id> `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file apiProperties.json `
  --script-file script.csx

Updating an existing connector is a single pac connector update, since it already holds an assigned function app.

A success message means the row was written, not that the definition survived intact. Download it back and check for 22 operations, x-ms-agentic-protocol: mcp-streamable-1.0 on the /mcp path, and the environment dropdowns:

pac connector download --connector-id <connector-id> --outputDirectory ./verify

The generated redirect URL sits at properties.connectionParameters.token.oAuthSettings.redirectUrl in the downloaded file. Register it, or OAuth consent fails:

az ad app update --id <appId> --web-redirect-uris `
  "https://global.consent.azure-apim.net/redirect" "<per-connector-url>"

That URL encodes both the connector name and the environment, so a connector deployed to dev and prod produces two different URLs and both need registering.

Caveats

This is public preview, and explicitly volatile. The microsoft/managed-apps README states that APIs, templates, and tooling may change before general availability, and there’s no versioned public contract for these routes. Treat the connector as tracking a moving target.

Repository create and delete are excluded. The CLI builds routes under /appframework/git/repositories, but that path returned RouteNotFound during testing while /appframework/apps did not — feature-gated or not uniformly deployed. Those operations are left out rather than shipped broken. The GitHub device code routes under /appframework/github/auth are a separate surface and are included.

Response schemas are best-effort, reconstructed from the CLI’s own mock fixtures and type usage. The script projects responses defensively, reading both flat and properties-nested shapes, so a server-side shape change degrades to null fields rather than a hard failure.

api-version=1 is pinned. Deployment has a newer manageddevops backend behind a CLI feature gate; this connector uses the stable appframework path.

When something comes back wrong

Telemetry is off by default. Replace APP_INSIGHTS_CONNECTION_STRING in script.csx with your connection string to record MCP method calls, tool invocations, and tool errors. Telemetry failures are swallowed and never affect the caller.

Resources

• Copilot Managed Runtime connector source
• Announcing Copilot Managed Runtime
• What is Copilot Managed Runtime
• Copilot Managed Runtime SDK overview
• Copilot Managed Runtime for admins
• microsoft/managed-apps
• @microsoft/managed-apps-cli
• Power Platform API reference
• Write code in a custom connector

Hosted skills are in preview, so endpoint names and configuration keys can still change.

Turn on the chat API first

The built-in endpoints are off by default. Switch them on in each .agent.md file you want to call:

---
name: Order Triage
description: Classifies an order problem and drafts a reply.
builtin_endpoints:
  chat_api: true
---

You classify order problems. Given a customer message, return the severity,
the responsible team, and a draft reply.

A skill with builtin_endpoints enabled needs no trigger. It can have both — a timer trigger for its scheduled run and a chat API for on-demand calls. builtin_endpoints: true is shorthand for everything: the chat API, the browser debug UI, and the runtime’s own MCP surface.

The skill’s slug is its file name. order_triage.agent.md has the slug order_triage, and that slug is what every operation takes. Skills can sit at the app root or in an agents/ folder; the slug carries no folder either way.

Only built-in endpoints are reachable here. A skill whose trigger is http_trigger gets its own route, such as /summarize, and needs a plain HTTP action — or add builtin_endpoints alongside the trigger.

Six operations

Both surfaces hit the same endpoints, so a skill you expose to a flow is immediately available to an agent.

Discovery costs you a key choice

Skill is a dropdown, not a free-text box, filled by List hosted skills. That operation reads the function app’s admin API, which accepts only the app’s _master key. So the picker works on one condition:

A host key is the least-privilege choice and costs you only the picker. You type slugs instead, and the slug is always the .agent.md file name without its extension. Nothing else changes. Discovery also stops working when the function app has admin isolation enabled, since the runtime itself publishes no catalogue endpoint.

Sessions carry the conversation

Omit the session ID on the first call and the runtime mints one, returns it in session_id, and stores the transcript in the app’s AzureWebJobsStorage account. Pass that value back and the skill sees everything said before. Two calls without a session ID are two unrelated conversations, even against the same skill.

In a flow, capture session_id from the first response and feed it into every later call in the same run. Supplying your own is fine — session IDs accept letters, digits, dots, hyphens, and underscores up to 128 characters, so a support ticket number makes a good one because it resumes the same conversation days later.

Get session transcript returns at most the 200 most recent turns and sets truncated when older ones were dropped. The skill’s own memory is unaffected; only the transcript you read back is capped.

Tool calls come back with the answer

tool_calls reports what the skill did to produce its response: one entry per tool, with the name, the arguments it was given, and what it returned. The type field reads tool_start even on a completed call, because the runtime merges the call and its result into a single entry on this path.

Arguments and results arrive as text, with structured values rendered as JSON. They map onto a single string column, so you can show them in an approval card or write them to a log table.

Two minutes, and what to do about it

A Power Platform request times out at roughly 120 seconds. A skill that searches the web, runs sandboxed Python, and calls three connectors can exceed that. Two ways around it:

Let the skill start a dynamic workflow. Skills with workflows.enabled: true in their front matter return quickly with work running in the background. Poll it with Get dynamic workflow status until runtime_status leaves Running, then read output. The Workflow ID field is a dropdown, filled from the workflows the chosen skill started in the session you name, each labelled with its status and start time.

Trigger the skill instead of calling it. If nothing in the flow needs the answer, give the skill a queue or Event Grid trigger and let the function app own the run.

Stopping a workflow is not an operation here. The runtime’s cancel_workflow and terminate_workflow are tools the skill holds, not HTTP endpoints, so there’s nothing for a connector to call. To stop a run, send the skill a prompt in the same session asking it to cancel that workflow.

A workflow that fans out to specialist skills doesn’t make those specialists visible here. Subagents are separate .agent.md files that usually have no builtin_endpoints of their own, so they won’t appear in the Skill list and can’t be invoked directly — which is the intent.

Retries stop at the skill boundary

Reads — transcript, workflow list, workflow status, and skill discovery — are retried up to three times on 429, 502, 503, or 504, honoring Retry-After when the app sends one. A function app scaling from zero produces exactly these codes, and retrying is invisible to your flow.

Invoking a skill is never retried. A hosted skill can send mail, update a record, or start a workflow before the throttle was applied, so replaying it risks doing that work twice. A throttled invoke fails with the wait time the app asked for, and whether repeating it is safe is your call.

Five tools for an agent

Add the connector to a Copilot Studio agent as an MCP tool and it publishes:

Every tool except list_skills takes an optional agent argument naming the skill. Omit it and the connector resolves the skill itself when the app hosts exactly one callable skill, which means a single-skill app needs no configuration at all. When the app hosts several, or the skills can’t be listed, the tool returns an error telling the agent to call list_skills and choose. Auto-resolution needs the skill list, so it works on the same terms as discovery.

The connector also sends a short set of instructions when Copilot Studio connects: discover skills before guessing at one, carry session_id between turns, and poll a dynamic workflow rather than assuming the skill finished. That guidance reaches the orchestrator without you writing it into every agent.

invoke_skill returns session_id in its result, which lets an agent continue the same hosted-skill conversation across turns by passing that value back. The agent has to carry it deliberately — Copilot Studio’s conversation state and the hosted skill’s session are separate things.

This is worth doing when the hosted skill knows something the agent does not. A skill wired to a Connector Namespace can reach SAP, Salesforce, or a line-of-business SQL database, run model reasoning over what it finds, and return a conclusion. The agent gets one clean tool instead of a dozen raw API calls.

You don’t need builtin_endpoints.mcp: true for any of this. That setting exposes the skill on the runtime’s own MCP endpoint, which the Functions MCP extension owns and which requires a separate system key. This connector builds its MCP surface from the chat API instead, so one key covers everything and you get five tools rather than one.

Tool results are trimmed before they reach the agent. A skill that scraped a dozen pages can return more than an agent’s context window holds, so oversized results have their tool-call detail shortened first and, if that isn’t enough, are truncated with a note saying so. The skill’s own answer is preserved, and Invoke a hosted skill always returns the complete payload.

Deploy it

Deploy the function app with chat_api enabled on every skill you plan to call. Then collect two values from the Azure portal: the default domain from the function app’s Overview page, such as contoso-skills.azurewebsites.net, and a host key from Functions → App keys. A host key works for every skill in the app. Use the _master key instead if you want the Skill picker populated, or scope access to one skill by copying a key from that skill’s _builtin_chat function.

pac connector create `
    --api-definition-file ./apiDefinition.swagger.json `
    --api-properties-file ./apiProperties.json `
    --script-file ./script.csx

Create a connection with the hostname and the key — those are the only two settings — and run Invoke a hosted skill with a slug and a prompt. A successful call returns response, session_id, and tool_calls.

The route prefix needs no configuration. The runtime registers its endpoints under the Functions route prefix, which defaults to api but is empty in the official quickstart’s host.json. The connector tries the declared path first and retries the other layout on a 404, so both work.

script.csx ships with Application Insights logging off. Set APP_INSIGHTS_ENABLED to true and replace APP_INSIGHTS_KEY with your instrumentation key to record skill invocations, MCP tool calls, and failures. Telemetry failures are swallowed and never affect a call.

Signing in with Microsoft Entra ID

Import apiProperties-entra.json instead of apiProperties.json to authenticate with Microsoft Entra ID. Everything else — the Swagger definition, the script, the operations — is identical. Use it when your skills set http_auth.mode: entra, or when your tenant disables function keys.

This path is built from the runtime’s documented behavior but hasn’t been exercised against a live Entra-protected app, so treat it as a starting point rather than a verified recipe. The function-key path is tested end to end.

The function app must have App Service Authentication turned on. The runtime doesn’t validate tokens itself; it accepts an Entra caller only when the platform has already done that work. Register an application for the function app with an Application ID URI such as api://<app-id> and a user_impersonation scope, point App Service Authentication at it, then fill in the client ID and both Application ID URI placeholders in apiProperties-entra.json. After importing, read back the redirect URL the platform generated and add it to the app registration. That value is specific to the connector and the environment, so a connector in two environments produces two URLs.

Skill discovery is unavailable in this mode. The admin API accepts only the master key, and this configuration has no key parameter to put it in — deliberately, since the reason to run in Entra mode is usually that you don’t want master keys stored in connections. Type slugs instead, and name the skill explicitly on every MCP tool call.

Resources

• Azure Functions Hosted Skills connector
• Azure Functions hosted skills
• Hosted skills reference
• Dynamic workflows
• Azure Functions Agents Runtime

Two rough edges the connector absorbs

Calling the sql option directly means dealing with both of these yourself.

The entity set in the URL must match the base table of the query. A query beginning FROM account has to go to /accounts, and FROM msdyn_botsession to /msdyn_botsessions. The connector reads the FROM clause, resolves the entity set from table metadata, and builds the URL. You write the table name and never the entity set.

The supported subset is narrow, and a rejected statement returns a raw fault. Every statement is checked locally first. Anything unsupported comes back as a named issue — select_star, having, unsupported_join — describing what to write instead, with no round trip to Dataverse.

Everything is read-only. A statement must be a single SELECT, and write keywords are rejected before the request is built.

Seven visible operations

An eighth operation, Get row schema, is marked internal and backs the dynamic content below.

Execute SQL takes the statement, a page size, an optional row budget, and a switch for formatted values. Formatted values add display text for choice, lookup, and date columns as @OData.Community.Display.V1.FormattedValue annotations next to the raw values.

Column names come from a sample row, not a prediction

The designer resolves the columns your statement returns and offers them as typed dynamic content, so you pick name or revenue directly instead of writing item()?['name']. Types come from Dataverse metadata for whichever table each alias refers to, so in a join c.birthdate is typed from contact rather than the base table. Aggregates are typed from their function: COUNT(*) is a whole number, SUM() a decimal, and MIN()/MAX() inherit the type of the column they wrap.

Two behaviors shape how that works.

Alias your aggregates. Dataverse names an aggregate column after its alias, so SELECT COUNT(*) AS total produces a total field while a bare SELECT COUNT(*) produces a field this connector cannot name and therefore omits.

Dataverse also decides what comes back, not your SELECT list. A plain query returns the primary key and @odata.etag on top of what you asked for, and some tables add more — systemuser and team return ownerid unselected, while queue and role do not. An aggregate query returns only its aliased columns. That pattern isn’t derivable from metadata, so the connector runs your statement once for a single row at design time and reads the real column names:

var sampled = await SampleRowAsync(table, validation.Statement).ConfigureAwait(false);

An empty table has no row to inspect, so the schema falls back to the SELECT list plus the primary key and etag, and the response reports sampled: false.

Resolution happens at design time against the statement in the box. Build the statement from an expression and there’s nothing to inspect yet, so rows stays untyped. The action still runs normally.

Six tools for an agent

Add the connector as a tool in Copilot Studio and the MCP endpoint exposes:

The tool descriptions carry the supported subset, so an agent generally writes a valid statement on the first attempt. When it doesn’t, failures come back as tool results rather than protocol errors, and the agent reads the issues and valid values and retries instead of stalling. An unknown table name returns near matches from your environment.

The intended path is list_tables → describe_table → run_sql. An agent that skips discovery and guesses column names gets corrected by unknown_column, but those round trips are avoidable.

What the subset covers

Out of scope: SELECT *, subqueries, CTEs, HAVING, UNION, RIGHT JOIN, FULL JOIN, CROSS JOIN, CASE, COALESCE, window functions, and string, date, or math functions beyond the two above. WHERE cannot compare two literals or two columns, and cannot apply a function to a column value. ORDER BY and GROUP BY take columns only, including date parts, so GROUP BY MONTH(createdon) is rejected.

A statement that fits looks like this:

SELECT a.name, COUNT(*) AS contact_count
FROM account AS a
INNER JOIN contact AS c ON a.accountid = c.parentcustomerid
WHERE a.createdon >= DATEADD(day, -30, GETUTCDATE())
GROUP BY a.name
ORDER BY a.name

Paging without a loop

Set the page size on Execute SQL and it becomes Prefer: odata.maxpagesize. When more rows exist, hasMore is true and nextLink carries the continuation — pass it to Get next page unchanged. Next links are checked against your environment before they’re followed.

Get next page returns the same shape, but sql, table, and entitySet come back empty. A next link carries the continuation token, not the statement that produced it, so carry those values forward from the first call if you need them.

To collect several pages in one action, set Maximum rows. The connector follows next links itself until it has that many rows, and stoppedBecause reports which limit ended the run:

The final page may carry the total slightly past Maximum rows, because pages are never split. Whenever paging stops with rows remaining, nextLink still comes back, so a flow resumes exactly where it left off. Leave Maximum rows at 0 for a single page.

TOP and OFFSET … FETCH are accepted but flagged with a warning. The Dataverse reference lists them as supported syntax while its paging guidance says they aren’t honored. Prefer the page size, or page by filtering on the last id you saw:

SELECT name, accountid
FROM account
WHERE accountid > '00000000-0000-0000-0000-000000000000'
ORDER BY accountid

Throttling that outlasts the script

Dataverse enforces service protection limits by returning 429 with a Retry-After header. The connector waits and retries automatically when that wait is short.

The wait scales with how demanding the previous five minutes were, so it can exceed the two minutes a connector script is allowed to run. When it does, the call returns a throttled error carrying retryAfterSeconds rather than being killed mid-wait. Handle it in a flow with a Delay of that many seconds followed by a retry.

Other ceilings worth knowing:

For the aggregate limit, add a filter — typically a date range or a subset of a choice column — and combine the results of several runs.

Deploy it

Register an app in Microsoft Entra ID, add the Dynamics CRM → user_impersonation delegated permission, grant consent, and create a client secret. Add https://global.consent.azure-apim.net/redirect as a web redirect URI.

Then point the files at your environment. In apiDefinition.swagger.json, set host to your environment hostname. In apiProperties.json, replace [YOUR_CLIENT_ID] with your application ID and replace https://org.crm.dynamics.com in both AzureActiveDirectoryResourceId and resourceUri with your environment URL. Leave redirectUrl as [YOUR_REDIRECT_URL], since the platform substitutes the real value at deploy time.

pac auth create --environment <your-environment-url>

pac connector create `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file apiProperties.json `
  --script-file script.csx

pac has no parameter for the client secret. Paste it in Power Apps → Custom connectors → Dataverse SQL → Edit → Security, or add it as clientSecret inside oAuthSettings in a temporary copy of apiProperties.json, deploy from that copy, and delete it afterwards. Never put a secret in the file you keep.

The platform generates a redirect URL unique to this connector and environment. Read it back and register it:

pac connector download --connector-id <connector-id> --outputDirectory ./verify

The value sits at properties.connectionParameters.token.oAuthSettings.redirectUrl. It encodes the publisher prefix, the connector name, and the environment, with characters escaped — _ becomes -5f and a space becomes -20:

https://global.consent.azure-apim.net/redirect/new-5fdataverse-20sql-5f<ENVIRONMENT_SUFFIX>

Copy the whole value exactly as downloaded rather than assembling it by hand, and add it to the app registration alongside the generic one. OAuth consent fails until it’s registered, and a second environment produces a different URL that also needs registering.

Create a connection, then run List tables with no parameters. A list of your tables confirms auth, host, and script are all wired up.

When something comes back wrong

Telemetry is off by default. Set APP_INSIGHTS_ENABLED to true in script.csx and replace APP_INSIGHTS_KEY with your instrumentation key to record executed statements, MCP tool calls, validation failures, and unhandled errors. Telemetry failures never fail an operation.

Resources

• Dataverse SQL connector source
• Use SQL to query data with the Dataverse Web API
• Page results
• Service protection API limits
• Query anti-patterns
• Write code in a custom connector

Why the two surfaces belong together

The ontology MCP endpoint is addressed per item:

https://api.fabric.microsoft.com/v1/mcp/dataPlane/workspaces/{workspaceId}/items/{ontologyItemId}/ontologyEndpoint

Those GUIDs have to be literals in the swagger path. An operation carrying x-ms-agentic-protocol must not declare a parameters key, and Copilot Studio rejects the operation if one is present. The MCP side is pinned to a single ontology as a result.

That’s where the REST operations start paying for themselves. List Workspaces and List Ontologies hand you the two GUIDs to paste in, with dropdowns, instead of reading them out of a portal URL. After setup they keep working for definition round-trips, ALM, and provisioning.

Fourteen operations

Seven cover ontology items themselves:

Six more exist to feed them. List Workspaces, List Folders, List Lakehouses, and List Lakehouse Tables populate dropdowns and supply data binding sources. Get Operation State and Get Operation Result poll long running operations.

The fourteenth is Invoke Fabric Ontology MCP, the JSON-RPC endpoint above.

Dropdowns instead of GUID copy-paste

Each dependent picker passes its parent through x-ms-dynamic-values.parameters, so choosing a workspace refilters everything below it:

List Workspaces ──▶ workspaceId
                      ├──▶ List Ontologies  ──▶ ontologyId
                      ├──▶ List Folders     ──▶ rootFolderId
                      └──▶ List Lakehouses  ──▶ lakehouseId ──▶ List Lakehouse Tables

List Lakehouse Tables is the exception. Table names belong in the body of an entity type data binding, at sourceTableProperties.sourceTableName, and Swagger 2.0 dynamic values can’t populate a nested body property inside an array. Run it as its own action and read the names off the result.

Definitions arrive readable

Fabric returns and accepts ontology definitions as base64 parts:

{ "path": "definition.json", "payload": "e30=", "payloadType": "InlineBase64" }

script.csx removes the encode and decode steps on both sides. On read, each part gains a payloadText field holding the decoded JSON, with the original payload preserved. A part whose payload isn’t valid base64 is left alone rather than failing the call. On write, supply readable JSON in payloadText and the script encodes it into payload and sets payloadType.

A definition round-trip becomes: get definition, edit payloadText, update definition. No base64 actions in the flow.

A 202 with an empty body is still useful

Create Ontology, Get Ontology Definition, and Update Ontology Definition can return 202 with nothing in the body and everything in the headers. Power Automate can’t read those headers off a connector response, so the script builds a body from them:

{
  "status": "Accepted",
  "operationId": "0acd697c-1550-43cd-b998-91bfbfbd47c6",
  "location": "https://api.fabric.microsoft.com/v1/operations/0acd697c-1550-43cd-b998-91bfbfbd47c6",
  "retryAfter": 30
}

Poll Get Operation State with that operationId until status is Succeeded, then call Get Operation Result.

One detail matters if you fork the script. In some regions Power Platform delivers Context.OperationId base64 encoded, so the script handles both forms. Drop that decoding and the definition and LRO transformations quietly stop running in affected regions while calls still return 200.

The scope that separates ontology from data agents

Register an Entra app for a single tenant and add these delegated permissions, then grant admin consent:

Item.Execute.All is easy to miss. A Fabric data agent uses DataAgent.Execute.All; ontology and Power BI semantic model endpoints use Item.Execute.All. Leave it out and every REST operation works while the MCP endpoint returns 403.

Two more auth settings decide whether connections behave. Set the OAuth tenant to your tenant GUID rather than common, which causes intermittent per-user failures against the Fabric data-plane endpoints. For on-behalf-of single sign-on, preauthorize Azure API Connections (fe053c5f-3692-4f14-aef2-ee34fc081cae) under Expose an API → Authorized client applications on an access_as_user scope.

The connector requests https://api.fabric.microsoft.com/.default, so it inherits whatever is consented on the app registration. Adding a scope later means re-consenting and recreating connections, because a connection caches its token audience.

Deploy it

cd "Fabric Ontology"

pac connector create `
  --environment <YOUR_ENVIRONMENT_ID> `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file apiProperties.json `
  --script-file script.csx

--script-file is required. The connector declares scriptOperations, and omitting the script fails deployment with InvalidScriptDefinitionUrlWithNonNullOperations.

A returned connector ID means the record was written, not that the definition arrived intact. Download it back and confirm 14 operations, the dynamic dropdowns, and a matching script.csx:

pac connector download --connector-id <id> --outputDirectory ./verify

Read the generated redirect URL from that download at properties.connectionParameters.token.oAuthSettings.redirectUrl and register it on the app registration. The URL encodes both the connector name and the environment, so dev and prod produce two different values and both need registering.

Then point the MCP operation at a real ontology. Create a connection, run List Workspaces and List Ontologies in the Test tab, and replace WORKSPACE_ID and ONTOLOGY_ITEM_ID in the MCP path before redeploying. Both GUIDs also appear in the Fabric portal URL when the ontology is open:

https://app.fabric.microsoft.com/groups/<workspace-ID>/ontologies/<ontology-item-ID>

Test the MCP side before wiring an agent

In the Test tab with Raw Body on, send an initialize call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "power-platform-test", "version": "1.0.0" }
  }
}

Expect HTTP 200 with result.protocolVersion and result.serverInfo, then follow with tools/list. The operation ID is not an MCP method: InvokeMCP is the Power Platform operation, while method in the body must be initialize, tools/call, or tools/list.

In Copilot Studio, add the connector as a tool, select Invoke Fabric Ontology MCP, enable generative orchestration, and publish. Keep the tool on user authentication. Ontology honors Fabric RBAC, and a shared maker connection would show every user the maker’s view of the data.

What it can’t do

One connector serves one ontology on the MCP side. Ten ontologies means ten connectors, or ten copies of the MCP operation with different literal paths. The REST operations stay fully parameterized and cover every ontology in the tenant from one connection.

There are no unattended MCP scenarios either. Delegated auth means an autonomous agent fired by a schedule has no signed-in user and no identity for the data-plane call. Service principals and managed identities work for the REST operations, so ALM automation is fine.

Ontology items, the ontology MCP server, and the lakehouse tables API are all in preview, with no SLA and endpoint shapes that can change.

Resources

• Fabric Ontology connector source
• Ontology items REST API
• Ontology definition structure
• Consume ontology as an MCP server
• Fabric REST API scopes
• Configure OBO authentication for custom connectors

Dataverse Catalog Tree is a custom MCP connector for recursive 1:N hierarchies in Dataverse. It serves two consumers from one traversal engine.

Why chaining produces hallucinations

Traversing a tree through a generic query tool means the model chains calls, and at every hop it supplies a relationship name, a lookup column, and a GUID. Each of those is a chance to invent something plausible. By the fourth hop the model is reasoning about records it never read.

The worse failure is quieter. A branch that was never expanded looks exactly like a branch that ends. The agent reports a leaf node with total confidence, and nothing in the response contradicts it.

This connector removes the chaining. One call returns the finished subtree, assembled server-side, with explicit accounting for anything left out.

Two shapes, both supported

Call describe_catalog once and it returns the exact levelsPath string to use. Paste that into the agent instructions and the value is fixed from then on.

If you get to choose the data model, use a self-referencing table and mark the relationship hierarchical. That unlocks the single-query strategy below and makes arbitrary depth free.

Three traversal strategies, chosen automatically

strategy=auto picks the cheapest correct engine. Force one when you’re testing.

The levels engine batches by level, not by node. All parents at a depth go out in one request using a chunked or filter, so a 500-node tree four levels deep costs about five calls instead of 500.

What stops the hallucinations

One call, no chaining. get_catalog_tree returns the whole subtree. The model never assembles a path across turns.

Errors name the valid values. An unknown relationship returns the real ones, so the model corrects itself from data instead of guessing again:

{
  "error": "unknown_relationship",
  "message": "'product_lines' is not a relationship from 'tst_category'.",
  "providedValue": "product_lines",
  "validValues": [
    { "value": "tst_category_subcategories", "description": "Children in tst_subcategory via tst_parentcategoryid" }
  ],
  "hint": "Retry with one of these relationship schema names."
}

Unexpanded branches are counted, not hidden. Every node carries childCount and hasMoreChildren. When depth runs out, one extra batched query counts the children at the boundary, so the agent says “12 more below Seattle” instead of inferring a leaf.

Truncation is explicit. stats.truncated and stats.truncationReason (depthLimit, nodeBudget, pageLimit, rootLimit) mean an incomplete tree can’t pass for a complete one. Exhausting the per-invocation Dataverse call budget is deliberately not a truncation. It raises a request_budget_exceeded error, because a tree that stopped growing for an internal reason should never be presented as data.

Identity flows one way. Every node returns id, table, and path. Write operations validate GUIDs and reject anything malformed with invalid_id, so a fabricated identifier fails loudly instead of silently targeting nothing.

search_catalog grounds names in records. It resolves user-typed text to real ids with full paths, which is the step that belongs before any traversal or write.

Cycles can’t run away. A visited-set guards traversal, move_catalog_node refuses a parent that sits below the node, and cyclesDetected reports anything skipped.

The outline format is the one to ask for

Set format to tree (default), flat, outline, or all. Indented text with ids costs a fraction of the tokens of nested JSON and gives the model nothing to reassemble:

Contoso Catalog Root (account, bdce4b86-dcb2-f111-aaae-70a8a5b2ff44)
  Contoso East (account, c3ce4b86-dcb2-f111-aaae-70a8a5b2ff44)
    Contoso East - Boston (account, 99005488-dcb2-f111-aaae-6045bd061c5d)
  Contoso West (account, cda82982-dcb2-f111-aaae-6045bd061c5d)
    Contoso West - Seattle (account, c8ce4b86-dcb2-f111-aaae-70a8a5b2ff44) [3 more children not expanded]

The full response carries the definition and the traversal stats alongside the roots:

{
  "definition": { "mode": "selfReference", "hierarchical": true, "levelsPath": "tst_category_parent", "levels": [ ] },
  "stats": {
    "nodeCount": 7, "maxDepthReached": 3, "depthRequested": 5,
    "truncated": false, "truncationReason": "", "cyclesDetected": 0,
    "strategy": "hierarchy", "dataverseRequests": 2, "elapsedMs": 380
  },
  "roots": [ { "id": "...", "label": "Contoso Catalog Root", "childCount": 2, "hasMoreChildren": false, "children": [ ] } ]
}

stats is there so a person debugging a flow can see which engine ran and what it cost, without turning on telemetry.

Nine operations

Two more operations, GET /metadata/tables and GET /metadata/childrelationships, populate the dynamic dropdowns in Power Automate.

Deleting refuses rather than improvises

A destructive operation is the worst place for an agent to fill in a blank. onChildren controls what happens when the node isn’t a leaf:

reparent and cascade need a self-referencing catalog. For heterogeneous levels they return child_handling_unavailable, because the children of a node live in a different table from that node’s parent.

Two more refusals protect against half-finished destruction. A cascade whose subtree exceeds maxNodes raises subtree_too_large, and one that would run past the 80-call budget raises delete_budget_exceeded. Both are checked before any record is deleted.

Limits

Defaults are conservative, and every one is a parameter.

Custom connector code has to finish within two minutes and the script has to stay under 1 MB. Both are comfortable here, since the hierarchy strategy costs two calls regardless of tree size.

Three Dataverse Web API behaviors worth recording

Each of these was confirmed by request rather than by documentation.

A nested $expand on a collection-valued 1:N does work, to at least three nested levels. The documented restriction to many-to-one applies to N:N relationships.

It’s rejected on a key-addressed URL. accounts(<id>)?$expand=children($expand=children(...)) returns “Only many-to-one relationships are supported for nested expansion”, while the same expand against accounts?$filter=accountid eq <id> succeeds. The expand strategy uses the collection form for this reason.

$top and $orderby are forbidden anywhere in a query containing a nested one-to-many $expand, including at the top level. That’s why expand is never the automatic choice: the result size can’t be bounded.

Deploy it

Set host in apiDefinition.swagger.json to your environment, such as contoso.crm.dynamics.com. It ships as the placeholder org.crm.dynamics.com. Set AzureActiveDirectoryResourceId and resourceUri in apiProperties.json to the matching https://<org>.crm.dynamics.com value, and replace [YOUR_CLIENT_ID] with your Entra app registration client id. Leave [YOUR_REDIRECT_URL] alone, because the platform generates and overwrites it on deploy.

pac connector create `
    --api-definition-file .\apiDefinition.swagger.json `
    --api-properties-file .\apiProperties.json `
    --script-file .\script.csx

Then read the generated redirect URL back and register it on the app registration, or OAuth consent fails:

pac connector download --connector-id <id> --outputDirectory ./verify
# properties.connectionParameters.token.oAuthSettings.redirectUrl

That URL encodes both the connector name and the environment, so dev and prod produce two different URLs and both need registering.

Using it from Copilot Studio

Add the connector to the agent as an MCP server and Copilot Studio lists the tools automatically. Add it once. If the same connector is added both as an MCP server and as individual connector actions, the agent sees two overlapping sets of the same capability, and wrong-tool selection is the failure mode this design exists to prevent.

An agent instruction that matches how the tools are built:

The catalog is stored in Dataverse. Use search_catalog to turn any name the user mentions
into a record id before doing anything else. Use get_catalog_tree with format=outline to
read structure. Never invent ids, table names or relationship names. If a tool returns
validValues, retry with one of them. If a node reports hasMoreChildren, say how many
children were not shown rather than listing or guessing them.

In Power Automate the typed operations show up as ordinary actions. GetTree with format=flat returns an array that feeds straight into Apply to each.

Verified behavior

The connector was built and tested against a live Dataverse environment using a four-level self-referencing account hierarchy and a three-level account > contact > task chain: 76 assertions covering both shapes, all three strategies, depth and node-budget truncation, boundary child counts, search path resolution, ancestor breadcrumbs, create, rename, reparent, all three delete modes, cycle rejection on move, MCP protocol handling, and every structured error path. It was then deployed with pac connector create to confirm it compiles in the connector runtime.

Telemetry is off by default. Set APP_INSIGHTS_ENABLED to true and fill in APP_INSIGHTS_KEY in script.csx to turn it on. Events cover MCP tool calls, structured catalog errors, and unhandled exceptions. Telemetry failures are swallowed and never affect the operation.

Resources

• Dataverse Catalog Tree connector source
• Query hierarchical data
• Define and query hierarchically related data
• Write code in a custom connector
• Model Context Protocol specification

Brightspace is a custom connector that covers both audiences from one definition.

The REST half covers the operations people build flows against. The MCP half isn’t limited to those. launch_brightspace calls any Brightspace route, so an agent never stalls on an operation nobody thought to declare in the Swagger.

Three things to collect before you deploy

The host name. Brightspace has no fixed tenant host pattern. It’s whatever hostname your institution runs on, such as school.brightspace.com.

An OAuth 2.0 application registration. Create it in Admin Tools > Manage Extensibility > OAuth 2.0 > Register an app. Pick the Authorization grant workflow, enable Prompt for user consent, and enable refresh tokens. Skipping refresh tokens breaks every connection the moment the access token expires. Brightspace returns a Client ID and Client Secret.

Brightspace’s documentation never mentions PKCE, so don’t assume it’s supported. This connector uses a confidential client with a client secret, matching the documented Authorization Code Grant.

The scopes the registration is allowed to request. More on those below.

The redirect URI is a chicken-and-egg step

Power Platform generates the redirect URL when the connector is created, so you can’t register it in Brightspace up front. Deploy first with the [YOUR_REDIRECT_URL] placeholder in place, then read the generated value back:

pac connector download --connector-id <id> --outputDirectory ./verify
# properties.connectionParameters.token.oAuthSettings.redirectUrl

The result looks like this:

https://global.consent.azure-apim.net/redirect/new-5fbrightspace-5ff5dc2f63c87a6469

That URL encodes both the connector name and the environment, so a connector deployed to dev and prod produces two different redirect URLs. Register both on the Brightspace application.

core:*:* is not a master key

Brightspace scopes are <resource-group>:<resource>:<action>, space-delimited, with * and comma wildcards (users:userdata:create,read,update, no spaces around the commas).

core:*:* reads like an admin scope and isn’t one. It’s the general fallback, and it only covers API actions that have no specific scope assigned yet. Any action that does have a specific scope still needs that scope explicitly. Ship both: the fallback for the unscoped remainder, and the specific scopes for everything else.

The connector’s default set is read-focused, with write access to grades and announcements:

Add the write scopes you need to both apiProperties.json and the Brightspace registration. A token can only request scopes the registration already holds.

Scopes gate which API actions the token may call. They don’t widen what the user can do, because the signed-in user’s role in each org unit still decides that. A 403 almost always means a permissions problem rather than a malformed request.

Versions are pinned to the oldest supported release

Brightspace versions each product component separately, and the version sits in the path: /d2l/api/{component}/{version}/{path}.

Both pin to the oldest version D2L still supports, so the connector works on any current tenant. Later contract versions are supersets, so raise a version only when you need a route added after that point.

REST actions expose version as an advanced path parameter, pre-filled with the pinned default. MCP tools read it from the LP_VERSION and LE_VERSION constants at the top of script.csx, so changing it there shifts every tool at once. To see what your tenant supports, call the Get API Versions action or have the agent call check_brightspace_versions.

30 typed actions, and only three of them run through the script

The typed actions cover users, org structure, courses, enrollments, grades, content, assignments, announcements, discussions, and quizzes:

That’s a sample. The readme lists all 30.

Only three operations run through script.csx: InvokeMCP, which is the MCP server itself, and the two user-lookup actions. Everything else passes straight through to Brightspace, because the Swagger paths are the real Brightspace paths. There’s nothing to transform, and a script hop would only add a failure mode.

The two user-lookup actions exist because GET /users/ changes its response shape depending on which query parameter it receives:

Precedence is orgDefinedId, then userName, then externalEmail, then bookmark, regardless of the order in the URL. One Swagger operation can’t describe three shapes honestly, so the connector declares three operations with accurate response schemas and the script maps the lookup variants back onto the real route.

Five MCP tools cover 57 operations

Add the connector to a Copilot Studio agent as an MCP tool and it exposes five tools:

The capability index embedded in the script describes 57 operations across ten domains. Scanning that index costs a few hundred tokens instead of the tens of thousands that 57 typed tools would add to every agent turn. launch_brightspace isn’t restricted to the index either. It calls any route and warns when the endpoint is unrecognized, so the index serves discovery rather than enforcement.

Here’s how an agent answers “what’s the average grade on the midterm in BIO-101?”:

1. scan_brightspace("find a course by name") returns get_org_unit_descendants
2. launch_brightspace on /lp/1.49/orgstructure/6606/descendants/paged/?ouTypeId=3 finds BIO-101 as org unit 7421
3. scan_brightspace("grade items in a course") returns list_grade_objects
4. launch_brightspace on /le/1.82/7421/grades/ finds the midterm as grade object 19
5. launch_brightspace on /le/1.82/7421/grades/19/values/ returns grades, paged by Next
6. follow_brightspace_page runs until Next is empty

Brightspace has two paging schemes

They’re not interchangeable, and picking the wrong one silently returns one page.

Bookmark paging returns a PagedResultSet:

{
  "PagingInfo": { "Bookmark": "...", "HasMoreItems": true },
  "Items": [ ... ]
}

Pass PagingInfo.Bookmark back as the bookmark query parameter and stop when HasMoreItems is false. List Users, Get My Enrollments, Get Org Unit Enrollments, Get Org Unit Children, and Get Org Unit Descendants use this scheme.

URL paging returns an ObjectListPage:

{
  "Next": "https://...",
  "Objects": [ ... ]
}

Follow the Next URL verbatim, since it already carries the filters you used, and stop when Next is empty. Get Quizzes, the paged classlist, and per-grade-item values use this scheme.

Agents should use follow_brightspace_page for the second scheme. It rejects any URL pointing at a different host, so a returned URL can’t redirect the bearer token somewhere else.

Get Classlist is unbounded and returns every member of a course in one response. For large courses, prefer Get Org Unit Enrollments, which is bookmark-paged.

Conventions worth knowing before the first 403

Deploy it

Replace the host placeholder in apiDefinition.swagger.json with your institution’s hostname:

"host": "[YOUR_INSTITUTION].brightspace.com"   // -> "school.brightspace.com"

This is the only place the host appears. The script derives the API base URL from the incoming request, so MCP tools automatically target the same host. You can’t deploy without replacing it, because square brackets aren’t legal in a hostname and Power Platform rejects the definition:

Error: ApiHubsRequestFailed
Invalid Api definition object. Please specify a valid Swagger 2.0 Url and valid list of ServiceUrls.

That failure is intentional. Deployment stops loudly rather than publishing a connector pointed at nothing.

Then replace [YOUR_CLIENT_ID] in apiProperties.json, and supply the client secret at deploy time or in the portal Security tab. Never commit it.

pac auth create --environment <environment-id>

pac connector create `
    --api-definition-file ./apiDefinition.swagger.json `
    --api-properties-file ./apiProperties.json `
    --script-file ./script.csx

Validate first with ppcv ./Brightspace. Two of its warnings are expected: it reports unbalanced braces on script.csx, because its brace counter doesn’t understand C# verbatim strings, and it flags most operations as absent from scriptOperations, which is the deliberate pass-through design described above.

Deployment was verified on PAC CLI 2.11.2 against a live environment, then downloaded and compared. All 31 operations deployed, x-ms-agentic-protocol survived as mcp-streamable-1.0, script.csx round-tripped byte for byte, and all 24 OAuth scopes and both auth URLs were preserved. The platform rewrote redirectMode from Global to GlobalPerConnector and replaced redirectUrl with the generated per-connector URL, which is exactly the behavior the redirect step above depends on.

Telemetry is off by default. Set APP_INSIGHTS_CONNECTION_STRING near the top of script.csx to turn it on. Telemetry failures are swallowed, so they never break a call.

Resources

• Brightspace connector source
• Brightspace API reference
• Calling conventions, paging, and rate limits
• OAuth 2.0 and scopes
• Scopes index
• API versioning
• Write code in a custom connector

Copilot Studio Agent Runtime closes that gap. The connector opens a conversation with a published agent, reads the entire server-sent event stream, consolidates it, and returns one completed JSON answer. A flow gets a finished reply. A Copilot Studio agent gets a Model Context Protocol (MCP) tool it can call to delegate work to another agent.

A data plane connector, not another control plane one

The other Copilot Studio connectors in the repository manage agents. This one runs them.

The two pair well. List Agents in Copilot Studio Bots returns schemaName and isCLIAgent, which tell you which agent to call here and whether it runs on the GitHub Copilot harness.

The endpoint is undocumented

POST https://{environment-host}/copilotstudio/agenticruntime/3p/dataverse-backed/
     authenticated/bots/{schemaName}/conversations?api-version=1

POST https://{environment-host}/copilotstudio/agenticruntime/3p/dataverse-backed/
     authenticated/bots/{schemaName}/conversations/{conversationId}?api-version=1

This route doesn’t appear on Microsoft Learn and carries no compatibility guarantee. Microsoft’s position today is that the Copilot Studio client library “can only be used with agents created by using the standard harness,” and that “agents using the GitHub Copilot harness aren’t yet officially supported.” The /3p agentic runtime route is how Microsoft’s own experimental Copilot Studio plugin reaches those agents.

Treat it as experimental and keep a fallback.

The agenticruntime prefix and the 3p third-party segment separate this from the classic Direct-to-Engine route at /copilotstudio/dataverse-backed/ with api-version=2022-03-01-preview, which Power Agent Desktop and Power Agent Tray use.

What the agent and app registration need

The agent must be published, because draft agents don’t resolve. It must use Authenticate with Microsoft, which is what the /authenticated/ path segment means. And it must be shared with the signed-in user, or the call returns 403.

The app registration needs the Power Platform API delegated permission CopilotStudio.Copilots.Invoke with admin consent granted, plus a web redirect URI matching the connector’s generated consent URL.

Sign-in is delegated only. The /authenticated/ route rejects app-only client credential tokens and answers with S2SDirectEngineRequiresNoAuthentication. Service-to-service Direct-to-Engine exists, but it’s a private preview and applies only to No Authentication agents. Every connection here is a user sign-in.

Derive the environment host

The connector reads the host from the connection rather than hardcoding it. Take your environment GUID, strip the hyphens, and split after the 30th character:

$environmentId = "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e809"
$id = $environmentId.Replace("-", "").ToLower()
"$($id.Substring(0, 30)).$($id.Substring(30)).environment.api.powerplatform.com"

# 0a1b2c3d4e5f60718293a4b5c6d7e8.09.environment.api.powerplatform.com

Enter the hostname only, with no https:// and no trailing slash. Non-production clouds use api.test., api.preprod., or api.dev. suffixes and work the same way. Sovereign clouds aren’t verified — the agentic runtime may not be deployed there.

The schema name looks like cr1a2_myAgent. Read it from the agent’s Settings page, from the direct connection URL in channel settings, or from List Agents in Copilot Studio Bots.

Four REST actions, three MCP tools

Use Ask Agent for stateless work. Use Start Conversation followed by Send Message when the agent needs to remember earlier turns. Both message operations accept an optional BCP 47 locale such as en-GB.

The MCP tools mirror the same three operations:

* required

emitStartConversationEvent defaults to true. Set it to false to suppress the greeting.

This is what makes agent-to-agent invocation work. A Copilot Studio agent can call a GitHub Copilot harness agent as a tool, which no supported channel currently offers.

Consolidating the stream takes two rules

The runtime replies with text/event-stream. Power Platform can’t surface a stream to a flow, so the connector reads the whole thing and consolidates it.

Naive concatenation breaks, because the runtime streams in two shapes depending on the agent and client:

The connector detects the shape by testing whether each chunk begins with the previous one. Guessing wrong is visible in the output either way: treating cumulative text as deltas repeats the answer several times over, and treating deltas as cumulative truncates it to the last fragment.

The response keeps both the consolidated text and the raw activities:

{
  "conversationId": "abc123",
  "text": "Paris is the capital of France.",
  "isComplete": true,
  "activityCount": 4,
  "attachments": [],
  "suggestedActions": [ { "type": "imBack", "title": "Tell me more", "value": "more" } ],
  "citations": [ { "@type": "Claim", "position": 1, "appearance": { "name": "France", "url": "https://example.com" } } ],
  "activities": [ "..." ]
}

Read text in almost every flow. Check isComplete when correctness matters — false means the runtime never signaled turn completion, so text is partial. activityCount covers this turn only, not the whole conversation. Ask Agent also returns greetingActivities separately, so the agent’s opening line never pollutes text.

Send a raw activity to trigger a topic

Send Message exposes a Raw Activity field for anything that isn’t a plain user message. An event or invoke activity can trigger a topic directly:

{
  "activity": {
    "type": "event",
    "name": "StartOrderLookup",
    "value": { "orderId": "SO-4417" }
  }
}

Message is ignored when Raw Activity is present. The connector always overwrites the conversation property with the conversation in the request path, so a caller can’t post into a conversation it doesn’t own.

Errors name the thing to check

The runtime returns bare status codes for common misconfigurations, so the connector translates each one:

{
  "status": 403,
  "message": "Forbidden. Share the agent with the signed-in user, and confirm admin consent was granted for CopilotStudio.Copilots.Invoke. This endpoint rejects app-only (service principal) tokens: the connection must be a delegated user sign-in.",
  "details": "<raw response body from the runtime>"
}

MCP callers get the same payload as the tool result with isError: true, so the calling agent reads the explanation instead of seeing an opaque failure.

When a call fails, confirm each layer in order. It isolates the problem faster than reading the error alone:

1. Host — does it match the {30}.{2} split of your environment GUID? A wrong host gives 404, not a connection error.
2. Schema name — copy it from List Agents exactly. It’s case-sensitive.
3. Published — republish if in doubt. A draft-only agent gives 404.
4. Sharing — confirm the signed-in user is on the agent’s share list.
5. Permission — check CopilotStudio.Copilots.Invoke has admin consent.

A 401 is almost always the app registration rather than the agent.

Know the limits before you build on it

Turn length is the hard one. Power Platform cuts a connector request off at roughly 120 seconds. Agentic loop turns routinely run longer, and this endpoint has no polling or resume route, so a long turn is simply lost. Keep prompts tightly scoped and don’t build deep research tasks on it.

The rest:

• No streaming to the caller. The answer arrives all at once when the turn completes. Progressive rendering isn’t possible through a custom connector.
• Delegated identity only. Every call runs as the signed-in user. There’s no unattended option.
• Unversioned in practice. api-version=1 is pinned because it’s what the route accepts today.
• Cost. Agents on the GitHub Copilot harness bill 100–500+ Copilot Credits per task regardless of Microsoft 365 Copilot licensing. Calling one in a loop from a flow gets expensive fast. Check the harness with List Agents before wiring an agent into automation.

Deploy the connector

pac auth create --environment <environment-id>

pac connector create `
    --api-definition-file apiDefinition.swagger.json `
    --api-properties-file apiProperties.json `
    --script-file script.csx

Replace [YOUR_CLIENT_ID] in apiProperties.json with your app registration’s client ID and set the client secret in the portal Security tab. Then read back the generated redirect URL and register it:

pac connector download --connector-id <id> --outputDirectory ./verify
# properties.connectionParameters.token.oAuthSettings.redirectUrl

az ad app update --id <appId> --web-redirect-uris `
    "https://global.consent.azure-apim.net/redirect" "<per-connector-url>"

Each environment generates a different redirect URL. Consent fails if only the generic one is registered.

Validate before deploying:

npx ppcv "./Copilot Studio Agent Runtime"

Finally, create a connection and supply the environment host derived above.

Three ways to use it

Ask an agent from a flow

Use Ask Agent when each call is independent.

Read text from the output. You don’t need to touch activities.

Hold a multi-turn conversation

When later turns depend on earlier ones, keep the conversation open:

1. Start Conversation, then store conversationId in a variable.
2. Send Message with that conversationId, then read text.
3. Repeat step 2 for each follow-up. The agent retains context across turns.

Don’t call Ask Agent in a loop for this. Each call opens a fresh conversation and the agent forgets everything.

Let one agent call another

This is the scenario the MCP endpoint exists for, and the only way to reach a GitHub Copilot harness agent as a tool:

1. In Copilot Studio, open the calling agent and go to Tools > Add a tool > Model Context Protocol.
2. Select this connector and create or pick a connection.
3. Add ask_agent for one-shot delegation.

4. In the calling agent’s instructions, say when to delegate and which schemaName to pass. The model won’t know the schema name otherwise:

   When the user asks a contract question, call ask_agent with schemaName set to cr1a2_contractReviewer and the user’s question as text.

Add start_conversation and send_message only when the calling agent genuinely needs a multi-turn side conversation. For most delegation, ask_agent alone produces better behavior.

Resources

• Copilot Studio Agent Runtime source
• Copilot Studio Bots connector
• Copilot Studio client library
• Write code in a custom connector
• Copilot Studio Bots v1.2 post

The licensing APIs Microsoft shipped in July 2026 answer both questions from one host. Power Platform Capacity Intelligence wraps them in 12 typed Power Automate actions and the same 12 tools over Model Context Protocol, so a flow or a Copilot Studio agent can ask directly.

Every operation is read-only.

Reading and writing stay in separate connectors

Allocation writes live in the Power Platform Admin connector, which shipped them in v1.4.

flowchart LR
    A[Power Platform Capacity Intelligence<br/>12 read-only tools] -->|reads| C[(licensing APIs<br/>api.powerplatform.com)]
    B[Power Platform Admin<br/>allocation writes] -->|reads and writes| C

An agent holding only this connector can report that production has burned 94% of its AI capacity. It can’t change the allocation, enable Deny, or move capacity between environments. That makes it safe to hand to a wider audience than the admin connector — finance, a platform steering group, anyone who needs the number without needing the controls.

What the 12 tools cover

Start with List Environment Entitlements. Entitlement IDs aren’t published anywhere convenient, and this tool returns the ones your environment actually has.

Each tool is also a typed Power Automate action with full request and response schemas, so it shows up in the designer with IntelliSense and output tokens. Every environmentId field renders as a picker of display names, backed by an internal dropdown operation — no GUIDs to paste.

The definition holds 15 operations: 12 typed actions, 2 internal dropdown sources, and the MCP endpoint.

Where the live API diverges from the reference

Each contract was checked against a live tenant before the connector was written. Five published details didn’t hold, and each one changed the implementation.

Allocation availability rejects an unfiltered call. The reference marks $filter optional. The service returns 400 Invalid filter options without it. So entitlementId is required and the connector writes the filter:

var filter = $"entitlementId eq '{EscapeODataLiteral(entitlementId)}'";
if (!string.IsNullOrWhiteSpace(environmentId))
    filter = $"environmentId eq '{EscapeODataLiteral(environmentId.Trim())}' and {filter}";

Paged responses use a different token name. The reference documents @odata.nextLink and @odata.count. What arrives is value and a lowercase continuationtoken. The connector accepts all three spellings and returns whichever it finds.

Dates are typed as bare strings. ISO yyyy-MM-dd works. The connector validates and normalizes before sending, so an inverted or unparseable range fails with a clear message instead of an opaque service error. Omit both dates and you get month-to-date, which matches how the service reports consumption.

EntitlementUnit isn’t a closed set. Four values are documented. The service also returns others, including Messages. The connector passes unit through as a display string and never switches on it.

Two endpoints return 403 with an empty body. Get Environment Resources and Get Tenant Resources were denied for a tenant administrator whose sibling entitlement reads succeeded on the same token. No error detail came back at all, so the connector supplies the diagnosis:

if (status == HttpStatusCode.Forbidden)
{
    return $"Access denied reading {description} (403). " +
           (string.IsNullOrWhiteSpace(body)
               ? "The service returned no detail. Grant Licensing.Allocations.Read to the app registration and sign in as a Power Platform or Global administrator. " +
                 "Some per-resource consumption endpoints stay denied even for tenant administrators; if a sibling entitlement read succeeds, the permission is present and this endpoint is restricted separately."
               : Truncate(body));
}

That last one costs the most time during setup. If Get Entitlement works and Get Environment Resources doesn’t, granting the permission again won’t help. You’ve hit a separate gate on per-resource consumption.

Making the numbers mean what they say

A capacity figure without its context invites the wrong conclusion. Three response fields carry that context.

consumptionType tells you what consumed covers

consumed isn’t always a running total. MonthToDate resets on the first of the month, so a low figure on the third says nothing about usage. Snapshot is a point-in-time reading. Every tool that returns consumed returns consumptionType next to it.

percentUsed is computed by the connector as consumed / entitled × 100, rounded to two places, and only when entitled is greater than zero. It measures the past. The connector doesn’t extrapolate, and the response says so.

An empty result isn’t always a zero

Three tools distinguish absence from measurement. The Finance and Operations summary is the clearest case — a tenant that has never produced a report returns zeroed counters and a default timestamp rather than a 204:

var neverRefreshed = IsDefaultTimestamp(doc["lastReportRefreshTime"]);

When that’s true, hasData comes back false with an explanation: “This tenant has no Finance and Operations licensing report. The zero counts are the absence of a report, not a measured result.”

Check hasData before charting it. A chart of zeros looks like a measurement.

capacity_list_resource_thresholds reports consumption as uncapped rather than returning a bare empty list, and capacity_get_license_trends explains that capacity-model entitlements have no assigned licenses to trend.

Posture degrades in parts

capacity_get_entitlement_posture reads three sources — entitlement capacity, allocation availability, and thresholds. Those sources don’t share authorization behavior, so one failure shouldn’t blank the other two:

try { entitlement = await HandleGetEntitlement(args).ConfigureAwait(false); }
catch (Exception ex) { problems.Add("entitlement: " + ex.Message); }

try { availability = await HandleGetAllocationAvailability(args).ConfigureAwait(false); }
catch (Exception ex) { problems.Add("availability: " + ex.Message); }

try { thresholds = await HandleListResourceThresholds(args).ConfigureAwait(false); }
catch (Exception ex) { problems.Add("thresholds: " + ex.Message); }

The response carries problems and a complete flag. A partial posture is a normal result, not a failure — check complete before treating it as whole.

Paging is handed back to the caller

Paged tools return one page and the service’s continuation token. Walking the full collection inside the script would risk the two-minute custom code limit on a large tenant, and a timeout is harder to diagnose than an explicit next-page token.

Loop while hasMore is true, passing continuationToken back each time:

1. Get Tenant Resources          (entitlementId: MCSMessages)
2. Do Until: hasMore is false
   3. Append resources[] to an array variable
   4. Get Tenant Resources       (continuationToken from the previous response)

pageSize defaults to 100 and clamps at 1,000. Raising it makes fewer calls, which matters when a sweep starts drawing 429 responses.

Rows arrive flattened. The service nests them as value[].resources[] and value[].users[]; the connector unwraps that level, so an apply-to-each runs directly over resources or users.

User attribution needs handling rules

The three attribution tools return identifiable people alongside consumption figures. Their responses carry a privacyNote saying so.

Telemetry is off by default, and when enabled it records only the tool name and entitlement ID through ToolCall and ToolCallError events. Consumption figures and user identifiers never reach Application Insights. Sending them would move personal data outside the boundary the caller expects, and a telemetry pipeline is the wrong place to keep it. Audit inside your own tenant against the connector’s response instead.

Prefer resource-level attribution when it answers the question. Reach for user-level data when it doesn’t, then retain the output according to your privacy obligations.

Setting it up

Grant the permission

Create a Microsoft Entra app registration with the delegated Power Platform API permission Licensing.Allocations.Read. The Power Platform API resource is 8578e004-a5c6-46e7-913e-12f58912df43.

az ad app permission add --id <appId> `
  --api 8578e004-a5c6-46e7-913e-12f58912df43 `
  --api-permissions 73cf5c38-5257-4f28-8bbb-f78acf3290a4=Scope

az ad app permission admin-consent --id <appId>

The permission reference doesn’t publish scope IDs. That value was read from the service — confirm it in your own tenant rather than trusting a pasted GUID:

az ad sp show --id 8578e004-a5c6-46e7-913e-12f58912df43 `
  --query "oauth2PermissionScopes[?starts_with(value,'Licensing')].{scope:value,id:id}" `
  --output table

The signed-in user needs Power Platform Administrator or Global Administrator. These reads are tenant-scoped.

Deploy all three files

apiProperties.json declares script operations, so the service rejects a deployment without a script to route them to:

ppcv ".\Power Platform Capacity Intelligence"

pac connector create `
  --api-definition-file ".\Power Platform Capacity Intelligence\apiDefinition.swagger.json" `
  --api-properties-file ".\Power Platform Capacity Intelligence\apiProperties.json" `
  --script-file ".\Power Platform Capacity Intelligence\script.csx"

Search for Power Platform Capacity in the connector list, not the folder name. pac connector create caps titles at 30 characters and “Power Platform Capacity Intelligence” is 35. ppcv doesn’t check that limit, so the files validate cleanly and the deployment still fails.

Replace [INSERT_YOUR_CLIENT_ID] in apiProperties.json with your application ID first. The placeholder deploys verbatim and the connector won’t authenticate until you fix it.

Register the generated redirect URL

Deployment rewrites redirectMode to GlobalPerConnector and replaces redirectUrl with a generated value. That value has to be on the app registration or OAuth consent fails. This step is easy to miss and the failure it causes looks like a permission problem.

pac connector download --connector-id <CONNECTOR_ID> --outputDirectory ".\verify"
# read properties.connectionParameters.token.oAuthSettings.redirectUrl

az ad app update --id <appId> --web-redirect-uris `
  "https://global.consent.azure-apim.net/redirect" `
  "<generated-url>"

The trailing segment identifies the environment, so a second environment produces a second URL and both need registering. Add to the existing list rather than replacing it if the app registration backs other connectors.

Putting it to work

A monthly posture report starts with List Environment Entitlements, filters to entitlements whose status isn’t WithinCapacity, and calls Get Entitlement Posture for each survivor:

1. Trigger: Scheduled (monthly, first of the month)
2. List Environment Entitlements  (production environment)
3. Filter array: status is not equal to 'WithinCapacity'
4. For each remaining entitlement:
   5. Get Entitlement Posture     (entitlementId from the filtered item)
   6. Append to an HTML table: entitlementId, percentUsed, status, consumed, entitled
7. Mail the table to the platform owners

Tracing Copilot Studio consumption takes three calls — the total, the resources behind it, and the headroom left:

1. Get Entitlement                (MCSMessages)
2. Get Tenant Resources           (MCSMessages, paging until hasMore is false)
3. Sort by consumed descending, take the top 10
4. Get Allocation Availability    (MCSMessages)

An agent answers the same questions conversationally:

How much Copilot Studio message capacity has the tenant used this month?
Which agents consumed the most MCSMessages capacity in August?
Which entitlements are in overage?
How much AI capacity is still unallocated?
What entitlements does my production environment have?
Are there consumption thresholds configured for MCSMessages?
Who consumed the most Copilot Studio capacity last month?

When the answer calls for a change, switch to Power Platform Admin. This connector reports the position; that one moves it.

Resources

• Source code
• July 2026 programmability additions
• Get Entitlement
• Get Many Environment Entitlements
• Get Environment Resources
• Get Tenant Users
• Get Allocations Availability V2
• Get All Resource Thresholds
• Get Fin Ops License Summary V2
• Programmability permission reference

Copilot Studio Bots v1.2 downloads that package for the Microsoft 365 channel. Save it before a release, archive it on a schedule, or compare two packages when a channel change behaves differently from the agent you tested.

The update adds the Download Agent Channel Manifest action for Power Automate and the download_agent_channel_manifest tool for Model Context Protocol (MCP) callers. It also hardens both ZIP download paths and fixes two problems found while testing the connector against the live Power Platform API.

What’s new in v1.2

The new REST action and MCP tool use the same operation:

GET https://api.powerplatform.com/copilotstudio/
    environments/{environmentId}/agents/{botId}/
    channels/{channelName}/download
    ?includeAgentSchema={true|false}
    &api-version=2024-10-01

This route differs from the other connector operations. Evaluations, quarantine, consent bypass, reassignment, deletion, and identity migration use bots/{botId}. Channel manifest export uses agents/{botId}.

Microsoft currently documents one channel value: M365. The connector defaults to it and rejects other values before making the request. When includeAgentSchema isn’t supplied, the connector leaves the query parameter out instead of changing an omitted value to false.

Keep the package that reaches Microsoft 365

The endpoint returns the channel manifest package as a ZIP. That makes it useful in agent application lifecycle management (ALM) workflows where the published package matters as much as the editable agent:

• Export the package before and after a release, then compare the contents
• Save each production package to a versioned SharePoint document library
• Capture a known-good package before changing channels, authentication, or actions
• Attach the package to a release record for review or incident analysis
• Include the agent schema when a downstream check needs it

A scheduled flow can inventory agents, call Download Agent Channel Manifest for each selected agent, and write the output directly to SharePoint or OneDrive. Keep the binary output out of string variables so the ZIP stays intact.

For an interactive MCP workflow, ask the agent to find the target first:

User: List the agents in the production environment.

Agent:
  1. list_agents { environmentId: "<production-environment-id>" }
  2. Presents names, IDs, owners, harnesses, and publish states

User: Download the M365 channel manifest for Contoso Support.

Agent:
  3. download_agent_channel_manifest {
       environmentId: "<production-environment-id>",
       botId: "<contoso-support-agent-id>",
       channelName: "M365",
       includeAgentSchema: true
     }

Discovery stays separate from the download, so the user can confirm the named agent before retrieving its package.

Binary downloads now share one path

The connector already downloaded evaluation snapshots. v1.2 moves snapshots and channel manifests onto one binary handler, with the same behavior for both:

• ZIPs up to 4 MB return to an MCP caller as a base64 resource
• Larger ZIPs return metadata and direct the caller to the REST action
• Power Automate receives the binary response without the MCP inline limit
• The file name comes from Content-Disposition, with a generated fallback

The 4 MB ceiling keeps large base64 payloads out of an agent conversation. Use the REST action in a flow when a package exceeds it, and send the action output straight to storage.

File names also get stricter handling. A service response header eventually becomes part of an MCP resource URI, so the connector no longer trusts that value as-is. It:

1. Removes directory components
2. Replaces characters that can break a URI
3. Forces a .zip extension
4. Caps the name at 120 characters
5. Falls back to agent-channel-manifest-M365.zip when the header is missing or malformed

The same checks now protect evaluation snapshot names.

Read a 403 before checking the IDs

Microsoft’s REST reference documents the request and 200 response but doesn’t list error responses for this operation. Live testing exposed an important order of operations: authorization runs before identifier validation.

Without CopilotStudio.MakerOperations.Read, the service returned 403 Forbidden for both an invalid channel and a nonexistent agent. A 403 therefore doesn’t prove the agent ID or channel is wrong.

Read innererror.code and innererror.message first. An InsufficientDelegatedPermissions response names the accepted delegated permissions. Grant CopilotStudio.MakerOperations.Read, consent again, and retry before troubleshooting the identifiers.

This permission is also used for reading evaluation test sets, test runs, and snapshots. Starting an evaluation needs CopilotStudio.MakerOperations.ReadWrite, while the administrative operations use their own permission family.

Two live-API fixes ship with the update

The source on main reports MCP server version 1.2.1 because testing found two defects after the channel export was added.

Environment names appear in the picker again

The environment management API returns displayName, type, state, and url at the top level. The connector expected a nested properties object, so the environment picker showed raw GUIDs when that object was absent.

The parser now checks the flat response first and keeps a nested fallback for older response shapes.

Agent inventory retries one transient 400

The undocumented resourcequery endpoint can intermittently return:

400 Bad Request
"KQLOM format is wrong or it cannot be null"

Testing reproduced the response with a byte-for-byte identical payload that had succeeded moments earlier. The connector now retries that specific error up to three times with a short backoff. It also retries 429 and 5xx responses, while unrelated 400 responses still fail immediately.

This matters beyond inventory. List Agents, the agent picker, find_containment_candidates, and contain_agents all depend on the same query.

Update the connector

Replace REPLACE_WITH_CLIENT_ID in apiProperties.json, then validate and update the existing connector:

ppcv "./Copilot Studio Bots"

pac connector update `
    --connector-id 00000000-0000-0000-0000-000000000000 `
    --api-definition-file apiDefinition.swagger.json `
    --api-properties-file apiProperties.json `
    --script-file script.csx

Keep --script-file. The MCP tool, binary handling, dropdown fix, and inventory retry all run through script.csx.

Existing flows keep their actions. The new channel manifest action appears with the evaluation, inventory, containment, identity migration, and administrative actions after the update.

Resources

• Copilot Studio Bots v1.2 source
• v1.2 commit
• Download Agent Channel Manifest
• Original Copilot Studio Bots post
• Copilot Studio Bots v1.1

Power Platform Admin v1.4 moves onto it. Five new tools cover allocations, availability, and reserved entitlements. The tenant pool tools from v1.1 were rewritten to use the same surface, so the tenant-routed host they reached is gone. Nothing in the connector calls an undocumented licensing route anymore.

The v1.2 post covers agent inventory, v1.3 covers resource thresholds, and the original post covers the first 12 tools.

What’s new in 1.4

One host now

v1.1 built a host from the tid claim of the access token — the tenant GUID lowercased, stripped of dashes, split into the first 30 hex characters and the last 2, assembled as {prefix}.{suffix}.tenant.api.powerplatform.com. It worked, and it was never in the published REST reference.

flowchart LR
    A[v1.3] --> B["api.powerplatform.com"]
    A --> C["first30hex.last2hex.tenant.api.powerplatform.com<br/>licensing/allocations"]
    D[v1.4] --> E["api.powerplatform.com<br/>including licensing/allocationsByEnvironment"]

The identifiers survived the move but the wire shape didn’t. MCSMessages and MCSSessions were entitlement IDs on the retired route. On the documented API they’re ExternalCurrencyType values inside a currencyAllocations array:

// MCSMessages and MCSSessions are ExternalCurrencyType values on the documented
// allocation API. The retired tenant-routed endpoint modelled them as entitlement
// IDs, so the wire shape differs even though the identifiers are spelled the same.
private static readonly string[] TENANT_POOL_CURRENCIES = { "MCSMessages", "MCSSessions" };

Tenant pool draw is now an enforcement rule on those two currencies rather than a document of its own. admin_get_tenant_pool_draw and admin_set_tenant_pool_draw keep their names and arguments, so an agent or flow built on v1.1 keeps working.

Every documented currency, four enforcement rules

The allocation tools cover the full ExternalCurrencyType list — AI, Copilot Studio messages and sessions, Power Pages authenticated and anonymous, hosted and unattended RPA, Power Automate per-process, Process Mining storage, and the rest — with Alert, PayGo, TenantPool, and Deny.

Throttle is missing from that list on purpose. It appears on the allocationsV2 surface but not on the by-environment API, so the connector rejects it locally rather than sending a value the endpoint doesn’t document:

throw new ArgumentException(
    $"ruleType '{trimmed}' is not a documented enforcement rule for the by-environment allocation " +
    "API. Expected one of: " + string.Join(", ", ENFORCEMENT_RULE_TYPES) + ".");

Currency spelling is validated the same way, against the documented list. Unknown values coming back from the service pass through untouched — Microsoft can add a member without a version bump, and a connector that filters reads would hide capacity that exists.

Deny deserves care. Enabling it halts consumption once the allocation is exhausted, which can break running apps and agents mid-request.

Writes read back and report whether it took

The PATCH accepts a currencyAllocations array, and the published contract doesn’t say whether the service merges the collection or replaces it. Sending the whole array makes both behaviors produce the same result, so admin_update_environment_allocation reads the current document, changes only the currency you named, and sends everything back.

Then it re-reads and compares:

var applied = await PatchEnvironmentAllocation(envId, document).ConfigureAwait(false);
var after = await FetchEnvironmentAllocation(envId).ConfigureAwait(false);

var verified = VerifyCurrencyMatches(after, currencyType, target);

The response carries verified plus a changes array of field, from, and to entries, so a flow logs what moved instead of what was requested. A false on verified means the read-back didn’t match:

Updated AI on environment {id}, but the read-back did not match the requested
values. Another administrator may have written concurrently — the service exposes
no ETag. Re-read the allocation before making further changes.

There’s still no ETag. Read-modify-write with verification narrows the window and tells you when you lost the race; it doesn’t close it. Don’t fan this out across 40 environments while someone is in PPAC.

A call that supplies neither allocated nor enforcementRules is rejected rather than rewriting the document with its own current values.

Confirmation the agent can’t reason its way past

“Confirm with the user before executing” in a tool description is a suggestion. An orchestrator resolving an ambiguous instruction can decide it already has consent — and Deny on a production currency is not a decision to leave to inference.

v1.4 puts the check in the tool router:

private static readonly HashSet<string> CONFIRMATION_REQUIRED_TOOLS =
    new HashSet<string>(StringComparer.OrdinalIgnoreCase)
    {
        "admin_update_setting",
        "admin_update_copilot_governance",
        "admin_set_tenant_pool_draw",
        "admin_upsert_resource_threshold",
        "admin_update_environment_allocation",
        "admin_install_package"
    };

confirm is required in each tool’s input schema, and the router refuses the call regardless:

throw new ArgumentException(
    $"{toolName} changes tenant or environment configuration and cannot be run from an " +
    "implied instruction. Show the caller what will change, then set confirm to true.");

A missing, false, or non-boolean confirm all land in the same place. The string "true" is accepted because some agents stringify booleans, and nothing weaker than an explicit affirmative gets through.

The typed Power Automate operations are deliberately not gated. A maker who drags Update Environment Allocation into a designer has already made the decision, and adding a required body property would break every flow built on the previous version.

In a flow

Five new actions, same environment picker as the rest of the connector — display names at design time, no GUIDs to paste.

List Environment Allocations takes no inputs and returns every environment, which makes the tenant-wide reports practical: which environments have Deny enabled on any currency, which draw from the tenant pool without a resource threshold, which have AI capacity sitting allocated and unused.

Get Allocation Availability and Get Reserved Entitlements each accept an OData $filter, but Microsoft doesn’t publish the filterable fields. Call them unfiltered and narrow the result in the flow. Reserved quantities don’t include enforcement rules — read the environment allocation for those.

Prompts to try

Show me capacity allocations across every environment
What AI capacity is allocated to my production environment?
How much AI capacity is still unallocated in the tenant?
Allocate 250 AI capacity to my sandbox and deny overage
Which environments have Deny enabled on any currency?
Which environments draw from the tenant pool but have no resource threshold?

That last one spans two APIs. With generative orchestration enabled, the agent reads allocations, reads thresholds, and joins them on environment ID without a tool built for the question.

Permissions

No new scope. The allocation routes sit under licensing, so the Licensing.Allocations.Read and Licensing.Allocations.ReadWrite scopes already on the app registration cover them, plus Power Platform Administrator or Global Administrator on the caller. The endpoint reference advertises only .default, so verify with a read before relying on a write.

Updating an existing install

cd "Power Platform Admin"
pac connector update `
  --connector-id <your-connector-id> `
  --api-definition-file apiDefinition.swagger.json `
  --api-properties-file apiProperties.json `
  --script-file script.csx

Set the clientId in apiProperties.json to your app registration first. If the update fails with “An unexpected error occurred,” push the definition and script without --api-properties-file, then set OAuth on the connector’s Security tab in the portal.

The connection doesn’t need to be recreated. Agents calling the six gated tools do need confirm: true added — that’s the one breaking change in this release.

Resources

• Source code
• List Allocations By Environment
• Get Allocations By Environment
• Update Allocations By Environment
• Get Allocations Availability V2
• Get Many Entitlements Reserved V2
• Manage Copilot credit allocations programmatically
• Permissions reference

It’s based on Microsoft’s MCP Streamable HTTP connector template, with the OAuth configuration swapped out.

Read this before you deploy it

oauth2pkcewithdcr is a hidden Power Platform identity provider, and its current refresh template includes client_secret={ClientSecret} even when the connector defines no clientSecret. The initial authorization works. Refresh is the open question, and it depends on how your authorization server handles an unexpected empty client_secret.

Treat this template as experimental. The refresh validation section below is the part that decides whether it’s usable for you.

Two files, no script

There’s no script.csx. Power Platform forwards MCP traffic straight to the remote server, so nothing needs to sit in the middle.

You’ll need a remote MCP server using Streamable HTTP, an authorization server supporting authorization code with PKCE S256, a static public-client registration with no secret, and its client ID, authorization endpoint, token endpoint, refresh endpoint, and scopes. Also PAC CLI and permission to create connectors in a test environment. If refresh is part of your test, the authorization server has to issue refresh tokens.

Configure the API definition

Edit apiDefinition.swagger.json:

1. Replace your-mcp-server.example.com with the MCP hostname, without https:// or a path.
2. Replace /mcp in basePath with the MCP endpoint path.
3. Replace the authorization and token endpoint URLs.
4. Replace mcp.tools with the scope your server requires.

For multiple scopes, add each one to both securityDefinitions.oauth2_auth.scopes and security[0].oauth2_auth.

The single operation carries the marker that tells Power Platform this is MCP traffic rather than a REST call:

"paths": {
  "/": {
    "post": {
      "operationId": "InvokeMCP",
      "summary": "Invoke MCP with public-client PKCE",
      "x-ms-agentic-protocol": "mcp-streamable-1.0",
      "responses": {
        "200": { "description": "MCP response" }
      }
    }
  }
}

Keep x-ms-agentic-protocol and keep the operation at path / beneath basePath. The MCP path lives in basePath, not in the operation path.

Configure the connector properties

The OAuth settings in apiProperties.json are where the public client is declared:

"oAuthSettings": {
  "identityProvider": "oauth2pkcewithdcr",
  "clientId": "[YOUR_CLIENT_ID]",
  "scopes": ["mcp.tools"],
  "redirectMode": "Global",
  "redirectUrl": "[YOUR_REDIRECT_URL]",
  "properties": {
    "IsFirstParty": "False",
    "IsOnbehalfofLoginSupported": false
  },
  "customParameters": {
    "serverUrl": { "value": "https://your-mcp-server.example.com" },
    "authorizationUrl": { "value": "https://your-auth-server.example.com/oauth/authorize" },
    "tokenUrl": { "value": "https://your-auth-server.example.com/oauth/token" },
    "refreshUrl": { "value": "https://your-auth-server.example.com/oauth/token" }
  }
}

Replace the client ID, the scope, and the four URLs. serverUrl is the MCP server origin without the endpoint path — the path stays in the swagger basePath.

Leave [YOUR_REDIRECT_URL] alone. Power Platform overwrites it with the generated per-connector callback URL at deployment.

Never add a clientSecret property. Adding one turns this into a confidential client and defeats the whole exercise. The scope list here also has to match the scopes in apiDefinition.swagger.json.

Create the connector

Confirm the target environment first:

pac auth list
pac connector list --environment POWER_PLATFORM_ENVIRONMENT_ID_OR_URL

Then create it:

pac connector create `
    --environment POWER_PLATFORM_ENVIRONMENT_ID_OR_URL `
    --api-definition-file .\apiDefinition.swagger.json `
    --api-properties-file .\apiProperties.json

Don’t pass --script-file. Record the connector ID that PAC returns — the next step needs it. Power Platform validates both files during creation, so resolve any errors PAC reports before continuing.

Register the generated callback URL

Power Platform generates the redirect URL, so you have to read it back out of the deployed connector:

pac connector download `
    --environment POWER_PLATFORM_ENVIRONMENT_ID_OR_URL `
    --connector-id CONNECTOR_ID `
    --outputDirectory .\deployed-connector

Open deployed-connector\apiProperties.json and find:

properties.connectionParameters.token.oAuthSettings.redirectUrl

Register that exact URL with your authorization server’s public-client registration. It uses HTTPS and the global.consent.azure-apim.net host. The callback is specific to this connector in this environment, so a connector deployed to a second environment needs its own registration.

Create and test the connection

1. Open Power Automate and select the environment you deployed to.
2. Open Custom connectors and edit MCP Public Client PKCE.
3. Open Test and select New connection.
4. If a client-secret field appears, leave it blank.
5. Complete authorization and consent, then refresh the connection list.

Then wire it into an agent:

1. Open Copilot Studio and select the same environment.
2. Open a non-production test agent, go to Tools, and select Add a tool.
3. Select MCP Public Client PKCE and its connection, then add it to the agent.
4. Confirm Copilot Studio discovers the remote tools, and invoke a safe read-only one.

Validate refresh behavior

A successful first tool call proves that authorization code with PKCE worked and that MCP connectivity is fine. It says nothing about refresh, which is where the client_secret={ClientSecret} template matters.

To test it:

1. Keep the same connection and agent.
2. Wait for the access token to expire, plus a clock-skew buffer.
3. Don’t repair or recreate the connection.
4. Invoke the same read-only tool again.
5. Check sanitized authorization-server logs for the refresh request.

If the normal access-token lifetime is too long to wait out, use a non-production client or policy with a shorter lifetime. A long-lived access token postpones the question rather than answering it.

Record only these observations:

Refresh request observed: yes/no
grant_type: refresh_token/other
client_id present: yes/no
client_secret presence: absent/empty/populated
HTTP Basic client authentication present: true/false
Refresh outcome: succeeded/rejected
OAuth error code, if any:
Post-refresh MCP tool outcome: succeeded/failed

Never record tokens, codes, verifiers, secrets, cookies, or authorization headers.

Interpret the result

The result you want:

client_secret presence: absent
HTTP Basic client authentication present: false
Refresh outcome: succeeded
Post-refresh MCP tool outcome: succeeded

Nothing in the OAuth specifications requires an authorization server to ignore an unexpected empty client_secret. Confirm empty-value behavior with the authorization-server owner instead of assuming that empty and absent mean the same thing.

Update the connector

After changing either file:

pac connector update `
    --environment POWER_PLATFORM_ENVIRONMENT_ID_OR_URL `
    --connector-id CONNECTOR_ID `
    --api-definition-file .\apiDefinition.swagger.json `
    --api-properties-file .\apiProperties.json

Delete and recreate existing connections after any OAuth configuration change. Cached connections hold the old settings and will fail in ways that look like server problems.

Resources

• MCP Public Client PKCE template
• Microsoft MCP Streamable HTTP connector template
• Update custom connector OAuth identity providers with PAC CLI
• Connect a Copilot Studio agent to an existing MCP server
• Create and test a custom connector
• RFC 6749: The OAuth 2.0 authorization framework
• RFC 7636: Proof key for code exchange by OAuth public clients
• RFC 8252: OAuth 2.0 for native apps

Two projects solve this together:

• Azure Async Operation Polling is the reusable script pattern. Copy it into a connector for ARM, Microsoft Fabric, Microsoft Foundry, Power BI, or another service with a long-running operation API.
• Azure Async Operations is a complete ARM custom connector built from that pattern. It creates, updates, deletes, and invokes actions on Azure resources.

The connector doesn’t wait for Azure to finish. A start action makes one request and returns an operation handle. A second action checks the status once. A Power Automate Do Until loop controls the delay and repeats the check.

Move the waiting into the flow

The custom code follows one rule: each connector action makes no more than one outbound request.

flowchart LR
    A[Power Automate<br/>start action] --> B[Azure API]
    B --> C[Operation handle]
    C --> D[Do Until]
    D --> E[Delay]
    E --> F[Get Operation Status]
    F --> B
    F -->|Running| D
    F -->|Succeeded, Failed, or Canceled| G[Continue flow]

Both actions return the same envelope:

{
  "status": "Running",
  "isComplete": false,
  "retryAfterSeconds": 15,
  "operationHandle": "eyJ1IjoiaHR0cHM6Ly9tYW5hZ2VtZW50...",
  "result": null,
  "error": null
}

The script normalizes service-specific states into four values:

• Running
• Succeeded
• Failed
• Canceled

An unfamiliar status stays Running. Treating an unknown value as success could let the flow continue while Azure is still changing a resource.

Build the Power Automate loop

Use the same flow shape for every operation:

1. Add one of the connector’s start actions.
2. Initialize handle, isComplete, and finalStatus from the response.
3. Add a Do Until loop that runs until isComplete equals true.
4. Inside the loop, add a Delay using retryAfterSeconds.
5. Call Get Operation Status with handle.
6. Set isComplete and finalStatus from the status response.
7. If the new operationHandle isn’t empty, update handle.
8. After the loop, branch on finalStatus. Read result for success or error for failure.

Set the loop count and timeout high enough for the slowest expected operation. Every iteration uses one connector request.

The condition in step 7 matters. Power Automate rejects a variable update that references the same variable:

Self reference is not supported when updating the value of variable

An expression such as coalesce(body('Get_Operation_Status')?['operationHandle'], variables('handle')) won’t work. Use a condition and update the variable only when the response contains a handle. The final status response returns a null handle, so the condition also avoids replacing the last valid value with null.

Handle both Azure polling shapes

Azure documents two ways to track an asynchronous operation. The start response tells the caller which one to use.

The distinction has two sharp edges.

First, an async header takes precedence over the HTTP status. A network security group create can return HTTP 201 with Azure-AsyncOperation. Code that assumes every non-202 response has finished will report success too early.

Second, Location means “poll this URL” only when the response is HTTP 202. A Location header on HTTP 201 often points to the resource that was just created. Polling that URL would mistake the resource document for an operation status.

The script resolves these rules when the operation starts:

if (TryHeader(response, "Azure-AsyncOperation", out url))
    return new JObject { ["u"] = url, ["k"] = "azureAsync", ["v"] = HANDLE_VERSION };

if (TryHeader(response, "Operation-Location", out url))
    return new JObject { ["u"] = url, ["k"] = "azureAsync", ["v"] = HANDLE_VERSION };

if (response.StatusCode != HttpStatusCode.Accepted)
    return null;

if (response.Headers.Location != null)
    return new JObject { ["u"] = response.Headers.Location.ToString(), ["k"] = "location", ["v"] = HANDLE_VERSION };

Operations that return no async header have completed inline. An action such as listKeys can return isComplete: true and put its response body in result without entering the loop.

Keep the operation handle opaque

The handle is compact, base64url-encoded JSON:

{
  "u": "https://management.azure.com/...",
  "k": "location",
  "v": 1
}

It records the polling URL, polling shape, and schema version. The flow doesn’t need to parse any of them. Base64url makes the value convenient to carry through a flow, but it doesn’t sign or encrypt it.

A flow variable is user-editable, and each status request carries the connection’s bearer token. The script rejects a handle unless its polling URL is absolute HTTPS, which prevents cleartext forwarding. When adapting the template for production, also allowlist the service’s expected polling hosts or add an integrity check. HTTPS alone doesn’t prove that an edited handle still points to Azure.

Return predictable errors

Each action returns HTTP 200 to Power Automate. A failed Azure operation appears in the response envelope:

{
  "status": "Failed",
  "isComplete": true,
  "retryAfterSeconds": 0,
  "operationHandle": null,
  "error": {
    "code": "ResourceGroupNotFound",
    "message": "Resource group 'rg-missing' could not be found.",
    "httpStatus": 404
  }
}

This keeps the Do Until loop on one branch. The flow checks status instead of catching a connector exception midway through the loop.

The script also preserves nested Azure errors. If a template deployment fails because a storage account name is taken, the top-level DeploymentFailed message remains in error, and the underlying conflict remains in error.details.

error.httpStatus appears only when the HTTP request failed. Azure can return HTTP 200 for a status document whose operation state is Failed; adding "httpStatus": 200 to that error would be misleading.

Use the ARM connector

The complete Azure Async Operations connector exposes six actions.

The start actions accept the target API version, so one connector can work across resource providers.

Use Create or Update Resource for a template deployment. Its deployment resource follows the standard ARM resource path.

Deploy the ARM connector

You need:

• An Azure subscription and permission to manage the target resources
• An Entra app registration
• A Power Platform environment that allows custom connectors
• Power Platform CLI

Register an Entra application, add the Azure Service Management user_impersonation delegated permission, grant admin consent, and create a client secret. Put the application ID in apiProperties.json, but don’t commit the secret.

Deploy all three connector files:

pac connector create `
    --api-definition-file apiDefinition.swagger.json `
    --api-properties-file apiProperties.json `
    --script-file script.csx

The connector authenticates for the https://management.azure.com audience. Azure also requires enough permission to read the operation status URL. The ARM guidance notes that status tracking can require resource group-level permission even when the caller can start an operation at the resource level.

Register the generated redirect URL

After deployment, Power Platform replaces the placeholder redirect URL with a connector-specific URL. Download the deployed connector and read:

properties.connectionParameters.token.oAuthSettings.redirectUrl

Add that generated URL to the Entra app registration. OAuth consent will fail if only the generic https://global.consent.azure-apim.net/redirect URL is registered. Each Power Platform environment generates a different redirect URL.

Adapt the polling template

The standalone project contains script.csx without an OpenAPI definition. Copy it into an existing connector and change three settings:

private static readonly HashSet<string> START_OPERATIONS =
    new HashSet<string>(StringComparer.Ordinal)
{
    "StartLongRunningOperation"
};

private const string POLL_OPERATION = "GetOperationStatus";
private const string HANDLE_PARAMETER = "operationHandle";

Then:

1. Add every start and poll operation to scriptOperations in apiProperties.json.
2. Review NormalizeStatus for the service’s status vocabulary.
3. Review NormalizeError for the service’s error body.
4. Confirm which header or operation ID identifies the polling URL.
5. Test synchronous success, synchronous failure, async success, async failure, and an unknown status.

Build one connector per service. A connection carries one OAuth audience, so an ARM connector can’t also call Fabric or Foundry with the same token.

Test the boundary cases

The implementation was checked against live ARM with 66 assertions. Coverage included:

• Location polling from storage account creation
• Azure-AsyncOperation polling from network security group creation
• A start call that returned in under one second
• A slowest observed poll of 0.3 seconds
• Synchronous HTTP 400 and 404 failures
• An ARM deployment that failed during provisioning
• Inline completion from listKeys
• Subnet create and delete operations
• Malformed, empty, and non-HTTPS handles
• Known and unknown status values

The connector was also deployed and run through a Power Automate Do Until loop. ARM supplied a 17-second retry interval, the flow completed after three polls, and the final result reported provisioningState: Succeeded.

Resources

• Azure Async Operation Polling template
• Azure Async Operations connector
• Track asynchronous Azure operations
• Write code in a custom connector
• Create a custom connector from an OpenAPI definition

Microsoft plans to migrate those older agents in a future update. Copilot Studio Bots v1.1 lets you move first, test the result, and roll back an agent that fails validation.

The release adds two Power Automate actions and two Model Context Protocol (MCP) tools to the evaluation, inventory, and containment connector introduced in the original post.

What’s new in v1.1

The two new Power Automate actions are:

Copilot Studio agents get matching tools:

• migrate_agent_identity
• rollback_agent_identity

Both take an environment ID and agent ID. The Power Automate actions use the connector’s existing cascading dropdowns, while MCP callers can use list_agents to find the raw identifiers first.

Why migrate before Microsoft does

A Microsoft Entra Agent ID gives administrators a first-class identity for each agent. Microsoft lists several benefits:

• Agent sign-in and audit logs in Microsoft Entra
• Agent lifecycle management
• Connector permissions visible as API permissions
• Conditional Access policies scoped to agent activity
• Integration with Microsoft Entra ID Governance

Manual migration gives you a window to test those controls against your own channels, connectors, actions, flows, and authentication settings before automatic migration reaches the tenant.

The migration converts the identity in place. The application (client) ID stays the same, so channel registrations and connectors continue to resolve to the same identifier. A successful response also returns the new agentIdentityId and servicePrincipalObjectId for lookup in the Microsoft Entra admin center.

The API sits next to the Bots operations

The new routes use the same Power Platform host, agent path, OAuth connection, and 2024-10-01 API version as the connector’s 13 Bots operations:

POST https://api.powerplatform.com/copilotstudio/
     environments/{environmentId}/bots/{botId}/
     api/agentidentitymigration/migrate?api-version=2024-10-01

POST https://api.powerplatform.com/copilotstudio/
     environments/{environmentId}/bots/{botId}/
     api/agentidentitymigration/rollback?api-version=2024-10-01

They aren’t part of the Bots REST operation group. Microsoft documents them separately in the agent identity migration guide, and the manual migration feature is in preview.

Neither request has a body. A migration returns one of two terminal statuses:

{
  "status": "Migrated",
  "cdsBotId": "00000000-0000-0000-0000-000000000000",
  "environmentId": "00000000-0000-0000-0000-000000000000",
  "tenantId": "00000000-0000-0000-0000-000000000000",
  "agentIdentityId": "00000000-0000-0000-0000-000000000000",
  "applicationId": "00000000-0000-0000-0000-000000000000",
  "servicePrincipalObjectId": "00000000-0000-0000-0000-000000000000",
  "completedAtUtc": "2026-08-27T20:00:00Z"
}

AlreadyMigrated is also a successful result. Migration is idempotent, so a repeated call doesn’t create a second identity.

Rollback returns RolledBack or NotMigrated. NotMigrated means there was nothing to undo, not that the request failed.

Migrate in stages

Migration affects a live agent. Microsoft recommends a staged rollout instead of moving the whole estate at once:

1. Pick a small group of noncritical agents
2. Include the channels, authentication modes, connectors, flows, and integrations you need to test
3. Coordinate a validation window with the makers
4. Migrate one agent or a small batch
5. Test every published channel, action, connector, and authentication flow
6. Review Microsoft Entra sign-in logs and Conditional Access results
7. Roll back failures before starting the next batch

The API migrates one agent per request. A Power Automate flow can loop over a planned batch, but leave room between calls. The service can return 429 Too Many Requests, and the connector surfaces that response instead of hiding it behind automatic retries.

Administrative permissions still apply. The caller must be a Power Platform Administrator, Dynamics 365 Administrator, or Global Administrator. A caller without the required role receives 403 Forbidden.

Use an agent for a plan-and-apply migration

The existing list_agents tool makes identity migration easier to control. Let the agent inventory the environment first, then name the agents to migrate:

User: List the unpublished agents in the sandbox environment.

Agent:
  1. list_agents { environmentId: "<sandbox-environment-id>" }
  2. Presents agent names, owners, publish state, and IDs

User: Migrate Contoso Support Test and Expense Policy Test.

Agent:
  3. migrate_agent_identity { environmentId, botId } for each named agent
  4. Reports Migrated or AlreadyMigrated and the new agent identity IDs

User: Expense Policy Test can no longer authenticate in Teams. Roll it back.

Agent:
  5. rollback_agent_identity { environmentId, botId }
  6. Reports RolledBack

This keeps discovery separate from the write. The user sees the inventory and names the migration set before any identity changes.

Rollback makes the operation recoverable, but it doesn’t replace testing. Stop the batch when an agent fails validation, undo that agent, and find the cause before continuing.

Update the connector

Replace REPLACE_WITH_CLIENT_ID in apiProperties.json, then validate and update the connector with the Power Platform Connector CLI and Power Platform CLI:

ppcv "./Copilot Studio Bots"

pac connector update `
    --connector-id 00000000-0000-0000-0000-000000000000 `
    --api-definition-file apiDefinition.swagger.json `
    --api-properties-file apiProperties.json `
    --script-file script.csx

Keep --script-file. The MCP endpoint and its two new tools run through script.csx, and the connector declares script operations in apiProperties.json.

Existing flows keep their actions. After the update, the two migration actions appear beside evaluation, quarantine, consent bypass, reassignment, deletion, and agent inventory.

Resources

• Copilot Studio Bots v1.1 source
• v1.1 commit
• Microsoft Entra Agent IDs for Copilot Studio
• Migrate agents to Microsoft Entra Agent ID
• Original Copilot Studio Bots post

It’s a profile, not a plugin. That distinction turned out to be the whole design, so it’s worth explaining before anything else.

Submitted to the Elgato Marketplace. If you want automatic updates, wait for that release rather than installing the GitHub build by hand. The GitHub release works today, but you’ll have to re-import it yourself when a new version ships.

Why a profile beats a plugin here

ZoomIt exposes no API, no IPC, and no command-line trigger. Its entire control surface is global hotkeys plus single keystrokes while a mode is active. Stream Deck’s built-in Hotkey action already sends those, for keys and dials alike.

That built-in action is marked "PrivateAPI": true, so third-party plugins can’t call it, and the SDK has no keyboard API at all. A plugin would mean re-implementing keystroke injection in native code — FFI to SendInput or a helper executable — and shipping per-architecture binaries through review to do a worse job than the action Elgato already ships.

A plugin could add exactly two things a profile can’t: live state feedback and reading the user’s remapped hotkeys. ZoomIt exposes no state, and its defaults never touch disk, so neither is achievable. PowerToys writes to HKCU\Software\Sysinternals\ZoomIt only when a hotkey changes from its default, so a fresh install has one value: EulaAccepted.

What’s on the deck

Three pages on a 5×3 MK.2, 45 keys, 41 of ZoomIt’s 45 shortcuts.

Zoom, Draw, Break, LiveZoom, LiveDraw, DemoType, Record, and Panorama are toggles. A second press sends Esc, and the icon flips to show the mode is live.

Whiteboard is a Multi Action Switch: one press sends Ctrl+1 → K → Ctrl+W — zoom, black pen, blank to white. Ordering matters. Send K after Ctrl+W and drawing reverts the blank.

Four shortcuts are impossible from a Stream Deck at all: straight line, rectangle, ellipse, and arrow each need a modifier held through a mouse drag, and a key only sends press-release.

Three device layouts

The grid is parameterised in a device block, so a new variant is a config file rather than a code change. Model IDs and grid sizes came from Elgato’s own per-device defaults in Program Files\Elgato\StreamDeck\DefaultProfiles.

The Mini is deliberately minimal. Fitting the full set into six keys needs roughly nine folder pages, which is worse than useless mid-presentation, so it carries four desktop triggers, five pen colours, and five drawing tools.

Coordinates are validated against the declared grid, so a key that would land off the device fails the build instead of being silently dropped. One caution if you build your own variants: the shipped Stream Deck + default profile reports a 5×3 keypad, which contradicts the hardware. Treat 4×2 as correct.

The profile format rules nobody documents

These came from diffing against working profiles and reading logs\StreamDeck.log. Break any of them and you get a silent or misleading failure.