It also answers the question the Bots API can’t: which agents are worth containing. The API quarantines an agent by ID but exposes no harness, template, or recognizer field, so the connector reads the Power Platform resource query API for a tenant-wide inventory that flags GitHub Copilot harness agents — the ones billing 100 to 500+ Copilot Credits per task.

This replaces an earlier connector, Copilot Studio Evaluations, which covered five operations from the same API group and stopped at measurement. A nightly quality check that quarantines a regressed agent needs the administrative half too, so all 13 operations now share one connection.

What the 13 operations do

{base} is /environments/{environmentId}/bots/{botId} on https://api.powerplatform.com/copilotstudio, with api-version pinned to 2024-10-01.

The first six are maker operations — anyone with access to the agent can run them. The last seven need Power Platform or Dynamics 365 administrator rights, and the API returns 403 to everyone else no matter how the connector or DLP policy is configured. The inventory reads tenant-wide resources, so it needs administrator rights too.

Each operation is also an MCP tool: get_test_sets, get_test_set_details, start_evaluation, list_test_runs, get_run_details, download_evaluation_snapshot, get_quarantine_status, quarantine_agent, unquarantine_agent, get_connector_consent_bypass, set_connector_consent_bypass, reassign_agent, and delete_agent. Three more tools — list_agents, find_containment_candidates, and contain_agents — come from the inventory rather than the Bots API, for 16 in total.

Tooling reports a third number. ppcv and PAC CLI count 17 operations in the OpenAPI definition: the 13 Bots operations, List Agents, two internal dropdown sources, and the JSON-RPC endpoint. The Power Automate action list shows 16, since the internal two are hidden. That the MCP count also lands on 16 is a coincidence — the REST side includes two dropdown operations that aren’t tools, and the MCP side includes two containment tools that have no REST equivalent.

The metrics are booleans, not scores

get_run_details returns results nested three levels deep:

run
├── state              Pending | Running | Completed | Failed
├── totalTestCases
└── testCaseResults[]
    ├── testCaseId
    ├── state          Passed | Failed | Error
    ├── errorReason    populated when the case failed
    ├── aiResultReason AI-generated explanation of the outcome
    └── metricsResults[]
        ├── type       e.g. GeneralQuality, Hallucination
        └── result
            ├── abstention    boolean
            ├── relevance     boolean
            └── completeness  boolean

Abstention, relevance, and completeness are true or false per test case. There’s no percentage or confidence value anywhere in the response, so a quality figure has to be aggregated yourself — “relevance false in 3 of 20 cases” rather than “85% relevant.” Models left to their own devices report these as percentages, which is why the sample system prompt says not to.

Read abstention: true as neutral. An agent that declines an out-of-scope question is behaving correctly. And aiResultReason is the field worth quoting to a human, since it explains why a case landed where it did.

Guards on the destructive operations

Handing an agent a tool that permanently deletes a copilot needs a gate. Three are built in:

• delete_agent refuses to run without confirm: true. The API has no undelete, so an ambiguous instruction can’t cost you an agent. The REST Delete Agent action has no such guard — treat it carefully in flows.
• contain_agents accepts no filter and requires confirm: true. It takes an explicit list of agents, so no single call can quarantine a population the caller hasn’t already seen and named.
• reassign_agent converts 204 No Content to { "status": 204, "succeeded": true }. An empty body reads like a failure to a calling model, which then retries a reassignment that already worked.

Quarantine is the reversible option and usually the right first move. A quarantined agent stays editable for makers and administrators; only end users lose access. Enabling connector consent bypass goes the other way — it removes an end user safeguard, so audit which connections the agent uses before turning it on.

Snapshots are binary

download_evaluation_snapshot returns a ZIP. The connector reads the response as bytes rather than text, because string handling corrupts the archive. Files 4 MB or smaller come back as an MCP resource with a base64 blob. Larger ones return metadata and a pointer to the REST operation, which is the better path anyway — stream the archive to SharePoint or OneDrive in a flow instead of through a conversation. The file name comes from Content-Disposition, falling back to evaluation-snapshot-{testRunId}.zip.

Which agents run the expensive harness

list_agents returns isCLIAgent for every agent in the tenant:

Three things to know before building on it:

• It’s a string, not a boolean. A flow condition testing it as a boolean silently never matches.
• "unknown" is not "false". An absent field isn’t evidence of the cheap harness, and that’s the direction you least want a cost report to guess in.
• "false" covers two harnesses. It can’t separate Standard from Copilot Chat, so the harness label says Standard or Copilot Chat rather than inventing precision the source doesn’t have.

To confirm a single agent definitively, clone it with the VS Code extension. The GitHub Copilot harness projects template: cliagent-1.0.0 and recognizer.kind: CLICopilotRecognizer, against default-2.1.0 and GenerativeAIRecognizer for Standard.

Plan, then apply

Discovery and containment are separate tools on purpose.

find_containment_candidates is read-only and quarantines nothing. It returns each matching agent with the reasons it qualified, plus skippedUnknownHarness and skippedAlreadyQuarantined counts so you can see what it declined to touch.

contain_agents takes an explicit array of { environmentId, botId } pairs and confirm: true. Failures are per-agent, so one 403 doesn’t abandon the rest of the batch, and the result reports succeeded, failed, and a per-agent breakdown.

User: "Find GitHub Copilot harness agents shared with everyone that were never published"
Agent:
  1. find_containment_candidates { requireNeverPublished: true }
     → 2 candidates, each with reasons
       [githubCopilotHarness, sharedWithEntireTenant, neverPublished]
     → skippedUnknownHarness: 1   (reported, not contained)
  2. Presents them with owners and environments
User: "Quarantine both"
  3. contain_agents { agents: [ {...}, {...} ], confirm: true }
     → succeeded: 2

The three composite tools break the usual error convention. They report outcomes inside the payload and set isError only when the whole operation failed, so a batch where some agents were quarantined and others rejected returns isError: false with the failures itemized in results. Read succeeded and failed, not the flag.

Two limits shape the inventory. It pages 1,000 rows at a time and stops after 10 pages, setting truncated: true rather than quietly returning a partial estate — scope to an environment if you hit it. And SkipToken doesn’t work: the service returns one but it never advances, so the connector pages with Skip offsets ordered by a unique tiebreaker to keep the window stable.

The inventory reads resourcequery at api-version=2022-03-01-preview, which returns the resource provider’s raw property bag. isCLIAgent isn’t in the published reference and can change shape or disappear without notice. Use it for reporting and chargeback triage, not as a hard enforcement gate.

Pickers, and what can’t be one

Environment ID, Agent ID, Test Set ID, and Test Run ID are all dropdowns in the Power Automate and Logic Apps designers, each cascading from the one before it.

The environment picker runs on an internal operation at /metadata/environments that the script rewrites to https://api.powerplatform.com/environmentmanagement/environments. That endpoint reports the environment identifier inconsistently, sometimes as a bare GUID in name and sometimes as an ARM-style path in id, so the connector normalizes both to the bare GUID the Bots operations expect.

The agent picker works the same way from /metadata/agents, backed by the inventory query. Because it already knows the harness, it appends (GitHub Copilot) to those entries — you see which agent is the expensive one at the moment you pick it.

Owner ID isn’t a picker. Resolving users means Microsoft Graph, a different host, and a connector can’t reach across hosts to back a dropdown.

Dropdowns are a designer convenience. MCP tools receive raw IDs, so an agent calling quarantine_agent still needs both GUIDs.

The flow that motivated the merge

1. Trigger: Scheduled (daily at 2 AM)
2. Get Agent Test Sets
3. For Each test set (Apply-to-each concurrency OFF)
   4. Start Agent Evaluation
   5. Poll Get Agent Test Run Details until state is Completed or Failed
   6. Count test cases where relevance or completeness is false
   7. Condition: failing count above your threshold
      8. Quarantine Agent
      9. Download Agent Evaluation Snapshot and save to SharePoint
      10. Email the agent owner with the failing cases and aiResultReason

Concurrency stays off for a reason. An agent runs one evaluation at a time, and Start Agent Evaluation returns 422 if a run is already in progress. Poll each run to completion before starting the next, and treat Failed as terminal so the loop can’t spin forever. Test sets also have to be Active — inactive sets come back from Get Agent Test Sets but won’t run.

A second flow reclaims ownership drift: List Agents weekly with a blank environment ID, check each ownerId against Entra ID, and reassign anything owned by a disabled account to a governance service account.

A third reports cost exposure monthly — List Agents across the tenant, filter isCLIAgent equal to 'true', and mail a table of display name, environment, owner, and lastPublishedAt. Filter 'unknown' separately and label those “harness unresolved,” never Standard.

Three details catch flow authors out. List Agents returns an object, not an array, so apply-to-each over agents and check truncated before treating the result as the whole estate. An empty lastPublishedAt means never published, not an unknown date. And channels and reasons are string arrays — flatten with join(item()?['reasons'], ', ') for a table or email body.

Status codes

MCP tool calls surface these as isError: true with the status code in the message text, so an agent can read and explain the failure. JSON-RPC errors (-32601, -32602) are reserved for unknown methods and malformed tool calls.

Setup

Register an Entra application with Power Platform API permissions and the https://api.powerplatform.com/.default scope, then put the client ID in apiProperties.json. Deploying with REPLACE_WITH_CLIENT_ID still in place succeeds, but no connection can be created, so set the real value first.

Validate with ppcv "./Copilot Studio Bots", then deploy. --script-file is mandatory:

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

Omitting it fails with InvalidScriptDefinitionUrlWithNonNullOperations, because apiProperties.json declares scriptOperations and the service won’t accept them with no script to route them to. A second failure, CustomScriptProvisioningFailed or FindAndAssignFunctionApp, means the region has no unassigned function app for custom code — creating a new script-enabled connector draws from that pool, while updating an existing one reuses its assignment and usually still works.

Without the script the 13 Bots operations still pass through untouched, but the MCP endpoint, both dropdowns, List Agents, and the containment tools don’t.

Evaluation with an authenticated agent connection needs an MCS Connection ID. Open the Connections page in Power Automate, select the Microsoft Copilot Studio connection, and copy mcsConnectionId from the URL.

Application Insights telemetry ships in script.csx, disabled by default. Set APP_INSIGHTS_ENABLED = true, drop in your instrumentation key, and redeploy to log every MCP request, tool call, and exception. That gives you an audit trail for the administrative tools:

customEvents
| where name == "MCP_ToolCall"
| summarize Count = count() by tostring(customDimensions.tool), tostring(customDimensions.status)

Related connectors

Resources

• Copilot Studio Bots connector on GitHub
• Power Platform API Bots operations
• Agent evaluations in Copilot Studio
• Quarantine noncompliant agents with the Power Platform API

One connector, two ways to use it. The InvokeMCP operation speaks JSON-RPC 2.0 and exposes 73 tools, 7 resources, and 5 prompts to any MCP client — Copilot Studio, Microsoft Foundry, Agent Framework. The other 116 operations call Graph directly for Power Automate and Logic Apps. Both share one connection and one set of delegated permissions.

Four layers, created in order

Getting this order wrong is the most common source of opaque 400 responses.

The provision_agent tool runs steps 2 through 4 in a single call and reports what it did at each one, including any step that was already satisfied.

Three rules save a lot of debugging:

• Create an agent identity with the blueprint’s appId, not its object id. The agentIdentityBlueprintId property takes the client ID. Graph reports the mistake as AgentIdentity_IncompatibleParentType.
• Deletion cascades downward, not upward. Deleting a blueprint or blueprint principal starts an asynchronous background cleanup that soft-deletes every child agent identity and agent user. It can lag by hours or days and appears in audit logs as Delete Agent Identities Task. Deleting an agent identity on its own leaves its agent user behind, so remove that explicitly.
• Everything soft-deletes with a 30 day restore window. Restoring a blueprint principal after the cascade has run does not bring its children back — restore each one individually. Soft-deleted objects keep consuming quota until you permanently delete them.

Tools worth knowing

The 73 MCP tools group into blueprints (13), blueprint principals (6), federation and inherited permissions (6), agent identities (18), agent users (10), lifecycle and governance (7), and risk, inherited permissions, and registry (13, beta).

A handful carry most of the weight:

Five prompts ship with the server — onboard_agent, federate_third_party_agent, audit_agent_governance, investigate_agent_risk, and offboard_agent. Each encodes the confirmation gates and ordering constraints so the model doesn’t rediscover them. Seven resources expose the lifecycle model, federation patterns, the beta surface and its licensing, the blocked permission list, the error catalogue, the connector’s scopes, and the directory roles each operation needs.

Error codes that tell the model what to do

Graph returns agent identity failures as opaque code strings. Given only a code, a model retries the identical call. The connector maps all 17 documented error codes to the concrete next step and appends it to the failure:

["AgentIdentity_AgentBlueprintPrincipalDoesNotExist"] =
    "The blueprint has no blueprint principal in this tenant, which is a prerequisite for creating agent identities from it. Call create_blueprint_principal with the blueprint's appId first, or use provision_agent which handles the ordering.",
["AgentIdentity_CredentialsNotSupported"] =
    "Agent identities cannot hold credentials. Every secret, certificate, and federation trust belongs on the blueprint — use add_blueprint_password or add_blueprint_federated_credential instead.",

Two failures arrive without a usable code, so the connector reads the path instead. A 403 on a sponsors collection means Graph supports that route with application permissions only, and the message points at get_agent_overview, which expands sponsors from the identity itself. A 400 on appRoleAssignments suggests a blocked permission — Entra rejects those without naming the offender — and the message points at check_blocked_permissions.

Third-party agents authenticate without secrets

An agent running on AWS, n8n, or Kubernetes shouldn’t hold a client secret. A blueprint doubles as a token factory through workload identity federation: the external platform’s own token is exchanged for an Entra token, with nothing stored on the agent.

Configure the trust with add_blueprint_federated_credential. Setting platform: entra_agent_identity builds the issuer from your tenant ID and uses the agent identity as the subject. Setting platform: custom takes the issuer and subject your external provider puts in its tokens — get those from that platform’s own configuration, because a wrong value fails at runtime with an unhelpful error. The audience defaults to api://AzureADTokenExchange, a blueprint holds at most 20 credentials, and each issuer/subject pair must be unique.

Credentials live on the blueprint, never on the agent identity. Graph reports violations as AgentIdentity_CredentialsNotSupported.

Inheritable permissions change what an audit means

A blueprint grants its agent identities delegated scopes automatically, with no separate consent prompt. Three patterns apply: enumerated inherits only the scopes you list, all_allowed inherits everything the resource application publishes, and none inherits nothing. Prefer enumerated.

An agent’s effective access is its own assignments plus what its blueprint grants. Auditing only the former understates its reach — read the rest with list_agent_inherited_permissions. Moving to a more restrictive pattern means agents still needing a removed scope must obtain fresh consent, so check what’s live with list_inheritable_permissions before narrowing.

The beta surface

Four areas run on Graph beta. The connector’s basePath is /v1.0 and it rewrites the version segment for these operations only, so v1.0 and beta calls never cross over.

Containment is not blocking. Confirming an agent compromised raises its risk level, and quarantining moves it in the registry. Neither stops it authenticating — only set_agent_identity_enabled does that.

The agent registry is transitional. Microsoft replaces it with the Agent Registry powered by Microsoft Agent 365 from May 2026. Every tenant reserves two immutable collections: Global (…0001) and Quarantined (…0002).

Skip the six beta scopes for a v1.0-only deployment.

In Power Automate

Every operation other than InvokeMCP is a plain Graph call — 90 on v1.0 and 27 on beta. An onboarding flow runs the same four layers:

1. CreateBlueprint          → displayName, sponsors@odata.bind
2. CreateBlueprintPrincipal → appId from step 1
3. CreateAgentIdentity      → agentIdentityBlueprintId = appId from step 1, sponsors@odata.bind
4. CreateAgentUser          → identityParentId = id from step 3
5. SetAgentUserManager      → @odata.id pointing at the human manager

