Copilot Studio MCP

Snapshot every environment in an ordered chain (e.g. DEV, TEST, ACC, PROD) and compare each adjacent pair. Returns one report per pair plus the first stage where drift appears. Snapshots go to <dir>/<label>, reports to <dir>/reports.

Diff a failed run against a successful one to separate a data problem from a logic problem. Names the action where the two runs part company, lists every action whose status differs, and flags actions present in one run but not the other, which means the definition changed between them. With compareTriggerData it also reports which top-level keys of the trigger payload differ (key names only, never the values). The baseline defaults to the most recent successful run. Read-only. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.

Offline diff of two snapshot folders: solution version, per-agent YAML differences (noise such as ids, audit info and connection ids removed), flows, connection references, environment variables, unpublished changes. Writes <reportDir>/<a>-vs-<b>.md and .json. failOnDrift returns an error result when drift is found (for pipeline gates).

pac copilot init: create a new agent workspace on disk. Without 'environment' it is a local scaffold (no sign-in). With 'environment' it also creates the live agent and connects the workspace (needs pac auth profile and confirm: true). With 'solutionName' the agent is created inside that solution (existing unmanaged solution, or a new one with createSolution: true) via init, pack, import and clone; without it, pac puts the agent in a solution named after the agent. authoringMode 'classic' is the standard harness (topics, evaluations); 'cli-copilot' is the GitHub Copilot harness.

pac solution create-settings: the JSON that maps every connection reference (to a connection id in the target environment) and environment variable (to a target value). Pass connectionReferences / environmentVariables to fill values; the result lists what is still unmapped.

Create a new Power Automate cloud flow, from a step spec (see cs_build_flow_definition: trigger plus connector, HTTP, condition, loop, variable and response steps) or from a ready-made definition, optionally straight into a solution. The flow is created switched off, because a flow can only be activated once its connection references are bound: bind them, then cs_set_flow_state on. To let an agent call it, use a trigger of type Request/kind Skills and add it as a tool with cs_add_tool type 'flow'. Changes a live environment: requires confirm: true.

Create a new unmanaged solution (and its publisher if missing) in an environment by packing an empty solution manifest and importing it with pac. Use it to prepare the container before cs_create_agent with solutionName. Requires confirm: true.

Write the CSV the portal's Evaluation page imports (columns Question, Expected response; max 100 cases). Test sets cannot be created through the API, so this file is imported once in the portal; runs and results are then automated via cs_run_evaluation. suggestFromWorkspace derives cases from topics, starters and knowledge.

pac copilot delete: permanently delete an agent from the environment. Requires confirm: true.

Remove a cloud flow from the environment for good. Read it with cs_get_flow first: any agent tool that calls this flow will be left pointing at nothing, and a flow that is still switched on has to be turned off with cs_set_flow_state before Dataverse will delete it. A managed flow cannot be deleted this way; uninstall the solution it came in. Changes a live environment and cannot be undone: requires confirm: true.

pac solution delete: delete an unmanaged solution container (its components stay in the environment) or uninstall a managed one (its components are removed). Requires confirm: true.

pac solution import into the target environment using the deployment settings file, then publish every Copilot Studio agent from the solution. Source: a zip, or a solutionDir from cs_pull_solution (managed zip preferred when present unless unmanaged: true), or an unpacked srcFolder (packed first). Blocks when connection references or environment variables are unmapped unless allowUnmapped. Requires confirm: true.

Fetch (or read from cache) a connector's OpenAPI definition and list its operations with operationId, parameters (required, type, description) and response fields; marks MCP-capable connectors (x-ms-agentic-protocol). Exactly what cs_add_tool needs. Cached under .cs-catalog/<environment>/connectors/<name>.json and used by cs_validate.

Export a solution (unmanaged, async) and unpack it locally, then inventory everything inside: agents (with harness and component counts), bot components by kind, cloud flows, connection references, environment variables, custom connectors, other component folders. Read-only for the environment.

Inventory of an agent workspace: settings, instructions, topics (with trigger phrases), knowledge sources, tools, flows, triggers, variables, connection references, sync metadata.

Answer 'give me the Teams app package for this agent': download the channel manifest zip (manifest.json plus icons) for an agent published to the Microsoft 365 and Teams channel, the same file the portal offers as 'Download .zip', for sideloading or the Teams admin centre. Writes only the zip file; nothing in the environment changes. The agent must already be published to that channel. Follows the published Power Platform API reference; not yet verified against a live tenant.

Answer 'what exactly did that evaluation run test?': download the agent content snapshot the run was scored against, as the service zipped it, so it can be compared with the workspace now (unzip, then cs_compare_snapshots or a file diff). Writes only the zip file; the environment is not touched. Follows the published Power Platform API reference; not yet verified against a live tenant.