Reference bodies use the OData bind syntax Graph expects:

// sponsors, on create
{ "sponsors@odata.bind": ["https://graph.microsoft.com/v1.0/users/{userId}"] }

// owners, sponsors, and managers, on $ref endpoints
{ "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{objectId}" }

A few limits shape flow design. An agent identity holds one agent user, and a second CreateAgentUser against the same identityParentId returns 400. Agent users don’t support $skip, so page with the returned @odata.nextLink. Blueprints, blueprint principals, and agent identities cap at 100 per page and 250 agent identities per blueprint. Soft-deleted objects still count against that ceiling, so permanently_delete_agent_object is what actually frees room.

Setup

Register an Entra application with the redirect URI https://global.consent.azure-apim.net/redirect, then add the delegated Graph permissions. The v1.0 set covers AgentIdentity.*, AgentIdentityBlueprint.*, AgentIdentityBlueprintPrincipal.*, AgentIdUser.ReadWrite.All, AppRoleAssignment.ReadWrite.All, User.Read, and offline_access. Add IdentityRiskyAgent.ReadWrite.All, IdentityRiskEvent.Read.All, Policy.Read.ConditionalAccess, AgentInstance.ReadWrite.All, AgentCollection.ReadWrite.All, and Application.Read.All only if you want the beta tools. Grant admin consent for all of them.

Then edit apiProperties.json with your client ID and secret, import apiDefinition.swagger.json through the Maker portal or paconn create, and sign in as an Agent ID Administrator. Agent ID Developer works for blueprint creation only.

Watch ownership as closely as role assignments. A principal that creates a blueprint or blueprint principal becomes its owner automatically and can then manage the derived agent identities with no role at all.

Where it fits

Use this connector for identity and governance. Use Agent 365 MCP for what the agent does at runtime.

Resources

• Entra Agent ID connector on GitHub
• Microsoft Entra Agent ID APIs in Microsoft Graph
• What is Microsoft Entra Agent ID?
• Agent identity blueprints
• The agent’s user account
• Integrate third-party agents
• Secure an Amazon Bedrock agent
• Secure an n8n agent
• ID Protection for agents
• Conditional Access for agents
• Agent identity platform error codes

This is the counterpart to my self-hosted Salesforce Cowork plugin, which ships a C# MCP server on Azure Container Apps. Same CRM workflows, opposite architecture.

How it works

Copilot Cowork
   |  MCP (streamable HTTP) + OAuth 2.0 / PKCE
   v
https://api.salesforce.com/platform/mcp/v1/platform/sobject-all
   |  runs as the signed-in Salesforce user
   v
Salesforce org - profile, sharing rules, field-level security enforced

The plugin contributes two things: a connector definition that points at the Salesforce endpoint, and nineteen skills that carry the CRM domain knowledge.

That second part is where the work went. The hosted server exposes generic sObject tools — soqlQuery, getObjectSchema, createSobjectRecord — not search_accounts-style domain tools. Without skills, the agent guesses field API names and SOQL syntax on every turn. The skills name the objects, the fields, the exact queries, how to read the results, and when to stop and ask before writing.

Tools on the default server

The plugin targets platform/sobject-all, which provides eleven tools:

Salesforce publishes seven standard servers. Four cover sObjects at different permission levels, and three cover Data 360 and Tableau Next.

Nineteen skills

Ten read skills, eight write skills, and one meta skill:

Every write skill shows a before/after diff and requires explicit confirmation before it calls a mutation tool. delete-salesforce-record goes further: it asks for confirmation by record name and Id, and discloses what the cascade will remove.

Two reference files carry the detail that would otherwise bloat every skill — a CRM object reference with field API names, picklist values, Id prefixes, and required fields, and a SOQL cookbook covering aggregates, relationships, escaping, error codes, and limits. Cowork loads them only when a skill needs them.

Pick a server with configure.ps1

Different orgs want different blast radius. configure.ps1 rewrites mcpServerUrl and declares only the skills the target server can actually support:

./configure.ps1 -ListServers                    # see the options
./configure.ps1 -Server sobject-all             # full CRUD (default)
./configure.ps1 -Server sobject-reads           # read-only deployment
./configure.ps1 -Server sobject-all -Sandbox    # sandbox or scratch org
./configure.ps1 -Server sobject-all -ReferenceId "<auth-config-id>"

Skill folders stay in the repo, so re-running with a broader server restores the fuller set. preflight.ps1 fails the build if a hand-edited manifest declares a skill the target server can’t run.

The skill counts drop sharply on the mutation and delete servers because Salesforce exposes getUserInfo only on sobject-reads and sobject-all. Six skills resolve “my deals” and “my tasks” through it. Treat those two servers as narrow, purpose-built deployments rather than general CRM assistants.

Custom servers

Salesforce Setup can build a custom MCP server that composes sObject tools with Apex invocable methods, @AuraEnabled controllers, Apex REST endpoints, API Catalog entries, Flows, and Prompt Builder templates. Target one with:

./configure.ps1 -CustomServer "myorg/crm-plus"
./configure.ps1 -CustomServer "myorg/crm-readonly" -BaseOn sobject-reads

-BaseOn tells the script which standard tool set the custom server is assumed to include, so it can pick the skill set. Verify that assumption against the server’s real tools/list output — preflight.ps1 can’t validate a custom server’s tools.

Custom servers are also the route around the plugin’s two biggest gaps. Lead conversion and record merge have no operation on the standard sObject servers. An admin can expose either as a Flow or @InvocableMethod, then add a skill that names that tool.

Authentication

Salesforce Hosted MCP uses OAuth 2.0 authorization code with PKCE, per user. Three facts drive the configuration.

Dynamic client registration isn’t supported. Salesforce says so explicitly, so the connector can’t omit authorization and let Cowork self-register. Create an auth config up front in the Microsoft Enterprise token store and reference it with authorization.type of OAuthPluginVault.

Connected Apps aren’t supported. You need an External Client App in the Salesforce org, with the mcp_api and refresh_token scopes and JWT-based access tokens for named users. Budget for propagation: the ECA can take up to 30 minutes to become operational.

The redirect URI is fixed. Register https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect as the ECA callback URL. It’s identical for every Copilot plugin and every OAuth provider.

offline_access is a Microsoft identity platform scope. Salesforce uses refresh_token instead, which is already in the list. Adding offline_access here breaks the registration.

Every action runs as the signed-in Salesforce user. The plugin has no service account and can’t exceed that user’s profile, sharing rules, or field-level security.

Deploy

1. In Salesforce: create the External Client App with the Teams callback URL, add the mcp_api and refresh_token scopes, enable JWT-based access tokens for named users, and enable the MCP server under Setup > Integration > Salesforce MCP Servers. The server is off by default.
2. Verify in Postman before touching Cowork. Add the Postman callback to the ECA, create an MCP request over HTTP, authorize with PKCE, then confirm tools/list returns the eleven tools and getUserInfo returns the right user. If this fails, nothing downstream will work.
3. In Microsoft 365: create the OAuth auth config in Teams developer portal > Tools > OAuth client registration. Supply the ECA consumer key and secret, the Salesforce endpoints, scopes mcp_api refresh_token, and PKCE. Set Base URL to the same value as mcpServerUrl. Capture the auth config ID.

4. Configure, validate, and package:

   cd "Cowork Plugins/Salesforce Hosted MCP"
   ./configure.ps1 -Server sobject-all -ReferenceId "<auth-config-id>"
   ./preflight.ps1
   ./package.ps1
   

5. Upload Salesforce Hosted MCP.zip in the Microsoft 365 admin center, publish to test users, then connect in a fresh Cowork session. An existing session won’t pick up a newly published connector.

preflight.ps1 -AllowPlaceholders downgrades unresolved placeholders to warnings while you’re still developing.

Smoke test in this order

Who am I in Salesforce?

What's my Salesforce pipeline this quarter?

Brief me on [a real account].

What fields are on the Opportunity object?

Those four exercise getUserInfo, SOQL aggregates, find plus multi-query synthesis, and getObjectSchema in turn. Finish with a small write on a test record to confirm the confirmation gate fires before anything is saved.

Two things that cost me time

The manifest schema matters. This plugin uses vDevPreview (manifestVersion: "devPreview"), not v1.28. In Cowork’s current runtime, only the devPreview path binds the MCP connector. A v1.28 manifest loads the skills and silently drops the connector, so the agent never invokes a tool and gives you no reason why. devPreview also wants packageName in reverse-DNS form and omits mcpToolDescription — Cowork discovers tools through MCP tools/list.

Base URL must match mcpServerUrl. A mismatch in the Teams developer portal registration produces no clear error. Sign-in succeeds, the connector stays disconnected, and token exchange quietly fails.

Hosted or self-hosted

Choose hosted MCP for breadth and zero infrastructure. Choose self-hosted when you need response shaping, custom telemetry, request-level policy, or tool definitions that hide the Salesforce data model from the agent.

Known constraints

• Lead conversion and record merge have no operation on the standard sObject servers. Expose them as a Flow or invocable action on a custom server, or handle them in Salesforce.
• Opportunity products need a Pricebook2Id on the opportunity before OpportunityLineItem records can be created.
• SOQL returns at most 50,000 records per transaction; SOSL find returns at most 2,000.
• Deletions are recoverable for 15 days from the Recycle Bin. The connector has no undelete tool.
• Custom picklist values are the norm, so skills call getObjectSchema before writing picklist fields rather than assuming Salesforce defaults.

Resources

• Salesforce Hosted MCP Cowork plugin
• Setup checklist
• SharingIsCaring repository
• Self-hosted Salesforce Cowork plugin
• Salesforce Hosted MCP servers in Copilot Studio
• Build plugins for Copilot Cowork
• Configure plugin authentication

The plugin connects directly to GitHub’s hosted MCP server. You don’t need to deploy an MCP server or maintain another Azure resource. Each user signs in with their own GitHub identity, so the connector sees only the repositories that person can access.

What the plugin includes

The package contains:

• A Microsoft 365 unified app manifest using schema version 1.30
• Six Agent Skills for common GitHub workflows
• A description file for 47 GitHub MCP tools
• OAuth configuration through the Microsoft Enterprise Token Store
• A PowerShell script that validates and packages the plugin
• An OAuth test script for separating GitHub failures from Cowork configuration failures

The architecture stays small:

Copilot Cowork
    |
    |-- Agent Skills define workflows, output, and guardrails
    |
    |-- MCP connector sends JSON-RPC over HTTPS
    v
https://api.githubcopilot.com/mcp/
    |
    v
GitHub REST and GraphQL APIs

Most of my Cowork plugins use an in-tenant MCP server to keep a vendor-hosted intermediary out of the data path. GitHub is different because the remote endpoint is GitHub’s own first-party service. If your organization requires GitHub traffic to leave from an Azure subscription you control, you can self-host the open-source GitHub MCP server and change mcpServerUrl.

Six GitHub skills

Raw tools expose operations. Skills turn those operations into work someone would delegate.

The repository-search and issue-triage skills also include reference files. Search syntax and issue-field details load only when needed instead of taking space in every conversation.

Why the tool description file matters

The manifest points to tools/github-tools.json, which contains the tool names and input schemas packaged with the plugin:

"agentConnectors": [
  {
    "id": "github-mcp",
    "displayName": "GitHub",
    "toolSource": {
      "remoteMcpServer": {
        "mcpServerUrl": "https://api.githubcopilot.com/mcp/",
        "mcpToolDescription": {
          "file": "tools/github-tools.json"
        },
        "authorization": {
          "type": "OAuthPluginVault",
          "referenceId": ""
        }
      }
    }
  }
]

Cowork calls initialize and tools/list at runtime, but the packaged description file is still required for upload. Microsoft documents this requirement in Build plugins for Copilot Cowork.

Configure GitHub OAuth

GitHub’s remote MCP server doesn’t support Dynamic Client Registration. Register a GitHub OAuth App or GitHub App, then connect it to an OAuth client registration in Teams Developer Portal.

A GitHub App gives production deployments better controls, including selectable repository access and expiring user tokens. An OAuth App takes fewer steps for a first test, so the instructions below use one.

1. Register a GitHub OAuth App

Open GitHub developer settings, select OAuth Apps, and create an app with these values:

Generate a client secret and copy it when GitHub displays it.

2. Register the OAuth client

Open Teams Developer Portal, select Tools > OAuth client registration, and add this configuration:

Use My organization only while testing in one tenant. Use Any Microsoft 365 organization when preparing the plugin for broader distribution.

The two MCP URLs intentionally differ:

• The manifest uses https://api.githubcopilot.com/mcp/ with a trailing slash
• The OAuth registration uses https://api.githubcopilot.com/mcp without a trailing slash

Using a trailing slash in the OAuth registration’s Base URL can let sign-in finish and then fail the connector binding.

The repo scope is broad because issue, pull request, and merge tools need write access to private repositories. GitHub doesn’t offer a narrower OAuth App scope that preserves those operations. Review this access before distributing the plugin.

offline_access asks GitHub for an expiring access token and a refresh token. It doesn’t add repository permissions. Enable expiring user tokens on the OAuth App to use the stronger token posture.

3. Add the registration ID

Teams Developer Portal returns an OAuth client registration ID after saving. Replace `` in manifest.json with that value.

The committed package keeps the placeholder by design. It can’t authenticate until you add a registration created for your tenant and rebuild the package.

Package and upload

Run the packaging script from the plugin folder:

cd "Cowork Plugins\GitHub Cowork"
.\package.ps1

The script validates the manifest, skill folders, skill front matter, icons, tool description, and OAuth placeholder before creating the zip file.

Upload the package through Microsoft 365 admin center > Agents > Tools > Registry. Choose the test users or groups that should receive it, then enable the GitHub source in a new Cowork session. Microsoft documents the admin flow in Manage tools for agents.

Each user completes GitHub sign-in the first time a skill needs a tool. An administrator can’t authorize GitHub on someone else’s behalf.

Try these requests

Start with a read operation before testing mutations:

Find my repositories related to Model Context Protocol.

Show open issues without an assignee in troystaylor/SharingIsCaring.

Review pull request 123 and summarize any merge risks.

Draft release notes from pull requests merged since August 1.

Create an engineering report for this repository covering the last seven days.

Assign issue 42 to the GitHub Copilot coding agent.

Confirm the target repository before creating issues, commenting, merging, or delegating work. The skills include mutation guardrails, but clear repository names make the conversation safer.

Fix common connection failures

GitHub returns HTTP 200 for some token-exchange errors and puts the error in the response body. A generic connector error can therefore hide incorrect_client_credentials. The included test script prints the real response without storing or echoing the client secret.

Resources

• GitHub Cowork plugin
• SharingIsCaring repository
• GitHub MCP server
• Build plugins for Copilot Cowork
• Manage plugins for Copilot Cowork
• Configure plugin authentication

Power Platform is the gap. Copilot Studio can consume an MCP server, but only through a connector, and a naive passthrough to this one fails on the first call. Microsoft Release Communications MCP is that connector, plus REST operations for the flows and apps that can’t speak MCP at all.

Five operations, two audiences

The MCP endpoint exposes four tools: get_recent_m365_roadmaps, get_m365_roadmap_by_id, get_recent_azure_updates, and get_azure_update_by_id.

The docs name the first one get_recent_roadmaps. The live server’s tools/list says get_recent_m365_roadmaps. Write agent instructions against the live name.

Three upstream behaviors that break a passthrough

The server is spec-compliant. That’s the problem — Power Platform’s MCP handling expects a narrower shape than the spec allows. script.csx handles each one.

406 on an Accept header of application/json. Streamable HTTP requires the client to accept both content types, and the server enforces it. Every call fails until you send both:

// The MRC MCP Server returns 406 unless the caller accepts both JSON and SSE.
forward.Headers.Accept.Clear();
forward.Headers.Accept.ParseAdd("application/json");
forward.Headers.Accept.ParseAdd("text/event-stream");

Responses framed as SSE. The body comes back as event: message / data: {...} lines, which isn’t parseable JSON-RPC. The script unwraps the frames and returns the message as application/json. It scans every frame and prefers the one carrying result or error, since a single response can include progress events ahead of the real answer:

lastPayload = payload;
if (parsed["result"] != null || parsed["error"] != null)
    bestPayload = payload;

202 with an empty body on notifications. Correct per spec, and Copilot Studio reports it as an invalid JSON-RPC response. Empty successes get a valid envelope instead:

if (string.IsNullOrWhiteSpace(responseBody))
{
    if (response.IsSuccessStatusCode)
        return CreateJsonRpcSuccessResponse(requestId, new JObject());
    ...
}

Schema normalization on tools/list

The tool schemas are valid JSON Schema that Power Platform won’t take. NormalizeToolsList rewrites four things:

• Nullable union types ("type": ["integer","null"] on skip) collapse to a single scalar type
• "default": null entries are dropped
• The non-standard execution vendor key is removed from each tool object
• Non-boolean exclusiveMinimum and exclusiveMaximum values are coerced

Descriptions pass through untouched. The upstream OData filter guidance in those descriptions is what lets an agent build a working filter, so rewriting it would cost more than the schema fixes save.

If parsing fails at any point, the original content is returned rather than a broken rewrite:

catch
{
    return content;
}

The REST operations exist because MCP has a ceiling

The MCP tools cap at 50 items and truncate descriptions to fit a context window. That’s right for an agent and wrong for a flow that needs to page 1,000 Azure retirements into a table.

The MCP tools wrap a public OData v4 API on the same host. Its service container is named ReleaseCommunicationsApi — the same string the MCP server reports as serverInfo.name. The connector exposes the entity sets directly:

GET /releasecommunications/api/v2/M365?$filter=products/any(p: p eq 'Microsoft Teams')&$top=50
GET /releasecommunications/api/v2/Azure?$filter=tags/any(t: t eq 'Retirements')&$count=true
GET /releasecommunications/api/v2/Azure?$filter=availabilities/any(a: a/ring eq 'Retirement' and a/year eq 2026)

$filter, $search, $orderby, $select, $top, $skip, and $count all work, including any() lambdas over collections and the nested availabilities complex type.

Entity key access such as M365(569217) returns 404. Fetch one post with $filter=id eq 569217, or the v1 path /api/v1/m365/569217.

The OData endpoints aren’t on Microsoft Learn. They’re public, anonymous, and back the published roadmap and updates sites, but they carry no compatibility guarantee. The MCP endpoint is the documented surface — prefer it for agents and treat REST as convenience for flows.

In a flow

Enter OData expressions unescaped. The connector handles URL encoding.

Set Include Count to true and read @odata.count to size a paging loop, then step Skip by your Top value. Use Select — descriptions are full HTML and will bloat a flow run.

For change detection, run a Recurrence trigger against an RSS operation, or query with created ge using the previous run’s timestamp.

In Copilot Studio

Add the connector under Tools > Add a tool > Model Context Protocol, pick the connection, and add the tools.

The server covers two catalogs, so name the source in the prompt:

Which Microsoft Teams features on the Microsoft 365 Roadmap are releasing in June?
What is the status of Feature ID 526798 on the Microsoft 365 Roadmap?
Show all Azure retirements scheduled for this year.
Which Azure Databricks features reached general availability in February?

Roadmap and update data is the kind of thing a model will answer from memory, confidently and a year out of date. If that happens, name the tools in the agent instructions:

When the user asks about Microsoft 365 Roadmap features, Azure service updates, release
timing, or retirements, call get_recent_m365_roadmaps, get_m365_roadmap_by_id,
get_recent_azure_updates, or get_azure_update_by_id before answering.

Set include_facets to true on either list tool to discover valid filter values before filtering.

Setup

No connection parameters. No app registration.

paconn login
paconn create --api-def apiDefinition.swagger.json --api-prop apiProperties.json --script script.csx

Test InvokeMCP with an initialize payload. A successful response reports serverInfo.name as ReleaseCommunicationsApi.

The connector is anonymous by design, and the caller’s Authorization header is deliberately not forwarded to the public endpoint.

Application Insights logging is in the script and off until you replace the placeholder instrumentation key. It emits McpRequestCompleted and RequestError with the MCP method, tool name, correlation ID, status code, and duration. Telemetry failures are swallowed so they never affect a call.

If you’re not on Power Platform, skip the connector and point your client at the server:

{
  "servers": {
    "MRC-MCP-Server": {
      "type": "http",
      "url": "https://www.microsoft.com/releasecommunications/mcp"
    }
  }
}

Resources

• Source code
• Get started with the Microsoft Release Communications MCP Server
• Microsoft 365 Roadmap
• Azure Updates
• Microsoft API Terms of Use

Power Platform Admin v1.3 adds two tools for that surface. This one is in the published REST reference, which is a change from the v1.1 tenant pool tools that call an undocumented route. The v1.2 post covers agent inventory, and the original post covers the first 12 tools.

What’s new in 1.3

Two routes, two shapes

The read is entitlement-scoped and returns every environment that has a threshold. The write is environment-scoped and targets one resource.

GET  /licensing/entitlements/{entitlementId}/resourceThresholds?api-version=2024-10-01
PUT  /licensing/environments/{environmentId}/entitlements/{entitlementId}/resources/{resourceId}/threshold?api-version=2024-10-01

entitlementId is what the resource consumes — MCSMessages or MCSSessions for Copilot Studio. Those IDs predate the rename to Copilot Credits, and the API never followed it.

resourceId has no discovery route of its own, so read before you write:

What resource thresholds are set on the MCSMessages entitlement?

Both tools live on api.powerplatform.com. The tenant pool tools are the ones that need the tenant-routed host.

flowchart TD
    A[Copilot Studio agent<br/>or Power Automate flow] --> B[script.csx]
    B --> C["api.powerplatform.com<br/>environments, settings, governance, inventory, thresholds"]
    B --> D["first30hex.last2hex.tenant.api.powerplatform.com<br/>licensing allocations"]

PUT replaces the whole document

The verb is PUT and the body is the complete threshold. Send { "limit": 50000 } against a threshold that already notifies at 80% and stops over capacity, and both of those come back unset.

So the connector reads the current threshold, seeds the payload from it, and overlays only the fields you supplied:

var existing = await TryFindResourceThreshold(entitlementId, envId, resourceId);

var payload = new JObject();
if (existing != null)
{
    foreach (var field in THRESHOLD_WRITABLE_FIELDS)
    {
        var current = existing[field];
        if (current != null && current.Type != JTokenType.Null)
            payload[field] = NormalizeThresholdSeed(field, current);
    }
}

var applied = new JArray();
foreach (var field in THRESHOLD_WRITABLE_FIELDS)
{
    var supplied = arguments[field];
    if (supplied == null || supplied.Type == JTokenType.Null) continue;

    payload[field] = CoerceThresholdValue(field, supplied);
    applied.Add(field);
}

The response reports mergedWithExisting and an appliedFields array, so a flow can log what actually changed rather than what was sent.

There’s no ETag on the route. A concurrent edit from the admin center between the read and the write is still lost. Don’t run this on a fan-out loop over 40 environments while someone is in PPAC.

The read model and the write model disagree

limit comes back as number (double) on ResourceThresholdModel and goes in as integer (int32) on ResourceThresholdRequestModel. Both are documented that way. Read a threshold of 50000, echo it back untouched as part of a merge, and the service can reject 50000.0 on model binding — a failure caused entirely by preserving a value nobody asked to change.

Seeded values get rounded to int on the way back in:

private static JToken NormalizeThresholdSeed(string field, JToken value)
{
    if (field == "limit" || field == "notificationThreshold")
    {
        double number;
        if (TryReadDouble(value, out number) && number >= int.MinValue && number <= int.MaxValue)
            return (int)Math.Round(number);
    }

    return value.DeepClone();
}

resourceConsumption stays a double. It’s a double on both models.

A failed read still lets you write

TryFindResourceThreshold swallows its exception and returns null:

catch (Exception ex)
{
    // A caller that can write but not read must still be able to upsert,
    // so a failed read degrades to a create rather than failing the call.
    this.Context.Logger.LogInformation($"Could not read existing resource thresholds to merge: {ex.Message}");
    return null;
}

An admin whose role grants the write but not the entitlement-wide read would otherwise be blocked from setting a limit by a call they never asked for. The degraded path is a create, and the response says so: mergedWithExisting is false and the message notes that unspecified fields were left unset.

Read the message. It’s the difference between a limit you added to an existing threshold and one that quietly replaced it.

Validation before the round trip

notificationThreshold is a percentage. The API types it as int32 and stops there, so notificationThreshold: 8000 for “80%” is a valid int32 that means nothing.

if (field == "notificationThreshold" && number > 100)
    throw new ArgumentException("notificationThreshold is a percentage and must be between 0 and 100.");

An empty write is also rejected locally. A PUT with three path parameters and no body fields is a request to blank the document:

if (applied.Count == 0)
    throw new ArgumentException(
        "Supply at least one threshold field to set: limit, notificationThreshold, notifyIfOverCapacity, resourceConsumption, stopIfOverCapacity, or stopResource.");

In a flow

Both actions render with the same environment picker as the rest of the connector — display names at design time, no GUIDs to paste. entitlementId and resourceId are free text.

List Resource Thresholds returns entitlementId, environmentId, thresholdCount, and a thresholds array. Apply-to-each over thresholds. Passing environmentId filters the array; leaving it blank returns every environment on the entitlement.

Upsert Resource Threshold takes the three IDs on the query string and everything else in the body. Omit a property to keep its current value. Sending null is treated the same as omitting it, so a flow that builds the body from optional inputs won’t clear a field it never populated.

A weekly consumption report is the read on its own: list MCSMessages thresholds, filter to rows where resourceConsumption is past notificationThreshold percent of limit, and mail the table.

Prompts to try

What resource thresholds are set on the MCSMessages entitlement?
Which environments are closest to their Copilot Studio message limit?
Cap Copilot Studio messages at 50,000 for this environment and notify me at 80%
Stop the resource once it goes over its message limit
Show me every threshold with stopIfOverCapacity turned off

With generative orchestration enabled, the agent can chain the threshold read into admin_list_agents and answer which agents sit in the environment that’s about to blow its limit.

Permissions

No new scope. The threshold routes sit under licensing, so the Licensing.Allocations.* scopes already on the app registration plus a tenant admin role are what the connector uses. There’s no threshold-specific permission published — verify with admin_list_resource_thresholds before relying on the 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. No scopes changed.

Resources

• Source code
• Resource Threshold REST reference
• Get All Resource Thresholds
• Upsert Resource Threshold
• Manage Copilot Studio credits and capacity
• Manage Copilot credit allocations programmatically
• Permissions reference

OAuth identity provider configuration

The connector’s OAuth configuration is stored in properties.connectionParameters.token.oAuthSettings in apiProperties.json:

{
  "properties": {
    "connectionParameters": {
      "token": {
        "type": "oauthSetting",
        "oAuthSettings": {
          "identityProvider": "oauth2"
        }
      }
    }
  }
}

The identityProvider value selects the runtime OAuth implementation. Connector artifacts use identifiers including:

Use the identifier and connection parameters from a tested connector artifact or provided by Microsoft support for the target provider.

Prerequisites

• Power Platform CLI
• An authenticated PAC CLI profile
• A solution-aware custom connector
• The connector’s Dataverse row ID
• Permission to update the connector
• The provider’s OAuth client ID and client secret

pac connector commands operate on solution-aware connectors stored in Dataverse. Use paconn for a custom connector that isn’t solution-aware.

1. Authenticate and get the connector ID

Authenticate to the target environment:

pac auth create --environment "https://contoso.crm.dynamics.com"

List the solution-aware connectors:

pac connector list `
  --environment "https://contoso.crm.dynamics.com" `
  --json

2. Download the connector

Use the connector ID returned by pac connector list:

pac connector download `
  --connector-id "00000000-0000-0000-0000-000000000000" `
  --environment "https://contoso.crm.dynamics.com" `
  --outputDirectory ".\connector"

Back up the API properties file:

Copy-Item `
  -Path ".\connector\apiProperties.json" `
  -Destination ".\connector\apiProperties.backup.json"

3. Update apiProperties.json

Open connector\apiProperties.json. Find:

properties.connectionParameters.token.oAuthSettings

Change identityProvider and retain the connection parameters required by the provider. The following example configures oauth2pkce, which the designer doesn’t list:

{
  "properties": {
    "connectionParameters": {
      "token": {
        "type": "oauthSetting",
        "oAuthSettings": {
          "identityProvider": "oauth2pkce",
          "clientId": "YOUR_CLIENT_ID",
          "clientSecret": "YOUR_CLIENT_SECRET",
          "scopes": [
            "YOUR_REQUIRED_SCOPES"
          ],
          "redirectMode": "GlobalPerConnector",
          "redirectUrl": "https://global.consent.azure-apim.net/redirect/UNIQUE_IDENTIFIER_FOR_THIS_ENVIRONMENT",
          "customParameters": {
            "authorizationUrl": {
              "value": "https://api.contoso.com/oauth2/authorize"
            },
            "tokenUrl": {
              "value": "https://api.contoso.com/oauth2/token"
            },
            "refreshUrl": {
              "value": "https://api.contoso.com/oauth2/token"
            }
          },
          "properties": {
            "IsFirstParty": "False",
            "IsOnbehalfofLoginSupported": false
          }
        }
      }
    }
  }
}

The provider accepts these parameters:

clientSecret is optional, so a public client can authenticate with PKCE alone. Set clientId, authorizationUrl, tokenUrl, and refreshUrl or the connection fails validation.

The provider generates the code verifier for you. It appends code_challenge and code_challenge_method=S256 to the authorization request and sends code_verifier on the token exchange, so don’t add those values yourself. Entries in scopes are joined with a space.

Requests the provider builds:

• Authorization: client_id, response_type=code, redirect_uri, scope, state, code_challenge, code_challenge_method, idp_hint, audience
• Token: code, grant_type=authorization_code, redirect_uri, client_id, client_secret, code_verifier
• Refresh: refresh_token, grant_type=refresh_token, client_id, client_secret

Both the token and refresh requests send the client secret in the body, so the authorization server has to accept client_secret_post. A server that requires HTTP Basic client authentication won’t work with this provider.

Retain the environment-specific redirectUrl from the downloaded connector and register the same URL in the provider’s OAuth application. Store the client secret outside source control and inject it during deployment.

The provider has no token introspection, so Power Platform learns the token lifetime only from an expires_in value in the token response. If the authorization server returns an opaque token without expires_in, the connection goes stale instead of refreshing. The connection display name also comes from the unique_name claim in an OpenID token, so an opaque access token leaves the name blank.

4. Upload the updated API properties

Update only the API properties file:

pac connector update `
  --connector-id "00000000-0000-0000-0000-000000000000" `
  --environment "https://contoso.crm.dynamics.com" `
  --api-properties-file ".\connector\apiProperties.json"

If the OpenAPI definition also changed, include it in the update:

pac connector update `
  --connector-id "00000000-0000-0000-0000-000000000000" `
  --environment "https://contoso.crm.dynamics.com" `
  --api-properties-file ".\connector\apiProperties.json" `
  --api-definition-file ".\connector\apiDefinition.swagger.json"

5. Verify the identity provider

Download the connector again to a separate directory:

pac connector download `
  --connector-id "00000000-0000-0000-0000-000000000000" `
  --environment "https://contoso.crm.dynamics.com" `
  --outputDirectory ".\connector-verify"

Confirm that connector-verify\apiProperties.json contains the expected provider.

Test the connection:

1. Delete any test connection created with the old OAuth configuration
2. Create a new connection for the custom connector
3. Complete the provider’s sign-in and consent flow
4. Run a connector action
5. Test again after the access token expires to confirm refresh works

6. Roll back the update

If sign-in or refresh fails, restore the downloaded backup:

pac connector update `
  --connector-id "00000000-0000-0000-0000-000000000000" `
  --environment "https://contoso.crm.dynamics.com" `
  --api-properties-file ".\connector\apiProperties.backup.json"

Resources

• PAC CLI connector reference
• Create a custom connector with the CLI
• Microsoft Power Platform Connectors samples
• DocuSign identity provider sample
• Template-based OAuth sample
• PKCE (RFC 7636)
• Power Platform connector CLI commands reference

Makers pick the harness. Nothing tells you which one they picked. The Power Platform admin center lists agents one environment at a time and doesn’t show harness at all, so the question “which of my agents run on the expensive one” has no screen behind it.

Power Platform Admin v1.2 adds admin_list_agents, which walks the whole estate in one call. Every agent comes back with an isCLIAgent value, and that field is the harness. It also carries environment context, sharing counts, Entra identity, and a risk level you can trace back to the signals that produced it.

Yesterday’s v1.1 post covers the tenant pool tools and the dual-mode rebuild. The original post covers the first 12 tools.

What’s new in 1.2

One tool, one action:

environmentId is optional on both. Leave it blank and you get the tenant.

isCLIAgent is the harness

This is the field to read first.

Cloning both harnesses to disk shows why the field is named the way it is. A GitHub Copilot harness agent projects template: cliagent-1.0.0 and recognizer.kind: CLICopilotRecognizer, where a Standard harness agent projects default-2.1.0 and GenerativeAIRecognizer. The agents-as-code post has the full comparison.

That makes the inventory a cost report. At $0.01 per credit, an agent on the wrong harness for its workload is a four-figure annual difference at modest volume, and roughly $400,000 against $0 for an internal agent at 100,000 interactions a year. One tenant-wide read tells you where those agents are and who owns them.

Development is on top of runtime. Building, previewing, testing, and generating evaluations all consume credits on the GitHub Copilot harness, and Microsoft publishes no figure for any of them. A GitHub Copilot harness agent in a developer environment that has never been published is still spending.

Absent isn’t false

isCLIAgent is missing entirely on some agents. Coercing that to false would report an agent as Standard harness when the platform never said so, and Standard is the cheap answer — the direction you least want a governance report to guess in. The connector returns three states:

private static string TriState(JToken parent, string propertyName)
{
    var token = parent?[propertyName];
    if (token == null || token.Type == JTokenType.Null) return "unknown";
    if (token.Type == JTokenType.Boolean) return token.Value<bool>() ? "true" : "false";

    bool parsed;
    return bool.TryParse(token.ToString(), out parsed) ? (parsed ? "true" : "false") : "unknown";
}

In a flow, compare against the strings 'true', 'false', and 'unknown'. A condition that tests it as a boolean never matches. Treat 'unknown' as a row to investigate, not as Standard.

One caveat on all of it: resourcequery returns the resource provider’s raw property bag, and isCLIAgent is not in the published reference. It can change shape or disappear without notice. Use it for reporting and chargeback triage, not as a hard enforcement gate.

One query, three tables

Agents live in PowerPlatformResources under type microsoft.copilotstudio/agents. The rows carry an environmentId and nothing else about the environment, so an inventory built on that alone gives you 400 GUIDs and no way to tell production from a developer sandbox.

The connector joins the environment and environment group rows in the same query:

flowchart LR
    A["microsoft.copilotstudio/agents"] -->|leftouter on environmentId| B["microsoft.powerplatform/environments<br/>name, region, type, isManaged"]
    B -->|leftouter on environmentGroupId| C["microsoft.powerplatform/environmentgroups<br/>group name"]
    C --> D[Projected agent + risk]

Both joins are leftouter, so an agent in an environment the caller can’t read still comes back with its own properties intact rather than vanishing from the count.

One detail that costs an afternoon if you miss it: every clause is a polymorphic document and $type has to serialize first. Build the clause with $type anywhere but the first key and the service rejects the whole query.

new JObject
{
    ["$type"] = "where",
    ["FieldName"] = "type",
    ["Operator"] = "in~",
    ["Values"] = new JArray { AGENT_RESOURCE_TYPE }
}

SkipToken doesn’t page

resourcequery returns a SkipToken in its response. Send it back and you get the same rows again. Verified against the live API, it never advances.

Skip offsets work. The connector pages 1,000 rows at a time and stops at 10 pages:

if (rows.Count < AGENT_PAGE_SIZE) break;

if (pages >= AGENT_MAX_PAGES)
{
    truncated = true;
    break;
}

skip += AGENT_PAGE_SIZE;

A 10,000-agent ceiling sets truncated: true in the response rather than returning a short list that looks complete. Scope to an environment if you hit it.

Offset paging has a second failure mode that’s quieter. Sorting on createdAt alone isn’t a total order — agents provisioned from a template share a timestamp to the second — so the service is free to order ties differently between requests, and the skip window slides over rows that were never returned. The sort carries name as a unique tiebreaker:

["FieldNamesAscDesc"] = new JObject
{
    ["tostring(properties.createdAt)"] = "desc",
    ["name"] = "asc"
}

Results are also de-duplicated by resource name, so a repeated row can’t inflate the count if the service reorders anyway.

A risk score you can argue with

Every agent gets a riskLevel of None, Low, Medium, or High. A score with no explanation is a number an admin has to take on faith, so each agent also carries the riskSignals that produced it.

Thresholds are 5 for High, 3 for Medium, 1 for Low. The score floors at 0.

cliAuthoredAndTenantWide is the pairing to watch. A GitHub Copilot harness agent shared with the entire tenant is the most expensive shape available: the priciest per-task rate, multiplied by everyone in the company, with no license inclusion to absorb it.

Three of those choices are worth defending.

Editor breadth counts double, viewer breadth doesn’t. Editors can rewrite instructions and swap tools. Ten people who can change what an agent does is a bigger exposure than ten people who can talk to it.

The default environment is scored as itself, not as unmanaged. It can never be a Managed Environment. Scoring it as unmanaged would fire on nearly every agent in most tenants and flatten the distribution into noise.

if (defaultEnvironment) { score += 1; signals.Add("defaultEnvironment"); }
else if (!managedEnvironment) { score += 1; signals.Add("unmanagedEnvironment"); }

One signal subtracts. An agent that was never published has no runtime exposure, so neverPublished takes a point back. A half-built experiment in a dev environment shouldn’t outrank a published agent shared with the company.

The Entra Agent ID gap

Entra Agent IDs give each agent a directory identity that Conditional Access and access reviews can act on. Newly created agents get one; older agents don’t have one to backfill.

That makes a missing ID mean two different things, so the connector dates it:

private static readonly DateTimeOffset ENTRA_AGENT_ID_MANDATE =
    new DateTimeOffset(2026, 7, 1, 0, 0, 0, TimeSpan.Zero);

A gap on an agent created before that date is a backlog item worth +1. A gap on an agent created after it means something bypassed the path that assigns one, and scores +2.

What comes back

The response is one object, not a paged list:

{
  "agentCount": 412,
  "truncated": false,
  "environmentId": null,
  "agents": [ ... ]
}

Each agent carries display name, schema name, environment name, region, type, managed state, environment group, creator, creation date, last publish, owner, authentication mode, orchestration mode, model, quarantine state, isCLIAgent, viewer and editor counts, channels, and the risk fields.

In a flow, apply-to-each over agents and check truncated before you treat the result as the whole estate. riskSignals and channels are string arrays — join(item()?['riskSignals'], ', ') flattens them for a table or an email body.

Prompts to try

Which of my agents run on the GitHub Copilot harness?
List every agent where isCLIAgent is true, with its environment and owner
Show me GitHub Copilot harness agents shared with the entire tenant
Are there any agents where the harness came back as unknown?
Inventory every Copilot Studio agent in my tenant
Show me agents with a Medium or High risk level and explain why
Which agents are missing a Microsoft Entra Agent ID?
List the agents in my default environment and who can edit them

With generative orchestration enabled, the agent can chain the inventory into admin_get_settings or admin_get_security_recommendations to check whether the environments holding the priciest agents are governed at all.

Permissions

No new scope. resourcequery has no documented permission to grant, and it was verified to work with the delegated scopes already on the app registration plus a Power Platform admin role.

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 this time. No scopes changed.

Resources

• Source code
• Power Platform API reference
• Permissions reference
• GitHub Copilot harness billing
• Standard harness billing rates
• Introducing a new harness for Copilot Studio
• Microsoft Entra Agent ID
• Managed Environments overview

The Copilot Studio extension for VS Code clones a live agent to disk as YAML, lets you edit it, and pushes the change back. I cloned one agent on the Standard harness and one on the GitHub Copilot harness in a live tenant and edited both to find out what actually round-trips.

Three findings, in order of how much they should change your decisions:

1. The two harnesses I tested are a price class apart. Roughly an order of magnitude per interaction. Employee-facing Standard harness agents are included in Microsoft 365 Copilot licensing, and GitHub Copilot harness agents are billed for all work regardless of it, which Microsoft now states outright.
2. Microsoft’s extension documentation disagrees with the product in eight places. Two of them break your files.
3. A working setup. Instructions, a skill, two prompts, and a script that reports what your agent actually contains.

What projects to disk

The round trip is confirmed. Edit a projected file, apply, and the change reaches the live agent, including entirely new nodes with hand-written ids. Verified on the Standard harness.

What you get to edit differs by harness:

A rule-and-topic agent can be built and iterated as code for nothing until publish. A reasoning agent projects more, since its instructions and behaviors both land on disk, but every test run is billed. Testing is the inner loop of agent development, not a final step.

The harnesses are a price class apart

At $0.01 per Copilot Credit:

A light GitHub Copilot task costs 5 to 15 times a complete Standard harness multi-step run.

Those tiers are runtime figures, and development is additional. Microsoft’s “How Copilot credits are measured” section frames consumption entirely around “how often customers interact.” It contains no development term, no worked example, and no guidance on expected iteration counts. The same page states elsewhere that building, previewing, testing, and generating evaluations all consume credits, but never quantifies them, and never confirms whether a test run bills as a full task. The GA announcement repeats the point without numbers, noting that natural language authoring, evaluations, and testing all fall under usage-based billing on this harness. Budget development separately as iterations × tier cost, and measure your own iteration count, because none is published. The tiers themselves appear on that page only as an image.

Employee-facing Standard harness usage is free for Microsoft 365 Copilot licensed users. Every billable feature in the Standard harness rate table carries a “no charge” inclusion when the agent runs under the authenticated licensed user’s identity. Microsoft’s own worked example bills 100 of 150 users for exactly this reason. The GA announcement confirms the inclusion continues for the Standard and Copilot Chat harnesses, and says agents on the GitHub Copilot harness “use usage-based billing for all work, regardless of Microsoft 365 Copilot licensing.”

For an internal agent at 100,000 interactions a year:

Read the caveats on that inclusion before you plan around it. It’s business-to-employee only, subject to unstated fair-usage limits Microsoft can revise, excludes Computer-Using Agents, and for agent flows applies only to the “When an agent calls the flow” trigger. Reasoning models double-bill, feature rate plus premium AI tools at 10 credits per 1K tokens. Enforcement at 125% of prepaid capacity disables agents rather than throttling them.

Choosing

flowchart TD
    A[New agent] --> B{Complex<br/>reasoning?}
    B -->|Yes| C[GitHub Copilot harness<br/>Metered from first build action]
    B -->|No| D[Standard harness<br/>Free to iterate until publish]
    D --> E{M365 Copilot<br/>licensed?}
    E -->|Yes| F["$0 runtime"]
    E -->|No| G[Pay per credit]

Pick the GitHub Copilot harness when you genuinely need goal decomposition, native Word, Excel, or PDF generation, memory, or recovery from failed steps. Nothing else does those.

Pick the Standard harness for threshold lookups, approval routing, and structured Q&A, which is most of what agents get asked to do. Deterministic logic in a ConditionGroup can’t hallucinate a policy number, costs a fraction to run, iterates free, and is reviewable in Git.

The Copilot Chat harness is the third option, aimed at customizing Microsoft 365 Copilot Chat rather than building a standalone agent. It bills on the same fixed rate card as the Standard harness.

The harness question is really how much of this agent has to sit on the expensive one.

What you can’t currently do is edit a Standard harness agent’s generative instructions as code. Push logic into topics instead.

Telling the harnesses apart

I tested the Standard and GitHub Copilot harnesses. Copilot Chat, the third, I didn’t clone.

Microsoft’s extension documentation is banner-marked Standard harness throughout, which left open whether GitHub Copilot harness agents could be cloned at all. They can, and they project more.

A script in the pack reads .mcs/conn.json and settings.mcs.yml and reports which harness you have, what projected, and the node kinds valid for that specific agent:

.github/skills/copilot-studio-agent/scripts/Get-AgentSchema.ps1 <agent folder>

The node kinds matter most. It extracts them from the definition rather than from a list someone wrote down:

foreach ($component in $def.components) {
    foreach ($field in 'dialog', 'metadata') {
        $payload = $component[$field]
        if ($payload -isnot [string]) { continue }
        foreach ($match in [regex]::Matches($payload, '(?m)^\s*(?:-\s*)?kind:\s*([A-Za-z0-9_.]+)')) {
            [void]$nodeKinds.Add($match.Groups[1].Value)
        }
    }
}

One detail worth copying if you write your own tooling: botdefinition.json contains keys that differ only by case, id and Id. ConvertFrom-Json throws on that unless you pass -AsHashtable.

Corrections

Where the product disagrees with Microsoft Learn.

The first two are the ones that cost you time. The file structure diagram is missing the n in connection, so searching for that filename finds nothing. And the naming conventions in the same article’s best practices section tell you to use .topic.yaml and .tool.yaml suffixes, but the extension maps files to remote components by path and name. Rename a cloned file to match the guidance and the mapping breaks.

Three behaviors nobody documents:

• Projection emits custom components only. An agent of nothing but system topics produces no topics/ folder. That’s correct, not a failed clone.
• .mcs/.gitignore contains *. The definition is deliberately excluded from source control, so whatever fails to project isn’t versioned at all.
• intent: {} plus modelDescription gives behavior-style generative selection on the Standard harness.

What’s in the pack

The split is deliberate. The instructions file is short and always-on for agent definition files, carrying the handful of rules that prevent a failed apply:

---
applyTo: "**/*.mcs.yaml,**/*.mcs.yml"
description: "Hard rules for editing cloned Microsoft Copilot Studio agent definition files (.mcs.yaml / .mcs.yml) managed by the Copilot Studio VS Code extension."
---

The skill carries the full schema and folder layout and only enters context when you actually need it. Under usage-based billing, a fat always-on instruction file is a charge you pay on every turn of every session.

Two rules in the instructions file earn their place:

• Never invent a kind: value. A guessed kind fails on apply and costs a round trip. If it isn’t in the verified vocabulary, confirm it with Ctrl+Space or the Problems pane first.
• Never mix harness primitives. InlineAgentSkill belongs to the GitHub Copilot harness and AdaptiveDialog to the Standard harness. Write the wrong one and nothing invokes it.

The /cs-component prompt opens by running the schema script, so the harness is settled before anything gets written, and it holds you to the description before the body. The description is the only thing the orchestrator reads when deciding whether to invoke a component. Write it as the when, not the what. “Use when the user asks whether a purchase requires competitive bidding” fires. “Bidding logic” doesn’t.