Change a knowledge source file: name, description, site URL, includeSubPages, trigger condition (null removes it), additional search terms.

Change an existing tool file: name, description, modelDescription / modelDisplayName (what the orchestrator routes on), operationId, connection mode or reference, output mode, and inputs (set / add / remove). Validates afterwards.

Change an existing topic in place, keeping its comment header: rename, description, trigger phrases (set / add / remove), priority, append or insert nodes (same node spec as cs_add_topic), remove top-level nodes by id. Validates the file afterwards.

Why one run of a cloud flow failed, in terms of the action that broke and what it was given. For each failed action it resolves the real error message - a failed connector action carries no error of its own, so the message is fetched from the action's outputs - classifies the failure as a connector, expression or timeout problem, and returns the inputs it was called with plus the outputs of the actions that ran just before it. Read-only. Start here when cs_list_flow_runs shows a failure. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.

Write the agent's instructions for it - the system prompt that decides how it answers. Builds a brief from purpose, audience, tone, capabilities, boundaries and examples, send it to an AI Builder prompt or model (pac copilot model predict; pick one with cs_list_prompts), and return the generated instructions. With apply: true the text is written into the agent's instructions (agent.mcs.yml, or settings.mcs.yml for cli-copilot), and only with confirm: true as well - without it the generated text comes back with the change it would make and the character count, and nothing is written. Pass curre…

Answer 'do users have to approve this agent's connectors?': read whether an admin has switched connector consent bypass on for the agent, so its connector tools run without each end user consenting to the connection first. Read-only. cs_set_connector_consent_bypass is the separate step that changes it. Follows the published Power Platform API reference; not yet verified against a live tenant.

Status and per-case results of an evaluation run, with a pass/fail summary per test method.

Answer 'what does this flow actually do?': one flow's trigger and action names, its connection references, and the whole Power Automate definition when 'includeDefinition' is set. Read-only. Use it before cs_update_flow, and to see why a flow cannot be switched on. For what happened on a particular run, use cs_list_flow_runs and cs_explain_flow_run instead.

One run of a cloud flow with its status, timing, trigger and error. Read-only. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.

Full catalogue entry for one agent: metadata, element types, availability and deployment state, and whether it is blocked. The raw body is returned alongside the mapped fields, because the detail resource carries more than the list rows. Read-only (cs_login scope 'graph'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.

The full turn list of one session: who said what, in order, with the topic and tool attributed to each turn where the transcript records them. Read-only.

Description is built at runtime.

pac solution import of a packed agent (from cs_pack) into an environment. Mutates the environment: requires confirm: true.

Check whether this machine is ready to work: the pac CLI and .NET, which pac auth profile is active, which cloud resources have a usable token, the environment variables, the write policy in force, and the agent workspace it found, ending with the next steps for that workspace. Read-only. Call it once at the start of a session, and again when a tool fails and you need to know whether the CLI, the credentials or the workspace is the reason. It reports the state of the machine and nothing else: when the user asked for something specific - an agent, a flow, a solution, an environment, instruction…

The state of a job started with background: true - running, succeeded or failed - with the phases it has reached and, once finished, the result the tool would have returned. Read-only. Jobs live in the server process, so a restart loses them; pass recordFile to read the copy the job wrote to disk instead.

List Copilot Studio agents in an environment. via 'pac' uses 'pac copilot list' (needs a pac auth profile); via 'dataverse' queries the bots table with the MSAL token. Default auto: pac when available, else dataverse.

The pac authentication profiles on this machine, which one is active, and which account each belongs to. Use it to find the name of the admin profile to pass as 'profile' to the admin tools. Read-only.

pac connection list: connections that exist in an environment (id, connector, owner). Use the ids to map connection references in a deployment settings file before cs_deploy_solution.

The environment's connector registry (the same list the portal's Add a tool shows): Microsoft-published and custom connectors, with an mcpLikely flag for MCP servers. Cached under .cs-catalog/<environment>/connectors.json for offline use; with search and no sign-in, falls back to the offline seed of public connectors.

List Power Platform environments the signed-in user can access (BAP API), with Dataverse URLs.

Previous evaluation runs for the agent.

Answer 'when did this flow last run, and did it work?': the run history of one cloud flow, most recent first, with status, start and end time, duration and the error of a failed run. Read-only. Use it to find the run you care about, then cs_explain_flow_run on that run to learn why it failed. Uses the Power Automate service, which is a separate sign-in from Dataverse (cs_login scope 'flow'). Unverified against a live tenant.