/cs-sync walks the apply ritual in order: preview remote changes, commit local work before retrieving, resolve conflicts explicitly, check the Problems pane, summarize, then apply. The order isn’t cosmetic. Apply is blocked while remote changes are outstanding, and Get Changes overwrites uncommitted local work.

It also ends by reminding you that apply is not publish. Copilot Studio: Apply Changes updates the agent in the environment so you can test it in the test pane. End users see nothing until a separate publish.

Using it

Copy .github/ into the workspace where you cloned your agent, or clone the agent into the folder that already has it. Then:

Ctrl+Shift+P → Copilot Studio: Clone Agent

Once files are on disk, the instructions apply themselves whenever you open a .mcs.yaml. Ask for the skill by name, or start editing a topic and it gets pulled in.

Limits

Verified August 2026 against CopilotStudioSolutionVersion 2026.6.3.20581040, using two agents in a single Dataverse environment, one on the Standard harness and one on the GitHub Copilot harness. The Copilot Chat harness is untested here.

The GitHub Copilot harness reached general availability on August 3, 2026, so anything written about it before that date describes the preview. cliagent-1.0.0 is a 1.0 template and behaviors/ is undocumented, so expect both to move. The node vocabulary is per-agent, so run the script against your own rather than trusting the count above.

Resources

• Copilot Studio agents as code pack
• Introducing a new harness for Copilot Studio
• Copilot Studio extension for VS Code
• Edit agent components
• Standard harness billing rates
• GitHub Copilot harness billing
• Copilot Studio agent usage estimator

The Power Platform admin center exposes the setting one environment at a time. If you run 40 environments and one agent in a sandbox is draining shared capacity, turning it off everywhere but production means 40 trips through the UI.

Power Platform Admin v1.1 adds two tools for that setting. The same release makes the connector dual-mode, so Power Automate gets typed actions next to the MCP endpoint that Copilot Studio uses.

The original post covers the first 12 tools. This one covers what changed.

What’s new in 1.1

The two new tools

Both act on two entitlements, MCSMessages and MCSSessions, because the single toggle in the admin center covers both:

private static readonly string[] TENANT_POOL_ENTITLEMENTS =
    { "MCSMessages", "MCSSessions" };

Those IDs are older than the billing vocabulary. Microsoft renamed Copilot Studio messages to Copilot Credits in September 2025, and the current licensing guide has no message or session meter left in it—one credit pack is 25,000 Copilot Credits per month, and pay-as-you-go bills at $0.01 per credit. The entitlement IDs on the API never followed the rename, so the connector uses the names the service still answers to.

This route is unsupported

licensing/allocations isn’t in the published Power Platform REST reference. The documented licensing surface is Currency Allocation, which shares the namespace but not this route. The endpoint can change or stop working without notice.

Treat these two tools as a way to fix a org-wide capacity problem in one conversation, not as a permanent integration. Read before you write, and check the result in the admin center the first few times.

Licensing answers on a different host

Environments, settings, governance, connectors, and apps all answer at api.powerplatform.com. Licensing allocations don’t. That route is tenant-routed, and the host is built from the tenant GUID: lowercased, dashes stripped, split after the first 30 hex characters.

flowchart TD
    A[Copilot Studio agent<br/>or Power Automate flow] --> B[script.csx]
    B --> C[api.powerplatform.com<br/>environments, settings, governance, inventory]
    B --> D["first30hex.last2hex.tenant.api.powerplatform.com<br/>licensing allocations"]

Send a licensing call to the wrong host shape and you get 404 RouteNotFound.

private string ResolveTenantHost()
{
    var dashless = ResolveTenantId().Replace("-", "").ToLowerInvariant();
    if (dashless.Length != 32)
        throw new InvalidOperationException(
            "Tenant id is not 32 hex characters; cannot build the licensing host.");

    return $"{dashless.Substring(0, 30)}.{dashless.Substring(30)}{TENANT_HOST_SUFFIX}";
}

The tenant ID comes from the token, not from a connection parameter. IScriptContext has no way to read connection parameters, so the script decodes the tid claim out of the bearer token it already receives:

var segments = auth.Parameter.Split('.');
var payload = segments[1].Replace('-', '+').Replace('_', '/');
if (payload.Length % 4 == 2) payload += "==";
else if (payload.Length % 4 == 3) payload += "=";

var claims = JObject.Parse(
    Encoding.UTF8.GetString(Convert.FromBase64String(payload)));
var tid = claims["tid"]?.ToString();

Setup stays the same as v1.0. No extra field on the connection, no tenant ID to paste.

A missing document is the answer

An environment that has never had capacity allocated has no allocation document, and the API returns 404. That 404 isn’t a failure. It’s the platform saying the environment draws from the pool by default.

RouteNotFound also returns 404, so the script reads the error code in the body instead of trusting the status:

if (result.Status == HttpStatusCode.NotFound &&
    result.Body != null &&
    result.Body.IndexOf("AllocationDocumentDoesNotExist",
        StringComparison.OrdinalIgnoreCase) >= 0)
{
    return null;
}

A null document flows through to a plain answer for the agent:

No allocation document exists for this environment,
so it draws from the tenant pool by default.

Writing back without clobbering

The read and the write use different route names for the same data. GET /licensing/allocationsV2 requires a $filter on the environment and entitlements. PUT /licensing/allocations takes the whole document.

That PUT is a full upsert with no ETag. A blind write would erase any capacity allocation or enforcement rule someone else configured on the environment, and nothing would warn you. So the set tool reads first and changes only the TenantPool rule:

var rule = FindTenantPoolRule(entitlement);
if (rule == null)
    rules.Add(new JObject
    {
        ["ruleType"] = "TenantPool",
        ["enabled"] = enabled
    });
else
    rule["enabled"] = enabled;

Enforcement rules also carry Alert, PayGo, and Deny types. Rewriting one entry in the array keeps the rest intact.

Read-modify-write narrows the window, it doesn’t close it. With no ETag there’s no optimistic concurrency, so an admin editing the same environment in the admin center at the same moment can still lose a change.

Six typed actions for Power Automate

Every environmentId parameter is a picker, not a GUID field:

"x-ms-dynamic-values": {
  "operationId": "GetEnvironmentDropdown",
  "value-path": "id",
  "value-title": "name"
}

GetEnvironmentDropdown is marked x-ms-visibility: internal, so makers see environment names in a list and never see the operation that fills it.

Both surfaces call the same handlers. The typed GetTenantPoolDraw operation and the admin_get_tenant_pool_draw MCP tool both land in HandleGetTenantPoolDraw, so a flow and an agent can’t drift apart.

Permissions to add

Add two delegated permissions to the app registration from v1.0, on Power Platform API (resource ID 8578e004-a5c6-46e7-913e-12f58912df43):

• Licensing.Allocations.Read
• Licensing.Allocations.ReadWrite

The caller needs Power Platform Administrator or Global Administrator for the tenant pool tools. These are the roles that gate licensing and capacity in the admin center, and an environment-scoped System Administrator won’t clear them.

Grant admin consent for the new scopes, then delete and recreate the connection so the token carries them.

Prompts to try

Does my sandbox environment draw Copilot Studio capacity from the tenant pool?
Stop the sandbox environments from drawing from the Copilot Studio tenant pool
Turn tenant pool draw back on for [environment name]

With generative orchestration enabled, the agent chains admin_list_environments into admin_get_tenant_pool_draw to sweep every environment before you change anything.

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 before you run it. 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.

Resources

• Source code
• Power Platform API reference
• Permissions reference
• Currency Allocation, the supported licensing allocation API
• Microsoft Copilot Studio Licensing Guide, August 2026
• FAQ for Copilot Studio billing and licensing

Plenty of agent work is a plain read, though. What meetings are today, who reports to whom, every unread message from finance, when five people are free. Microsoft Graph answers those deterministically and consumes no credits doing it.

Surface area is what makes that hard. Graph has hundreds of operations, and registering them as typed tools means an agent pays for every schema in its context window before it does any work. Graph Mission Control registers three instead, and lets the model discover the rest on demand.

It’s built on the Power Mission Control Template, so the protocol and framework details live there. This post covers what’s specific to Graph.

Why three operations

The planner calls scan_graph to find what it needs, then launch_graph to run it. Operation schemas are fetched on demand, never injected up front.

Two heads, one index

The repo ships two independent deployments that compile against the same capability index.

flowchart TD
    A[graph-capability-index.json<br/>82 operations] --> B[Connector head<br/>script.csx]
    A --> C[Federated head<br/>.NET 10 MCP server]
    B --> D[Copilot Studio<br/>MCP endpoint at /mcp]
    B --> E[Power Automate<br/>ScanGraph, LaunchGraph, SequenceGraph]
    C --> F[Microsoft 365 Copilot<br/>federated connector]

The connector head is dual-mode. Copilot Studio talks to the MCP endpoint at /mcp with generative orchestration enabled, and Power Automate gets the typed ScanGraph, LaunchGraph, and SequenceGraph actions with full schemas and dynamic content. Both route through the same index and the same proxy, so behavior can’t drift between them.

The federated head is a public HTTPS MCP server. Federated connectors require one, and a Power Platform custom connector isn’t a public endpoint, so that surface needs its own deployment.

Deploy either head without the other.

The capability index

graph-capability-index.json is the source of truth: 82 Graph v1.0 operations, 50 read and 32 write.

Each entry carries a readOnly flag. The connector head ignores it—Copilot Studio and Power Automate get the full surface—but the federated head depends on it.

That flag can’t be derived from the HTTP verb. Three operations are POST and semantically reads:

POST /me/findMeetingTimes
POST /me/calendar/getSchedule
POST /search/query

A verb-based filter would drop /search/query, which is the highest-value read in the whole index.

Batching

sequence_graph maps onto the native Graph $batch endpoint rather than issuing calls one at a time, so twenty operations cost one round trip. Two constraints follow from Graph’s implementation:

• 20 requests maximum. MaxBatchSize matches it.
• Sub-request URLs must be version-relative—/me/messages, not /v1.0/me/messages. This is why DefaultApiVersion is left unset and the version lives in BaseApiUrl only. Setting both would prefix every sub-request URL and Graph would reject the batch.

A partial failure isn’t a failure. Individual requests can fail while the sequence returns 200, with per-request status and success.

Authentication on the connector head

Entra ID with on-behalf-of, so calls run as the signed-in user and Graph enforces that user’s own permissions. Graph publishes its own app registration and scopes, so you only need one app registration—the connector app.

Add the delegated Graph permissions your scenarios need and grant admin consent. Start narrow: User.Read, Mail.Read, and Calendars.Read cover most read scenarios. The aad identity provider hardcodes scope=openid in the on-behalf-of exchange and has no scopes parameter, so pre-consented delegated permissions are what actually govern access.

Two setup steps trip people up.

The per-call sign-in prompt. On the same app registration, go to Expose an API, add a scope named access_as_user, then add fe053c5f-3692-4f14-aef2-ee34fc081cae under Authorized client applications. That’s the Azure API Connections service principal. Without it, users are prompted to sign in on every call.

The redirect URI is a second pass. apiProperties.json sets redirectMode: GlobalPerConnector, which mints a URI carrying the connector’s own name and a hash of its id:

https://global.consent.azure-apim.net/redirect/new-5fgraph-20mission-20control-5f<hash>

You can’t know it until the connector exists. Deploy first, read the exact value off the connector’s Security tab, then add it to the app registration as a Web redirect URI. Until you do, every connection attempt fails with AADSTS50011. The generic https://global.consent.azure-apim.net/redirect doesn’t satisfy it, so keep both.

When a call fails, the two statuses mean different things:

Graph’s own error code and message pass through, so a 403 tells you which permission to add.

Deploy the connector head

pac auth create --environment <ENVIRONMENT_ID>

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

Pass --environment explicitly even though pac auth create already named one. Relying on the auth profile alone fails with an opaque An unexpected error occurred.

Then configure OAuth on the connector’s Security tab: identity provider Azure Active Directory, plus the client ID and secret from your app registration.

Earlier guidance said to omit apiProperties.json because PAC CLI 2.8.1 failed whenever OAuth connectionParameters were present. That’s fixed as of 2.9.3, so all three files go in one command and the two-step workaround is gone.

script.csx is compiled by the platform at deploy time, not locally, so a real pac connector create is the only validation.

The federated head

Graph Mission Control MCP/ surfaces the same operations inside Microsoft 365 Copilot as a federated connector. It ships two tools, not three, because launch can write:

Read-only by construction

Federated connectors are read-only by contract, and each tool must carry the readOnlyHint annotation. That annotation is checked at registration time and never enforced at runtime, so the server enforces it itself in two independent layers:

Both are necessary. /me/messages and /chats/{chatId}/messages each have a read and a write at the same path, distinguished only by method—the path guard allows them and the GET-only rule blocks the write. Meanwhile GET alone would happily read /servicePrincipals and /auditLogs/signIns, which the path guard rejects.

ToolRegistry.Add throws if a tool declares readOnlyHint: false, so a violation fails startup rather than a request.

Search splits by entity-type group

Graph rejects most cross-type searches with Invalid entity type combination. Only certain types may share a single /search/query request:

search_work buckets the requested sources by group, issues one search per group, and merges the hits. A failure in one bucket is reported alongside the results that succeeded.

This isn’t theoretical. The tool’s own defaults are mail, files, and events, which is an illegal combination, so every default call failed until the bucketing went in.

Discovery goes through the tools

Federated connectors expose tools only. Microsoft’s documentation describes tool availability exclusively, and MCP resources and prompts never appear for this surface. Copilot Studio does support resources, but the server owner has to configure the resource as the output of a tool, so resources are never independently browsable on any Microsoft surface.

That leaves the tools as the only discovery channel, and fifty readable operations would otherwise be reachable but invisible. So fetch_work returns the full catalog of readable paths, grouped by domain, whenever it gets a path it doesn’t recognize. A dead end becomes self-correction on the first miss. The catalog runs about 1.3 KB for 50 operations and is produced only on a miss, so it costs nothing in the tools/list payload a planner loads every session.

What it adds over Copilot on its own

These aren’t competitors on the same axis. Microsoft 365 Copilot reasons over a semantic index of your content; this server makes live, deterministic Graph reads. Where they overlap, Copilot on its own is usually better—an index plus a model beats fifty REST endpoints at summarizing, fuzzy intent, and cross-document reasoning. This server returns JSON. It doesn’t reason.

The value sits in the parts that don’t overlap. Roughly 30 of the 50 read-only capabilities have no native equivalent, because they’re configuration, structure, and computation rather than content:

Three structural differences go beyond the capability list:

• Freshness. Reads hit Graph at request time. The semantic index has ingestion lag, so “did the contract arrive yet” is answered correctly here and possibly not there.
• Determinism. $filter, $select, $orderby, $top, and @odata.nextLink paging return complete, exactly specified result sets. The index returns relevance-ranked top-N. “All 47 unread messages from finance, oldest first” is a query, not a search.
• Auditability. Every call lands in Application Insights with its exact Graph path and result code, so “did it actually run” is answerable. With native grounding it isn’t, which is why a connector that’s merely not selected looks identical to one that’s broken.

The honest counterweight: Copilot on its own needs no Entra app, no on-behalf-of chain, no container, and no per-user connection step. Inside the overlap this is more moving parts for a worse answer. The case rests on the non-overlapping capabilities, the freshness and determinism properties, and the fact that the same index drives the Power Automate connector, where none of Copilot’s grounding exists at all.

Deploy the federated head

azd env new <ENV_NAME> --location <REGION> --subscription <SUBSCRIPTION_ID>
azd env set ENTRA_TENANT_ID <TENANT_ID>
azd env set ENTRA_CLIENT_ID <SERVER_APP_CLIENT_ID>
azd up

azd up provisions a Container App, registry, log workspace, Application Insights, and a user-assigned identity, then builds and pushes the image. Five billable resources, two of which bill whether or not anyone uses the server. minReplicas: 1 is deliberate, because a cold start would land inside Copilot’s request timeout. Set it to 0 in infra/resources.bicep if you’d rather pay less than answer promptly, and run azd down when you’re finished evaluating.

There’s no client secret. The server authenticates to Entra with workload identity federation, using the same user-assigned identity that pulls the image, which needs a federated credential on the server app registration:

Entra accepts a federated credential with a wrong issuer, subject, or audience without any error, then fails later at token exchange. Verify it by making a real call, never by the credential saving successfully.

Registration then runs through three portals:

1. Teams Developer Portal → Tools → Microsoft Entra SSO client ID registration. Supply the server app’s client ID, base URL, and scope. The scope must be fully qualified—api://<Application ID URI>/mcp.access, not the bare mcp.access. A bare scope name has no resource attached, so Entra resolves it against Microsoft Graph and consent fails with AADSTS650053.
2. On the server app registration, add the returned Application ID URI to identifierUris, add https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect as a Web redirect URI, and pre-authorize ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b, the Microsoft Enterprise token store. Then azd env set ENTRA_EXTRA_AUDIENCES "<Application ID URI>" and redeploy, because Copilot’s token carries that audience rather than the app’s own api:// URI.
3. Microsoft 365 admin center → Copilot → Connectors → Gallery → Created by your org → Connect to MCP server. Supply the display name, base URL, and SSO registration ID. Display name caps at 30 characters, which is undocumented and the only field on the form short enough to hit it.

Each user then connects the server themselves in Copilot Chat → Settings → Sources. Admin rollout only makes the connector available. Until a user creates the connection, prompts are answered from Copilot’s native M365 data and the connector is never consulted, which looks like a broken connector but is just an unconnected one. Changes take up to 15 minutes to take effect, so an immediate failure isn’t meaningful.

Every user who queries the federated head needs a Microsoft 365 Copilot license. It’s a flat per-user add-on rather than a per-call meter, so query volume costs nothing extra, but a tenant without it can’t use this head at all. Check that first.

Check the billing terms too, before you plan around a flat cost. Microsoft now meters several Copilot services with Copilot Credits, and a Copilot license doesn’t always cover what a custom agent does. The Work IQ API bills on usage even for licensed users when a custom or third-party agent calls it.

Behavior worth knowing

• Pagination. launch_graph surfaces @odata.nextLink as nextLink. Pass it back as the endpoint to page forward. fetch_work accepts a continuation in path and passes it through untouched, since re-applying $top or $select would corrupt it.
• Absolute URLs. Only https://graph.microsoft.com/v1.0/... is accepted. Following an arbitrary absolute URL would turn the tool into an open proxy for whatever host the caller names.
• Throttling. Transient responses (429, 503, 504) are retried up to three times, honoring Retry-After when it’s short enough to be worth waiting for. A longer Retry-After surfaces as an error instead.
• Directory search. Graph rejects $search and $count on /users and /groups unless the request carries ConsistencyLevel: eventual, and $search also requires $count=true. Both are added automatically.
• Response size. Mail bodies and Teams messages are HTML and can be very large. Summarization strips markup and truncates at 500 characters for bodies, 1000 for text. Set SummarizeResponses = false to disable.
• Default page size. Graph defaults to 10 and allows up to 999. The connector injects $top=25 on collection reads when no page size is given.

Going past 82 operations

The connector runs DiscoveryMode.Static against the embedded index. Graph has no per-resource describe endpoint—$metadata is one monolithic CSDL document—so Hybrid has nothing to call.

To reach the rest of Graph, switch to McpChain against MS Learn, at the cost of an external call on every scan:

DiscoveryMode = DiscoveryMode.McpChain,
McpChainEndpoint = "https://learn.microsoft.com/api/mcp",
McpChainToolName = "microsoft_docs_search",
McpChainQueryPrefix = "Microsoft Graph",

The modes are exclusive rather than additive—McpChain replaces index search instead of supplementing it.

To add operations to the static index instead, edit graph-capability-index.json and re-embed it into script.csx. The CAPABILITY_INDEX constant is a C# verbatim string, so every " becomes "". Do that mechanically:

$json = Get-Content .\graph-capability-index.json -Raw
$escaped = $json.TrimEnd() -replace '"', '""'

Both heads and the full readme are in my SharingIsCaring repository.

The template now runs on MCP 2026-07-28, and mission control is the one connector where that revision matters twice. In McpChain discovery mode it’s both an MCP server and an MCP client, so it has to negotiate protocol eras coming in and going out.

I covered the pattern itself in the original Power Mission Control post, and the protocol changes in the Power MCP Template update. This covers what mission control adds on top.

Serving both eras

As a server, mission control behaves like the base template. A request carrying a _meta protocol version, an MCP-Protocol-Version header, or a call to server/discover is served modern. Everything else, Copilot Studio included, is served exactly as before.

The three tools are stable by design, which makes them worth caching:

ProtocolVersion = "2026-07-28",
SupportedProtocolVersions = new List<string> { "2026-07-28", "2025-11-25", "2025-06-18" },

ListCacheTtlMs = 900000,   // 15 min — the three tools are stable
ListCacheScope = "public",
DiscoverCacheTtlMs = 3600000,

Instructions = "Call scan_{service} first to find the operation you need, then launch_{service} to execute it."

Fill in Instructions. server/discover returns it, and it’s the one place you can tell the model how to drive three generic tools before it has called anything. Without it, the planner has to infer the scan-then-launch sequence from tool descriptions alone.

The capability catalog is also deterministically ordered now, so a client can hold it across reconnects rather than re-fetching.

Calling out as a client

McpChain mode routes a scan query to an external MCP server and parses the documentation results. That external server has its own protocol era, and the connector has to figure out which one.

McpChainClient tries the modern path first:

sequenceDiagram
    participant MC as Mission Control
    participant Up as Upstream MCP server

    MC->>Up: tools/call with _meta protocol version
    alt Modern upstream
        Up-->>MC: result
        Note over MC: One round trip. Era cached.
    else Legacy upstream
        Up-->>MC: 4xx
        MC->>Up: initialize
        Up-->>MC: capabilities
        MC->>Up: notifications/initialized
        MC->>Up: tools/call
        Up-->>MC: result
        Note over MC: Era cached, handshake paid once.
    end

Two things fall out of this.

The happy path drops from three HTTP round trips to one, inside a code path that already needed a cache because it was slow. And the era is cached per endpoint, so the probe is paid once rather than on every scan.

The fallback logic reads the error rather than the status alone. A recognized modern error—-32020, -32021, or -32022—means the upstream is modern and refused that specific request, so the client doesn’t fall back and retry as legacy. Any other 4xx identifies a legacy server.

This mattered immediately. The documented default McpChainEndpoint is MS Learn MCP, and Microsoft shipped 2026-07-28 support on day zero. Under the old client code, a modern upstream would have broken McpChain discovery outright.

Confirming a destructive launch

launch and sequence execute whatever endpoint and method the planner hands them, including DELETE. Multi Round-Trip Requests let a stateless connector ask before acting:

handler.AddTool("launch_guarded", "Launch an operation, confirming destructive methods first.",
    schema: s => s
        .String("endpoint", "API endpoint path", required: true)
        .String("method", "HTTP method", required: true),
    handler: async (args, ct) =>
    {
        var method = args.Value<string>("method");
        if (method == "DELETE")
        {
            return McpRequestHandler.InputRequired(
                new JObject
                {
                    ["confirm"] = McpRequestHandler.ElicitationRequest(
                        $"Confirm {method} on {args.Value<string>("endpoint")}?",
                        s => s.Boolean("proceed", "Confirm", required: true))
                },
                requestState: args.Value<string>("endpoint"));
        }
        // Execute
    });

Legacy clients can’t parse input_required, so the framework degrades it to a tool error naming the confirmation they can’t supply. Nothing executes unconfirmed either way.

Mission control or typed tools

The readme’s comparison table used to read like a version history—v2 versus v3. Both patterns ship on the same framework, so the comparison is now between two approaches you choose per connector.

Typed tools win for a small fixed set of operations, or where each one needs unique logic that doesn’t fit a generic proxy. Mission control wins past roughly ten operations, or when the API will keep growing—adding an operation means adding an index entry, not writing code.

You can mix them. AddTool(), AddResource(), AddResourceTemplate(), AddPrompt(), and AddSkill() all work alongside mission control mode, so high-value operations can be exposed directly while the generic tools cover the rest.

AddSkill() is a good fit here. Publishing a skill that documents how to drive scan, launch, and sequence gives Microsoft Agent Framework agents the same guidance Instructions gives the Copilot Studio planner.

Also in this revision

• Mcp-Method and Mcp-Name headers are sent on outbound calls and validated on inbound ones, with HeaderMismatch (-32020) when a header disagrees with the body
• Error codes -32020, -32021, and -32022; resource-not-found moved from -32002 to -32602
• ResourceLinkContent, and structuredContent now accepts any JSON value
• The schema builder is hardened against the four documented Copilot Studio schema defects, including $ref silently dropping a tool from tools/list
• AddTool declared schemaConfig and annotationsConfig while every call site used schema: and annotations:. The parameters now match the call sites.

Getting started

Set ServiceName and BaseApiUrl in MissionControlOptions, pick a discovery mode, then build the capability index with the companion generate-capability-index.prompt.md—paste your API documentation, and Copilot generates the JSON array to drop into CAPABILITY_INDEX.

private static readonly MissionControlOptions McOptions = new MissionControlOptions
{
    ServiceName = "salesforce",
    BaseApiUrl = "https://your-instance.salesforce.com/services/data/v66.0",
    DiscoveryMode = DiscoveryMode.Static,
    MaxDiscoverResults = 3,
};

Deploy as a custom connector and add it to an agent with generative orchestration enabled.

The full template is in my SharingIsCaring repository.

MCP 2026-07-28 removed the initialize handshake, deleted the Mcp-Session-Id header, and made the protocol stateless. Every request now carries its own protocol version, client identity, and capabilities in _meta. A custom connector is a stateless request-in, response-out function, so the runtime and the protocol finally agree on the same execution model.

The template ships as script.csx, apiDefinition.swagger.json, apiProperties.json, a copilot-instructions.md for agents editing the code, and a readme. You write tools, resources, prompts, and skills; the built-in McpRequestHandler handles the protocol.

What the protocol change fixed

Two things stay out of reach, both because a connector can’t hold a stream open: the subscriptions/listen notification stream, and the io.modelcontextprotocol/tasks extension.

Dual-era serving

Copilot Studio is still a legacy client. It opens with initialize and knows nothing about _meta, server/discover, or resultType. The spec permits one server to answer both eras on a single endpoint, so the template does.

The era is decided per request:

Modern-only fields—resultType, ttlMs, cacheScope, and _meta.serverInfo—never appear in a legacy response. That’s what makes the upgrade safe to deploy against a Copilot Studio agent that’s already running.

Configuring the server

McpServerOptions at the top of the script drives server/discover, the legacy initialize, and the cache hints:

private static readonly McpServerOptions Options = new McpServerOptions
{
    ServerInfo = new McpServerInfo
    {
        Name = "power-mcp-server",
        Version = "1.0.0",
        Title = "Power MCP Server",
        Description = "Power Platform custom connector implementing Model Context Protocol"
    },

    ProtocolVersion = "2026-07-28",
    SupportedProtocolVersions = new List<string> { "2026-07-28", "2025-11-25", "2025-06-18" },

    Capabilities = new McpCapabilities
    {
        Tools = true,
        Resources = true,
        Prompts = true,
        Completions = true
    },

    ListCacheTtlMs = 300000,
    ListCacheScope = "public",
    ResourceCacheTtlMs = 60000,
    ResourceCacheScope = "private",
    DiscoverCacheTtlMs = 3600000,

    Instructions = ""
};

Drop a revision from SupportedProtocolVersions and the server returns UnsupportedProtocolVersionError (-32022) with the list it does support, so the client can retry.

server/discover is mandatory for servers on 2026-07-28, and the framework generates it from these options. There’s nothing to implement.

Cache scope is a security decision

2026-07-28 requires cache hints on every complete result from server/discover, the four list methods, and resources/read. The framework attaches them; you choose the values.

public permits a shared gateway to serve one caller’s cached response to another. Use private whenever the result depends on who’s asking, which is why resources/read defaults to it. Tool and prompt lists default to public because they’re normally identical for everyone. If your tools/list varies by the caller’s granted scopes, change ListCacheScope to private.

Tool ordering is deterministic (registration order), which is what makes list caching and upstream prompt caching worth anything.

Multi Round-Trip Requests

MRTR is how 2026-07-28 replaced server-initiated elicitation/create, sampling/createMessage, and roots/list. Rather than pushing a request down an open stream, the server returns resultType: "input_required" and the client retries the original call with the answers attached.

That inversion is what makes elicitation possible from a connector. There’s no stream to hold open and no session to keep, just two ordinary request and response exchanges.

sequenceDiagram
    participant Client as MCP client
    participant Conn as Connector

    Client->>Conn: tools/call delete_records { filter }
    Conn-->>Client: input_required + elicitation + requestState
    Note over Client: Asks the user to confirm
    Client->>Conn: tools/call delete_records { inputResponses, requestState }
    Conn-->>Client: complete

Ask for the confirmation and stash what you need to resume:

handler.AddTool("delete_records", "Permanently delete matching records.",
    schema: s => s.String("filter", "Records to delete", required: true),
    handler: async (args, ct) =>
    {
        var filter = args.Value<string>("filter");

        return McpRequestHandler.InputRequired(
            new JObject
            {
                ["confirm"] = McpRequestHandler.ElicitationRequest(
                    $"Permanently delete all records matching '{filter}'?",
                    s => s.Boolean("proceed", "Confirm deletion", required: true))
            },
            requestState: filter);
    });

On the retry, inputResponses and requestState arrive on the request context. Because the server holds nothing between the two calls, anything you need to resume has to go in requestState. Treat it as opaque to the client, and keep secrets out of it—it round-trips through the caller.

Legacy clients can’t interpret resultType. Instead of emitting a shape Copilot Studio would fail to parse, the framework converts an input_required into a tool error naming the missing input, so the model asks for it as a normal argument. One code path, sensible degradation.

Agent Skills over MCP

An Agent Skill is a portable package of instructions and resources that an agent loads on demand. AddSkill() publishes one over MCP, so a connector becomes a distribution point for skills that Microsoft Agent Framework agents and Microsoft Foundry Toolbox pull at runtime. This adds no protocol surface—skills are ordinary MCP resources under the skill:// scheme.

handler.AddSkill("expense-report",
    "File and validate employee expense reports according to company policy. " +
    "Use when asked about expense submissions, reimbursement rules, or spending limits.",
    instructions: @"1. Read the `policy-limits` resource for current per-category caps.
2. Validate each line item against those caps.
3. Flag any item that exceeds a cap and state which rule it breaks.",
    resources: r => r
        .Resource("references/policy-limits.md", "Per-category spending caps.", () => limitsMarkdown),
    license: "Apache-2.0");

That one call generates skill://index.json, skill://expense-report/SKILL.md, and a resource per sibling file. Every naming and length constraint is checked at registration, so a malformed skill throws when the connector loads instead of failing quietly at discovery time.

Because the skill lives on the server, editing the instructions updates every connected agent without redeploying any of them.

The schema builder stays narrower than the spec

2026-07-28 loosened inputSchema and outputSchema to allow any JSON Schema 2020-12 keyword, including $ref and $defs. McpSchemaBuilder doesn’t use them, and neither should a schema you hand-write.

The reason is Copilot Studio. Its documented MCP limitations include four schema behaviors that are easy to trip over:

A dropped tool produces no error anywhere. It simply never appears. The builder inlines nested objects rather than referencing them and never emits a multi-type array. If you add numeric bounds, use the draft-04 boolean form of exclusiveMinimum.