Answer 'which flows are there?': every cloud flow in the environment with its state, owner and last change, so you can see what the agent's flow tools can call and what a solution import left switched off. Read-only. This is the inventory only. For one flow's contents use cs_get_flow; for its execution history use cs_list_flow_runs; for the cause of a failure use cs_explain_flow_run.

Every agent in the organisation's Microsoft 365 catalogue, across environments, with the things Power Platform cannot see: who the agent is available to, where it is deployed, and whether an admin has blocked it. Defaults to agents built in Copilot Studio; pass platform: 'all' to include the Agent Builder and acquired apps. Read-only. Uses Microsoft Graph, a separate sign-in from Dataverse (cs_login scope 'graph'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.

pac copilot model list: AI Builder models (including custom prompts) in the environment, with ids for cs_add_tool type 'prompt'.

pac solution list: solutions in an environment with version and managed flag. Needs a pac auth profile.

Power Platform API: test sets defined for the agent (standard harness).

Sessions people had with the published agent, newest first: when, how many turns, the first thing the user asked, which topics and tools fired, and how the session ended. Read-only. Needs a cached cs_login. Use it to find the session behind a bad answer, then cs_get_transcript for the full turn list.

Acquire a Microsoft Entra token for the cloud tools (evaluations, environments, agents, publish, chat, drift). mode 'interactive' (default) starts a browser sign-in and returns within waitSeconds: status 'ok' when it completed, otherwise status 'pending' with the sign-in URL. If no browser opened, show the user that URL to open on the machine running this server; the page redirects to localhost and the login completes in the background (check cs_login_status or call any cloud tool). mode 'device_code' returns a code to enter at microsoft.com/devicelogin (some tenants block this flow). Not need…

Answer 'am I signed in?' for the cloud tools: the cached MSAL accounts, and whether a browser or device-code sign-in is still pending, with its URL or code; optionally wait for it to complete. For the separate pac sign-in, cs_auth_who.

Remove cached MSAL accounts for the tenant.

Inspect the Copilot Studio authoring schema: summarize or resolve a definition (e.g. Question, SearchAndSummarizeContent, KnowledgeSourceConfiguration), search by keyword, or list all kinds.

Escape hatch: run 'pac <args...>' directly. Read-only commands (list/who/status/help) run immediately; anything else needs confirm: true. 'profile' runs it as another pac auth profile, for example the tenant admin account.

pac copilot pack: local-only packaging of the workspace into a Dataverse solution .zip (no sign-in). Also a cheap structural check of the workspace. outputPath must be outside the workspace.

pac solution pack: zip an unpacked source folder (after local edits) so it can be deployed.

Make the agent's current draft visible to real users on its channels - the tool for 'go live', 'release it' and 'make my changes live'. It publishes what is already in Copilot Studio, so send local edits up with cs_push first. via 'pac' runs 'pac copilot publish'; via 'dataverse' calls the PvaPublish action with the MSAL token and polls until publishedon changes. Requires confirm: true.

pac copilot pull: three-way merge of server changes into the local workspace (also downloads knowledge files). Run before editing and before pushing. Records a sync stamp (.mcs/cs-sync.json) so cs_check_drift can tell later portal changes from yours; commit the workspace afterwards to keep a reviewable history.

Export the solution (unmanaged and optionally managed), unpack it to <targetDir>/src, write <targetDir>/solution.json, generate deployment-settings.json (connection references + environment variables to map), and clone every agent in the solution into <targetDir>/agents/<name> as a sync-connected workspace. This is the input for cs_deploy_solution.

Send local file changes up into the agent's draft in Copilot Studio - topics, knowledge files, flows, connection references - so the draft matches your workspace (pac copilot push). This is the tool for 'upload', 'send my changes up' and 'sync my edits'. It only moves files into the draft; cs_publish is the separate step afterwards. Validates YAML first and blocks on errors unless force. The dry run also reports components changed in Copilot Studio since the last sync (quick drift check, needs a cached cs_login); when one of those also changed locally the push is blocked unless force. Changes …

Hand ownership of an agent in the Microsoft 365 agent catalogue to another user, by their Entra object id. Used when the owner leaves the organisation. The agent's owner inside a Power Platform environment is cs_reassign_agent_owner. Changes a live tenant: requires confirm: true. Needs CopilotPackages.ReadWrite.All and runs against Graph beta (cs_login scope 'graph_write'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.

Delete a topic, knowledge source, tool, trigger, variable or flow from the workspace files (the live agent changes on the next cs_push). For tools, the connection reference is dropped too unless another tool uses it. Reports topics that still redirect to a removed topic. Deletes files: requires confirm: true.