New error codes

2026-07-28 partitioned the JSON-RPC implementation-defined range. -32000 to -32019 is legacy and frozen; -32020 to -32099 belongs to the specification.

Resource-not-found also moved from -32002 to -32602.

Methods removed in this revision

A modern caller that invokes initialize, notifications/initialized, notifications/roots/list_changed, ping, logging/setLevel, resources/subscribe, or resources/unsubscribe gets MethodNotFound. A legacy caller gets the same behavior it always did. Don’t delete the legacy branch—Copilot Studio depends on it.

Wiring it up

ExecuteAsync now passes the request through so the framework can read the transport headers:

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    var handler = new McpRequestHandler(Options);
    RegisterCapabilities(handler);

    var body = await this.Context.Request.Content.ReadAsStringAsync().ConfigureAwait(false);
    var result = await handler.HandleAsync(
        body,
        McpTransportHeaders.FromRequest(this.Context.Request),
        this.CancellationToken).ConfigureAwait(false);

    return new HttpResponseMessage(HttpStatusCode.OK)
    {
        Content = new StringContent(result, Encoding.UTF8, "application/json")
    };
}

The connector files ship ready to deploy once you set host. The Swagger is a single POST with basePath of /mcp and the operation at /, carrying x-ms-agentic-protocol: mcp-streamable-1.0. That operation must have no parameters key at all, not even an empty array—Power Platform injects its own body parameter and a declared one collides with it.

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

Upgrading from v2

The script sections swapped order. Section 1 is now the connector entry point—server options, RegisterCapabilities, ExecuteAsync, and optional Application Insights logging. Section 2 is the framework, which you leave alone unless you’re extending it.

One breaking rename came with the revision: AddTool declared schemaConfig and annotationsConfig, while every call site and both doc files used schema: and annotations:. The parameters are now named schema and annotations, matching what everything already called them.

If you’re new to the template, start with the original Power MCP post for the architecture, then v2 for the fluent registration API.

The full template is in my SharingIsCaring repository.

You can find the complete code in my SharingIsCaring repository.

What it does

The connector wraps getMicrosoft365CopilotUsageUserDetail(period, version). It returns per-user last-activity dates across Teams, Word, Excel, PowerPoint, Outlook, OneNote, Loop, and Copilot Chat, plus prompt counts and agent activity in version 2. Ask for a period, pick a version and format, and the connector returns the report.

JSON comes from the beta Copilot reports namespace; CSV comes from the v1.0 endpoint. The connector routes each request to the right one based on the format you choose.

Operations

Parameters

• Period — the number of previous days to aggregate. v1 supports D7, D30, D90, D180, ALL; v2 supports D7, D28, D90, D180, ALL.
• Version — v1 or v2 (default). v2 adds prompt counts (all apps, Copilot Chat work and web), active usage days, and last-activity dates for Microsoft 365 Copilot, Edge, and Copilot Agent.
• Format — json (default) or csv.

Example

Get the last 7 days as JSON (v2):

Request: period = D7, version = v2, format = json

Response (abridged):

{
  "value": [
    {
      "reportRefreshDate": "2026-07-23",
      "userPrincipalName": "avery@zava.com",
      "displayName": "Avery Howard",
      "lastActivityDate": "2026-07-22",
      "copilotChatLastActivityDate": "2026-07-22",
      "microsoftTeamsCopilotLastActivityDate": "2026-07-21",
      "wordCopilotLastActivityDate": "2026-07-20",
      "copilotActivityUserDetailsByPeriod": [ { "reportPeriod": 7 } ]
    }
  ]
}

With version=v2 (the default), the response carries extra data beyond the named outputs—prompt counts and active usage days inside each copilotActivityUserDetailsByPeriod entry, and additional last-activity dates at the top level. These pass through in the JSON; Graph doesn’t publish the exact property names, so they aren’t declared as named outputs.

Data flow

sequenceDiagram
    participant Client as Copilot Studio / Power Automate
    participant Conn as Connector
    participant Graph as Microsoft Graph
    participant Data as Usage Reporting

    Client->>Conn: Get Usage Report { period, version, format }
    alt format = json (default)
        Conn->>Graph: GET /beta/copilot/reports/getMicrosoft365CopilotUsageUserDetail(period, version)
        Graph-->>Conn: 200 JSON { value: [ per-user detail ] }
    else format = csv
        Conn->>Graph: GET /v1.0/copilot/reports/getMicrosoft365CopilotUsageUserDetail(period, version)
        Graph-->>Conn: 200 CSV stream
    end
    Conn-->>Client: Report (JSON or CSV)

    Note over Client,Data: Delegated Reports.Read.All + a supported admin role

Prerequisites

• A Microsoft Entra ID app registration. This connector uses the generic aad identity provider with your own client ID and secret.
• The signing-in user must hold a supported admin role—for example Reports Reader, Usage Summary Reports Reader, AI Administrator, or Global Reader.

Set up credentials

The connector uses OAuth 2.0 (authorization code) with Microsoft Entra ID and the Reports.Read.All delegated permission:

1. In the Microsoft Entra admin center, register a new application.
2. Add a Web redirect URI: https://global.consent.azure-apim.net/redirect.
3. Under API permissions, add the delegated Microsoft Graph permission Reports.Read.All and grant admin consent.
4. Under Certificates & secrets, create a client secret. Record the Application (client) ID and secret value.
5. Set the client ID in apiProperties.json (clientId) and provide the client secret on the connector’s Security tab after deployment.

Deploy with PAC CLI

A known PAC CLI issue blocks OAuth connectionParameters on create, so deploy in two steps and configure OAuth in the portal:

# 1. Create the connector with the definition, properties, and script
pac connector create `
  --api-definition-file "apiDefinition.swagger.json" `
  --api-properties-file "apiProperties.json" `
  --script-file "script.csx"

# 2. In the Power Platform portal, open the connector's Security tab and set:
#    - Client ID and Client secret from your app registration
#    - Confirm the redirect URL matches https://global.consent.azure-apim.net/redirect

Telemetry

script.csx includes an Application Insights hook (LogToAppInsights) that emits events for requests, Graph calls, MCP tool calls, and errors. It’s disabled by default—the instrumentation key is a placeholder, and telemetry is skipped until you set a real key. Replace the APP_INSIGHTS_KEY constant to turn it on. Telemetry failures are swallowed and never block an operation.

Limitations

• JSON comes from the beta namespace — the v1.0 Copilot reports endpoint returns CSV, so this connector routes JSON requests to /beta/copilot/reports/.... APIs under /beta are subject to change.
• Licensed users only — the report returns usage for users with a Microsoft 365 Copilot license. Unlicensed Copilot Chat usage isn’t available here (check the admin center Copilot Chat Usage report or Purview audit logs).
• Admin role required — the signed-in user must hold a supported reports or admin role, not just the app permission.
• Data anonymization — usage report data may be anonymized depending on the tenant’s admin center reports privacy setting.

References

• copilotReportRoot: getMicrosoft365CopilotUsageUserDetail
• Microsoft 365 Copilot usage report (admin center)
• Authorization for APIs to read Microsoft 365 usage reports

Full source is in the SharingIsCaring repository.

#PowerPlatform #CopilotStudio #MCP #CustomConnectors #Reporting #GraphAPI

You can find the complete code in my SharingIsCaring repository.

App-only authentication

This connector is different from the Copilot Chat and Copilot Search connectors, which sign in as the user. The Export API supports application (app-only) permissions only. The connection authenticates as the app itself through the client credentials flow—no user signs in. Plan your app registration and connection around that.

What it does

The connector wraps the Microsoft Graph v1.0 getAllEnterpriseInteractions API. Pass a user ID and it returns that user’s Copilot interactions—prompts, responses, the app each one came from, accessed resources, and timestamps—so you can feed the data into compliance workflows, audit logs, or analytics.

Operations

Parameters

• User ID — the object ID or user principal name of the user whose interactions to export.
• Top — the number of interactions to return. 100 is a good value for performance.
• Filter — an OData filter, for example appClass eq 'IPM.SkypeTeams.Message.Copilot.BizChat'.

MCP tools for Copilot Studio

Invoke MCP is the Model Context Protocol endpoint. A Copilot Studio agent pointed at it gets two tools:

• get_user_interactions — all interactions for a user
• get_user_interactions_by_app — interactions filtered to a specific app class

The by-app tool saves the agent from writing the OData filter by hand when someone asks for, say, just their Teams Copilot activity.

Example

Get a user’s BizChat interactions:

Request: userId = 4db02e4b-d144-400e-b194-53253a34c5be, $filter = appClass eq 'IPM.SkypeTeams.Message.Copilot.BizChat'

Response (abridged):

{
  "value": [
    {
      "id": "1732148357313",
      "sessionId": "19:YzBP1kUdkNjFtJnketPYT8kQdQ3A08Y51rDTxE_ENIk1@thread.v2",
      "appClass": "IPM.SkypeTeams.Message.Copilot.BizChat",
      "interactionType": "aiResponse",
      "conversationType": "bizchat",
      "createdDateTime": "2024-11-21T00:19:17.313Z",
      "locale": "en-us",
      "body": { "contentType": "html", "content": "<attachment id=\"4062...\"></attachment>" },
      "from": { "application": { "displayName": "Microsoft 365 Chat", "applicationIdentityType": "bot" } }
    }
  ]
}

Data flow

sequenceDiagram
    participant Client as Copilot Studio / Power Automate
    participant Conn as Connector
    participant AAD as Microsoft Entra ID
    participant Graph as Microsoft Graph (v1.0)
    participant Hist as Interaction History

    Note over Conn,AAD: App-only (client credentials) — no user sign-in
    Conn->>AAD: Token request (client_credentials, resource=Graph)
    AAD-->>Conn: App access token
    Client->>Conn: Get User Interactions { userId, top, filter }
    Conn->>Graph: GET /v1.0/copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions?$top&$filter
    Graph->>Hist: Read interaction history
    Hist-->>Graph: aiInteraction[]
    Graph-->>Conn: 200 { value: [ { id, appClass, body, from, ... } ] }
    Conn-->>Client: Interaction collection

    Note over Client,Hist: Requires AiEnterpriseInteraction.Read.All + Copilot license

Prerequisites

• A Microsoft Entra ID app registration with the AiEnterpriseInteraction.Read.All application permission and admin consent granted.
• Users whose interactions you export must have a valid Microsoft 365 Copilot license with the Microsoft Copilot with Graph-grounded chat service plan.

Set up credentials

The connector authenticates as the application through the client credentials flow:

1. In the Microsoft Entra admin center, register a new application.
2. Under API permissions, add the Application permission Microsoft Graph → AiEnterpriseInteraction.Read.All, then grant admin consent.
3. Under Certificates & secrets, create a client secret. Record the Application (client) ID, secret value, and your Directory (tenant) ID.
4. Set the client ID in apiProperties.json (clientId) and your tenant ID in apiProperties.json (customParameters.tenantId). A concrete tenant is required—the client credentials flow can’t use common.
5. On the connector’s Security tab after deployment, provide the client secret. The connection acquires an app-only token, so no user signs in.

Deploy with PAC CLI

A known PAC CLI issue blocks OAuth connectionParameters on create, so deploy in two steps and configure OAuth in the portal:

# 1. Create the connector with the definition, properties, and script
pac connector create `
  --api-definition-file "apiDefinition.swagger.json" `
  --api-properties-file "apiProperties.json" `
  --script-file "script.csx"

# 2. In the Power Platform portal, open the connector's Security tab and set:
#    - Client ID and Client secret from your app registration
#    (Grant type = client_credentials and the tenant ID are already set in apiProperties.json)

Telemetry

script.csx includes an Application Insights hook (LogToAppInsights) that emits events for requests, Graph calls, MCP tool calls, and errors. It’s disabled by default—the instrumentation key is a placeholder, and telemetry is skipped until you set a real key. Replace the APP_INSIGHTS_KEY constant to turn it on. Telemetry failures are swallowed and never block an operation.

Limitations

• Application permission only — delegated (user) sign-in isn’t supported by this API.
• Copilot license required — only interactions for users with a Microsoft 365 Copilot license are returned.
• No delta — the delta function isn’t supported; use $top paging (@odata.nextLink) to retrieve large histories.
• Copilot Studio agents excluded — interactions inside agents created by Copilot Studio aren’t returned.

References

• AI Interaction Export API overview
• aiInteractionHistory: getAllEnterpriseInteractions
• Export content with the Microsoft Teams export APIs

Full source is in the SharingIsCaring repository.

#PowerPlatform #CopilotStudio #MCP #CustomConnectors #Compliance #GraphAPI

GraphQL Bridge is a reusable script.csx template that reconciles all three. Callers send flat JSON, the script builds the GraphQL envelope, posts it, and returns clean JSON. No GraphQL knowledge is needed in the connector operations, Power Automate, or Copilot Studio.

You can find the complete code in my SharingIsCaring repository.

Why this is needed

Three mismatches between GraphQL and Power Platform’s Swagger model drive the whole script:

How it works

The bridge chooses one of two modes per OperationId.

Mode A — server-defined document (recommended)

Register the GraphQL document in GraphQlDocuments, keyed by OperationId. The connector body passes straight through as GraphQL variables, so the operation looks like a normal typed REST call:

private static readonly Dictionary<string, string> GraphQlDocuments =
    new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
    ["GetAssetById"] = @"query GetAssetById($id: ID!) {
        asset(id: $id) { id title status createdAt }
    }",
};

// Optional: return exactly the nested object the Swagger schema expects
private static readonly Dictionary<string, string> ResponseRootPaths =
    new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{
    ["GetAssetById"] = "asset",   // returns data.asset instead of the whole data object
};

The caller sends a flat body:

{ "id": "abc123" }

The script wraps it as variables, posts the registered document, and returns data.asset. The maker never sees GraphQL.

Mode B — passthrough

If no document is registered for the OperationId, the body must carry the query itself. Wire this to a generic RunQuery operation for ad-hoc queries:

{
  "query": "query ($id: ID!) { asset(id: $id) { id title } }",
  "variables": { "id": "abc123" }
}

Reserved body keys (query, variables, operationName) are always honored. In Mode A, everything else in the body becomes variables.

Configuration

Four settings control the bridge, all at the top of script.csx:

Auth is untouched. The incoming request already carries the connector’s Authorization header. The script only changes the method, URI path, and content, so credentials flow through automatically.

Error shapes returned

The bridge turns silent GraphQL failures into real HTTP errors your flows can catch:

• Invalid request JSON returns 400 INVALID_JSON
• No query available returns 400 NO_QUERY
• A GraphQL errors array returns 400 GRAPHQL_ERROR, with errors and any partialData
• A non-2xx from the GraphQL server returns the original status, wrapped as HTTP_<code>
• A non-JSON GraphQL response returns 502 INVALID_GRAPHQL_RESPONSE

Using it for a real API

Most GraphQL APIs expose a single endpoint and use a bearer token:

• Host: the API’s host, such as api.example.com
• Path: /graphql (the default GraphQlPath; change it if the API differs)
• Auth: OAuth 2.0 or an API or personal access token, configured as the connector’s security definition

Steps to adapt it:

1. Point the connector host at the API and set GraphQlPath to its GraphQL endpoint path.
2. Add one entry to GraphQlDocuments per typed operation you want to expose, for queries and mutations.
3. Optionally set ResponseRootPaths so each operation returns the exact nested object.
4. Add a generic RunQuery operation for anything not yet modeled (Mode B).

Because the bridge exposes schema-shaped typed operations rather than a raw passthrough, pair each build with full Swagger response schemas so you keep IntelliSense and dynamic value support in Power Automate.

For per-tenant hosts, where the GraphQL host varies per customer (for example, {tenant}.example.com), Power Platform’s Swagger host is static. Bake the host as a replaceable constant in the script and set the request URI there instead of relying on GraphQlPath alone.

Conventions

• Uses this.Context.SendAsync(...), never new HttpClient(), which the runtime blocks
• Fully qualifies Newtonsoft.Json.Formatting to avoid the System.Xml ambiguity
• Requires no connection parameters; the endpoint path is a compile-time constant

Resources

• Template repo: SharingIsCaring/Connector-Code/GraphQL Bridge
• GraphQL specification: spec.graphql.org
• Custom connector C# code reference: Write code in a custom connector

You can find the complete code in my SharingIsCaring repository.

What it does

The MCP connector wraps the Microsoft Graph v1.0 Search API (POST /v1.0/search/query). Send a query and the entity types you want, and Graph returns ranked hits with summaries and resource links. Permissions are evaluated per item, so users only see content they already have access to.

Searchable content includes:

• Files in OneDrive and SharePoint
• Email
• Teams messages
• Calendar events
• SharePoint sites and lists
• People
• Copilot connector (external) items

Operations

Search parameters

• Query — the search text. Supports Keyword Query Language (KQL), for example budget filetype:xlsx.
• Entity Types — content types to search. File types (site, drive, driveItem, list, listItem) must be searched together and can’t be combined with non-file types in one request.
• From / Size — paging, using a zero-based offset and page size.
• Fields — specific properties to return per hit.
• Query Template — advanced KQL template, for example {searchTerms} CreatedBy:Bob.
• Content Sources — for externalItem, the connector connection(s) to query, for example /external/connections/connectionId.
• Enable Top Results — for message, return the most relevant results first.

MCP tools for Copilot Studio

Invoke MCP is the Model Context Protocol endpoint. Point a Copilot Studio agent at it and the agent gets six tools:

• search — general search across entity types
• search_files — OneDrive and SharePoint files
• search_email — mail
• search_teams_messages — Teams chat and channel messages
• search_events — calendar events
• search_external_items — Copilot connector content

The dedicated tools save the agent from choosing entity types by hand—ask for files and the agent calls search_files directly.

Example

Search files:

{
  "queryString": "quarterly budget filetype:xlsx",
  "entityTypes": [ "driveItem" ],
  "size": 10
}

Response (abridged):

{
  "value": [
    {
      "searchTerms": [ "quarterly", "budget" ],
      "hitsContainers": [
        {
          "total": 3,
          "moreResultsAvailable": false,
          "hits": [
            {
              "hitId": "01ABC...",
              "rank": 1,
              "summary": "...quarterly <c0>budget</c0> figures...",
              "resource": { "name": "Q3-Budget.xlsx", "webUrl": "https://..." }
            }
          ]
        }
      ]
    }
  ]
}

Data flow

sequenceDiagram
    participant Client as Copilot Studio / Power Automate
    participant Conn as Connector
    participant Graph as Microsoft Graph (v1.0)
    participant M365 as Microsoft 365 Content

    Client->>Conn: Search { queryString, entityTypes, from, size, fields }
    Conn->>Graph: POST /v1.0/search/query { requests: [ { entityTypes, query, from, size } ] }
    Graph->>M365: Query indexed content (permissions evaluated per item)
    M365-->>Graph: Authorized hits
    Graph-->>Conn: 200 { value: [ { hitsContainers: [ { hits[], total } ] } ] }
    Conn-->>Client: Ranked hits with summaries + resources

    Note over Client,M365: OAuth 2.0 delegated — results scoped to the signed-in user

Prerequisites

• A Microsoft Entra ID app registration. This connector uses the generic aad identity provider with your own client ID and secret.
• Delegated permissions — searches run in the context of the signed-in user.

Set up credentials

The connector uses OAuth 2.0 (authorization code) with Microsoft Entra ID. Register an app and grant the delegated Microsoft Graph permissions for the entity types you plan to search:

Answer types bookmark, acronym, and qna are also supported by the Search API but require Bookmark.Read.All, Acronym.Read.All, and QnA.Read.All respectively. Add those scopes if you need them.

Steps:

1. In the Microsoft Entra admin center, register a new application.
2. Add a Web redirect URI: https://global.consent.azure-apim.net/redirect.
3. Under API permissions, add the delegated permissions above and grant admin consent.
4. Under Certificates & secrets, create a client secret. Record the Application (client) ID and secret value.
5. Set the client ID in apiProperties.json (clientId) and provide the client secret on the connector’s Security tab after deployment.

Deploy with PAC CLI

A known PAC CLI issue blocks OAuth connectionParameters on create, so deploy in two steps and configure OAuth in the portal:

# 1. Create the connector with the definition, properties, and script
pac connector create `
  --api-definition-file "apiDefinition.swagger.json" `
  --api-properties-file "apiProperties.json" `
  --script-file "script.csx"

# 2. In the Power Platform portal, open the connector's Security tab and set:
#    - Client ID and Client secret from your app registration
#    - Confirm the redirect URL matches https://global.consent.azure-apim.net/redirect

Telemetry

script.csx includes an Application Insights hook (LogToAppInsights) that emits events for requests, Graph calls, MCP tool calls, and errors. It’s disabled by default—the instrumentation key is a placeholder, and telemetry is skipped until you set a real key. Replace the APP_INSIGHTS_KEY constant to turn it on. Telemetry failures are swallowed and never block an operation.

Limitations

• Delegated only — this connector runs user-context search. Application-permission search for driveItem/listItem also requires a region in the request and isn’t exposed here.
• File-type interleaving — file entity types must all be in the same request and can’t mix with non-file types.
• person can’t be combined with any other entity type in a single request—search people on their own.
• Paging — from/size must be consistent when combining entity types. Page size maxes at 25 for message and event, and up to 1000 for SharePoint and OneDrive types.

References

• Microsoft Search API overview
• searchEntity: query
• Scope search based on entity types

Full source is in the SharingIsCaring repository.

#PowerPlatform #CopilotStudio #MCP #CustomConnectors #MicrosoftSearch #GraphAPI

You can find the complete code in my SharingIsCaring repository.

What it does

The connector calls the Microsoft Graph beta Copilot Chat API (/beta/copilot/conversations). You send a prompt, Copilot grounds its answer on the signed-in user’s Microsoft 365 data—respecting that user’s access controls—and returns a reply with citations. Because it runs as the signed-in user, every question needs a Microsoft 365 Copilot license.

Operations

Four operations cover single questions, multi-turn conversations, and Copilot Studio.

Use Ask Copilot when you have one question. For a back-and-forth, call Create Conversation once, then call Send Chat Message with the returned conversationId for each follow-up.

Grounding options

Ask Copilot and Send Chat Message accept extra context to steer the answer:

• Time Zone — IANA time zone (for example, America/New_York) used to interpret time-relative prompts like “tomorrow morning.” Defaults to UTC.
• Additional Context — a list of free-text strings added as grounding.
• File URLs — OneDrive or SharePoint file URLs to use as context.
• Enable Web Search — set to false to restrict grounding to enterprise data only.

Example

Ask Copilot:

{
  "text": "What meetings do I have tomorrow morning?",
  "timeZone": "America/New_York"
}

Response:

{
  "conversationId": "0d110e7e-2b7e-4270-a899-fd2af6fde333",
  "reply": "You have 1 meeting tomorrow at 9 AM: Zava Engineering Standup...",
  "turnCount": 1,
  "conversation": { "id": "0d110e7e-...", "messages": [] }
}

For a multi-turn thread, call Create Conversation, then Send Chat Message repeatedly with the returned conversationId.

MCP tools for Copilot Studio

Invoke MCP is the Model Context Protocol endpoint. Point a Copilot Studio agent at it and the agent gets three tools:

• ask_copilot — send a prompt and get a grounded reply
• create_conversation — start a multi-turn conversation
• send_message — continue a conversation by ID

The agent extracts parameters from the user’s request, calls the right tool, and reads back Copilot’s answer. That gives you Copilot’s enterprise grounding inside a Copilot Studio agent alongside your other tools.

Data flow

sequenceDiagram
    participant Client as Copilot Studio / Power Automate
    participant Conn as Connector
    participant Graph as Microsoft Graph (beta)
    participant M365 as Microsoft 365 Data

    Note over Client,M365: Ask Copilot (one-shot)
    Client->>Conn: Ask Copilot { text, timeZone }
    Conn->>Graph: POST /beta/copilot/conversations {}
    Graph-->>Conn: 201 { id }
    Conn->>Graph: POST /beta/copilot/conversations/:id/chat
    Graph->>M365: Ground on Mail, Calendar, Chats, Files, People
    M365-->>Graph: Authorized content + citations
    Graph-->>Conn: 200 copilotConversation { messages[] }
    Conn-->>Client: { conversationId, reply, turnCount }

Prerequisites

• A Microsoft 365 Copilot license for every user who signs in to the connection.
• A Microsoft Entra ID app registration. This connector uses the generic aad identity provider with your own client ID and secret.
• Delegated permissions only — the Chat API doesn’t support application permissions.

Set up credentials

The connector uses OAuth 2.0 (authorization code) with Microsoft Entra ID. Register an app and grant these delegated Microsoft Graph permissions—all are required for the Chat API to succeed:

• Sites.Read.All
• Mail.Read
• People.Read.All
• OnlineMeetingTranscript.Read.All
• Chat.Read
• ChannelMessage.Read.All
• ExternalItem.Read.All

Steps:

1. In the Microsoft Entra admin center, register a new application.
2. Add a Web redirect URI: https://global.consent.azure-apim.net/redirect.
3. Under API permissions, add the seven delegated permissions above and grant admin consent.
4. Under Certificates & secrets, create a client secret. Record the Application (client) ID and secret value.
5. Set the client ID in apiProperties.json (clientId) and provide the client secret on the connector’s Security tab after deployment.

Deploy with PAC CLI

A known PAC CLI issue blocks OAuth connectionParameters on create, so deploy in two steps and configure OAuth in the portal:

# 1. Create the connector with the definition, properties, and script
pac connector create `
  --api-definition-file "apiDefinition.swagger.json" `
  --api-properties-file "apiProperties.json" `
  --script-file "script.csx"

# 2. In the Power Platform portal, open the connector's Security tab and set:
#    - Client ID and Client secret from your app registration
#    - Confirm the redirect URL matches https://global.consent.azure-apim.net/redirect

Telemetry

script.csx includes an Application Insights hook (LogToAppInsights) that emits events for requests, Graph calls, MCP tool calls, and errors. It’s disabled by default—the instrumentation key is a placeholder, and telemetry is skipped until you set a real key. Replace the APP_INSIGHTS_KEY constant to turn it on. Telemetry failures are swallowed and never block an operation.

Limitations

• Beta API — subject to change and not supported for production by Microsoft.
• Delegated only — no application (app-only) permission support.
• License required — each signing-in user needs a Microsoft 365 Copilot license.
• No streaming — the connector uses the synchronous chat endpoint, so chatOverStream isn’t exposed.

References

• Microsoft 365 Copilot Chat API overview
• Create copilotConversation
• copilotConversation: chat

Full source is in the SharingIsCaring repository.

#PowerPlatform #CopilotStudio #MCP #CustomConnectors #PowerAutomate #GraphAPI

This MCP connector wraps Azure AI Search multimodal embeddings in a dual-mode Power Platform connector. Copilot Studio agents get MCP tools that return ImageContent blocks. Power Automate flows get typed operations with full schemas. Both share the same FastAPI + FastMCP backend running on Azure Container Apps.

Inspired by Pamela Fox’s Beyond text: Returning images and interactive apps from MCP servers and the Azure-Samples/image-search-aisearch reference implementation.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Power Platform / Copilot Studio                                │
│  ┌──────────────────┐  ┌──────────────────────────────────────┐ │
│  │  Power Automate  │  │  Copilot Studio (MCP)                │ │
│  │  Typed ops:      │  │  Tools: image_search,                │ │
│  │  SearchImages    │  │         search_by_image,             │ │
│  │  SearchByImage   │  │         get_image_details,           │ │
│  │  GetImageDetails │  │         display_images               │ │
│  │  GetImageUrl     │  │                                      │ │
│  │  UploadImage     │  │                                      │ │
│  └────────┬─────────┘  └──────────────────┬───────────────────┘ │
└───────────┼───────────────────────────────┼─────────────────────┘
            │        Custom Connector       │
            └───────────────────┬───────────┘
                                │ HTTPS + X-API-Key
            ┌───────────────────▼────────────────────┐
            │  Azure Container Apps (FastAPI + MCP)  │
            │  • /health — liveness probe            │
            │  • /mcp — MCP endpoint                 │
            │  • /api/search — text search           │
            │  • /api/search-by-image — reverse      │
            │  • /api/images/{f} — details           │
            │  • /api/images/{f}/url — SAS           │
            │  • /api/upload — add images            │
            └──────────────┬──────────┬──────────────┘
                           │          │
          ┌────────────────▼──┐  ┌────▼──────────────────┐
          │  Azure AI Search  │  │  Azure Blob Storage   │
          │  (multimodal      │  │  (image files)        │
          │   embeddings)     │  │                       │
          └───────────────────┘  └───────────────────────┘

MCP tools

When connected via Copilot Studio, the server exposes four tools:

The agent workflow follows a two-stage pattern:

1. Search — image_search returns thumbnails (resized to 512×512 for token-efficient model inspection) plus structured metadata
2. Curate — The agent reviews results, selects the best matches
3. Display — display_images renders selections in an interactive carousel via an MCP App resource

Typed operations (Power Automate)

SearchImages accepts a natural language query and returns results with base64 thumbnails and AI-generated descriptions. GetImageUrl returns a time-limited SAS URL for full-resolution download.

How the search works

The server uses hybrid retrieval — combining full-text search with vector similarity via VectorizableTextQuery:

results = search_client.search(
    search_text=query,
    top=max_results,
    vector_queries=[
        VectorizableTextQuery(
            k_nearest_neighbors=max_results,
            fields="embedding",
            text=query,
        )
    ],
    select=["metadata_storage_path", "metadata_storage_name", "verbalized_image"],
)

The index uses an integrated vectorizer (aiServicesVision) so queries are auto-vectorized at search time — no client-side embedding calls needed. If the vector search fails (wrong index schema, missing vectorizer), it falls back gracefully to text-only search.

For reverse image search, VectorizableImageUrlQuery vectorizes an image URL and finds nearest neighbors in embedding space:

results = search_client.search(
    search_text="",
    top=max_results,
    vector_queries=[
        VectorizableImageUrlQuery(
            url=image_url,
            k_nearest_neighbors=max_results,
            fields="embedding",
        )
    ],
)

Lightweight mode

Not every deployment needs Blob Storage access. Set LIGHTWEIGHT_MODE=true to return URLs and metadata only — no image bytes fetched, no thumbnails generated. Useful when the consumer (a flow or agent) only needs the image URL for downstream processing.

Index requirements

The AI Search index needs:

• An embedding field (Collection(Edm.Single), 1024 dimensions, HNSW profile)
• A verbalized_image field (AI-generated text description per image)
• A metadata_storage_name field (blob filename)
• A metadata_storage_path field (full blob URL)
• An integrated vectorizer using aiServicesVision

The Azure-Samples/image-search-aisearch repo includes a complete indexing pipeline you can adapt.

Deployment

Build in ACR

az acr build --registry yourregistry --image ai-image-search:latest --file server/Dockerfile server/

No local Docker required — ACR builds remotely.

Deploy infrastructure

The infra/ folder contains Bicep templates. Deploy with:

$acrPwd = az acr credential show --name yourregistry --query "passwords[0].value" -o tsv
az deployment group create --resource-group rg-ai-image-search `
    --template-file infra/main.bicep `
    --parameters containerImage="yourregistry.azurecr.io/ai-image-search:latest" `
                 apiKey="your-api-key" `
                 acrServer="yourregistry.azurecr.io" `
                 acrUsername="yourregistry" `
                 acrPassword=$acrPwd