Judge whether the agent is any good and say what to improve, as a score out of 10 with a fix for each finding: instructions present and sized, escalation and fallback topics, trigger phrase count and overlap, tool descriptions and name collisions, unbound connections, authentication versus private knowledge, web browsing with internal sources, orchestration off with tools, duplicate names, credentials in YAML, pack-only workspace. Returns a score, findings with fixes, and optional Markdown.

Run a YAML test file (tests: name, utterance, expect, continueConversation) against the published agent through cs_chat and report pass/fail. expect asserts on wording (contains, containsAny, notContains, regex, minLength, noSignIn) and on what the agent did (usedTool, notUsedTool, usedTopic, notUsedTopic, citedKnowledge), so a test can tell a real tool call from an answer that merely sounds right. Every result reports the observed topic, tool and citations whether or not it asserted on them. The CLI-native complement to portal evaluations. Pass writeExample to create a starter file.

Start an evaluation run for a test set (draft agent by default, or the published one). Optionally wait for completion and return the summary. mcsConnectionId runs it signed in as a user profile (the id of that user's Copilot Studio connection) so authenticated knowledge and tools answer; toolsConnections picks the connection each connector tool uses. Counts against the 20 runs per agent per 24h limit: requires confirm: true.

Start a run of a manually triggered cloud flow, with an optional payload. Only flows whose trigger is manual or agent-callable can be started this way; scheduled and event-driven flows run on their own. Whatever the flow does (sending mail, writing records) happens for real, so this changes a live environment: requires confirm: true. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.

Switch connector consent bypass on or off for one agent. On, end users stop being asked to approve the agent's connectors and the tools run straight away; off restores the consent prompt. An admin setting through the Power Platform API, so the signed-in user needs a Power Platform or Copilot Studio admin role. Changes a live environment: requires confirm: true. Follows the published Power Platform API reference; not yet verified against a live tenant.

Switch a flow on (Activated) or off (Draft). This is the step a solution import leaves for you: flows whose connection references were unbound at import time land switched off. A flow can only be turned on once its connections are bound and its definition is valid. Changes a live environment: requires confirm: true.

Answer 'there are too many tools': narrow, or restore, the tool list for the rest of this session. The full list is 146 tools and about 50k tokens of schema, which crowds a smaller model's context and makes it choose worse. Presets: core (the loop that builds an agent and gets it live), authoring (local files only), admin (tenant administration), solutions (moving solutions between environments), full (everything). Read-only: it changes nothing in any environment and no tool is lost, only hidden. Ask the user before calling it.

Capture one environment into a folder for comparison or history: solution version, every agent cloned with pac copilot clone (agents/<name>), and, when signed in, flows, connection references, environment variables and publish state. Read-only for the environment.

pac copilot status for an agent id.

Aggregate over recent sessions: how they ended, the escalation rate, average turns, how many never matched a topic, the topics and tools that actually fire, and the questions behind the sessions that went badly. Read-only. This is the input for deciding what to fix next, and for cs_create_test_set_csv fromTranscripts.

Write the portal's import CSV from questions people actually asked, most frequent first, instead of guessing from the workspace. onlyFailed (default true) keeps the sessions that escalated, went unanswered or were abandoned, which are the ones worth turning into regression cases. Read-only apart from writing the file; import it once in the portal, then cs_run_evaluation automates the runs.

Edit agent.mcs.yml (standard harness): instructions, display name, conversation starters, model hint, and the settings the portal groups under responses and generative AI: response instructions (wording and formatting), response mode, conversation history, capability toggles (web browsing, code interpreter, image generation, Teams / SharePoint / email / meeting / people search), whether the model may use its own general knowledge, content moderation level, file analysis and semantic search. The first call writes nothing: it returns the change - the current lines against the proposed ones, and …

Change a flow's name, description or definition in the environment. Pass 'steps' (and optionally 'trigger') to rebuild the definition the way cs_build_flow_definition does, or 'definition' for a ready-made one; either replaces properties.definition inside the existing clientdata and keeps the connection references. 'clientData' replaces the whole document. Read the current one with cs_get_flow includeDefinition first. Managed flows cannot be edited in place; edit them in their source environment or through a solution. Changes a live environment: requires confirm: true.

Set values in settings.mcs.yml by dot path, e.g. {"configuration.settings.GenerativeActionsEnabled": true}. Do not change authoringModel/recognizer/template.

Structural validation of every component file against the Copilot Studio authoring schema (kinds, unknown/missing properties, duplicate ids, placeholders, Power Fx prefixes, variable scopes) plus cross-file checks (connection references, topic redirects). Answers 'is anything broken in these files?'; it only reads them and sends nothing anywhere. cs_push runs it itself and blocks on errors.