Copilot Studio MCP

An MCP server that lets a coding agent (GitHub Copilot in VS Code, Claude Code, or any other MCP client) build, test, ship and look after Microsoft Copilot Studio agents from the editor.

An agent becomes a folder of YAML you can read, diff and commit. The server writes that folder the way the Copilot Studio VS Code extension does, syncs it with the live agent through the official Power Platform CLI (pac), and calls the Power Platform, Dataverse, BAP, Power Automate and DirectLine APIs for what the CLI does not cover: evaluations, chat, cloud flows, portal drift, transcripts. Nothing reaches a live environment without your approval, and when a choice is still open the tool asks a question instead of failing.

What you can do with it

You want to	What happens	Read
Stand up a new agent and get it live	create it inside a solution, generate instructions, add knowledge, topics and tools, review, validate, push, publish, talk to it	Build a new agent
Change an agent that already exists	clone it to files, edit or remove components, review, merge what colleagues changed, push	Work on an existing agent
Give the agent something to call	connector actions, MCP servers, cloud flows, AI Builder prompts, other agents, chosen from what the environment actually has	Give the agent tools
Know whether it works	chat with the published agent, repeatable conversation tests, evaluation runs with per-case results	Publish and test
Learn from real users	transcripts, session outcomes, escalation rate, a regression test set built from real questions	Learn from production conversations
Not overwrite what a colleague did in the portal	see portal changes since your last sync, block a push that would collide, merge	Keep the workspace and the portal in sync
Write a Power Automate flow without hand-writing Logic Apps JSON	compose a definition from steps, create the flow, bind its connections, switch it on, read its run history	Build cloud flows
Find out why a flow keeps failing	resolve the real error behind a failed connector action, diff the run against one that worked, and see where the failures concentrate	Build cloud flows
Move to test and production	pull the whole solution, map connections and variables, deploy 1:1, publish; or use a pipeline	Ship a solution to another environment
Prove the stages match	snapshot each environment, compare, gate a pipeline on drift	Compare environments across DTAP
Run the tenant	environments, security roles, DLP, tenant settings, backups to files, onboarding a team, the Microsoft 365 agent catalogue	Administer the tenant

The complete tool list is in docs/tools.md and the diagrams in docs/flows.md; both ship inside the npm package under docs/. The reference sections at the end of this page cover the agent settings the server can write, authentication and permissions, configuration, the hard limits and how this differs from pac's own MCP server.

Status

Early release. What has actually been exercised:

• Offline: 251 unit tests over the compiled output, plus a pack oracle that round-trips every authoring tool's YAML through pac copilot init and pac copilot pack.
• Against a real tenant (2026-09-08, phases A to F of docs/live-verification.md): the connector registry, the pac connection list layout, pac copilot clone and its sync metadata, drift detection and the cs_push conflict refusal, and the evaluation path end to end including the portal's CSV import format and the metric status strings. A portal-made agent validates clean, so cs_validate produces no false positives on real content. That run also caught a real bug: pac copilot publish prints "Failed to publish" and exits 0, so a failed publish was being reported as a success. Fixed.
• Not yet verified live: the transcript tools, cs_check_drift in quick mode, cs_chat, the Dataverse listBots path, moving a solution between environments, and every flow the flow builder produces (none has been imported into an environment yet).

docs/verify.md is the short list of what is still open, docs/STATUS.md the full record. Read the dry run before confirming anything that writes.

Set up

Prerequisites

• Node.js 20+.
• .NET 10 SDK and the Power Platform CLI: dotnet tool install --global Microsoft.PowerApps.CLI.Tool. If the SDK lives in your user profile, set DOTNET_ROOT to that folder; the server defaults it to ~/.dotnet when that folder exists.
• A pac auth profile for the environment you work in, created once in a terminal: pac auth create --environment <id or URL>. Everything that goes through pac (create, clone, pull, push, publish, solutions, administration) uses it, with Microsoft's own first-party app.
• For the API-based tools (environments, evaluations, chat, flows, drift, transcripts): an Entra sign-in through cs_login, done from the session. By default no app registration is needed; Authentication and app registration says when you need one and which permissions it must carry.

Install and register

The server is on npm as copilot-studio-mcp, so the usual install is no install: point your MCP client at npx, and the first start fetches the package.

There is also a VS Code extension, vscode-extension/, which registers the server with VS Code's MCP host and exposes the environment variables below as settings. It carries the server and its dependencies inside the VSIX, so it needs no npm and no network on first start. Build it with cd vscode-extension && npm install && npm run package; install the resulting .vsix with code --install-extension copilot-studio-mcp-<version>.vsix.

VS Code, from a terminal or by hand in .vscode/mcp.json (workspace) or the user-level mcp.json:

code --add-mcp '{"name":"copilot-studio","command":"npx","args":["-y","copilot-studio-mcp"]}'

{
  "servers": {
    "copilot-studio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "copilot-studio-mcp"],
      "env": { "CPS_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Claude Code (user scope):

claude mcp add-json copilot-studio '{"type":"stdio","command":"npx","args":["-y","copilot-studio-mcp"]}' --scope user

npm install -g copilot-studio-mcp with "command": "copilot-studio-mcp" avoids the npx start-up cost. The server is published to the MCP Registry as io.github.jgt87/copilot-studio-mcp, which is what VS Code's MCP gallery (Extensions view, search @mcp) draws from through the GitHub MCP Registry. To run from a clone instead, see Development.

Environment variables are optional and listed under Configuration.

The first session

1. cs_init. Reports pac and .NET, the pac profiles and which one is active, the MSAL sign-in, the write policy in force, the workspace it found and the next steps for it. It also returns a menu of tool presets; on a smaller model pick one (see Running on a smaller model).
2. cs_login when a cloud tool needs it. The call opens the browser from the server and returns within 15 seconds; if the sign-in has not finished by then it returns status: pending with the URL so you can open it yourself, and the next cloud call (or cs_login_status) picks the token up. That is what makes sign-in work from clients that cap tool-call duration or run the server where no browser can be launched. Device code (mode: device_code) is the alternative where the tenant allows it; many block it by Conditional Access policy.
3. cs_guide <topic> when you want the walkthrough for one job rather than inventing a sequence: getting-started, instructions, knowledge, tools, topics, evaluations, publish-and-test, drift, transcripts, solutions, administration, troubleshooting. Each names the tool per step, the portal steps that cannot be automated, and the next steps for your workspace. Six MCP prompts (new agent, add knowledge, add tool, write instructions, review and push, check drift) wrap the same walkthroughs in clients that show prompts as commands.

Approval before anything changes

The server never changes a live Copilot Studio environment on its own. Every tool that can (cs_push, cs_publish, cs_run_evaluation, cs_import_solution, cs_deploy_solution, cs_create_agent with an environment, the delete tools, the flow and admin tools that write, and the environment-changing pac wrappers) returns a dry run describing what it would do, and does nothing else, until it is called again with confirm: true. The calling agent is instructed, in the MCP handshake, to show that dry run and pass confirm only after you agree; one approval covers one call.

Changing the agent on disk asks the same way, for the same reason: an edit you did not intend is cheap to make and expensive to notice. cs_add_topic, cs_add_knowledge_source, cs_add_tool, cs_add_flow, cs_add_trigger, cs_add_variable, cs_edit_topic, cs_edit_tool, cs_edit_knowledge, cs_update_settings, cs_update_agent and cs_generate_instructions write nothing on the first call. They return the change instead - a file that would be created shown in full, a file that would be edited shown as a diff against what is there now - and write it when the same call is repeated with confirm: true. Reviewing, validating and describing read only, and ask nothing.

The prose fields get their own accounting, because they are the change a diff alone does not settle: the preview carries the character count and how much of the product's limit is left, and an edit that would exceed it is refused outright rather than failing at push time. The limits are not the same - instructions holds 8000 characters, and the Settings > Responses > "Response formatting" box (responseInstructions) only 500.

For a hard lock, set CPS_READ_ONLY=1 in the server's environment: the environment-changing tools are then not registered at all, so no confirmation can reach the environment, while authoring, validation, review and the read-only tools keep working. cs_init reports the mode and which tools are withheld. test/policy.test.js fails if a tool that declares confirm is missing from that list, so the two layers cannot drift apart.

Three more behaviours you will meet in every workflow:

• A question instead of an error. When a call cannot proceed because something has not been decided (which connector, which operation, which agent), the tool returns needsInput: true with what it needs, why, the real choices when the server can list them, and the tool that lists more. Nothing is written; the calling agent asks you and calls again. This works in every client, including those without MCP elicitation.
• Long calls run in the background. MCP clients cap a tool call at about a minute. Tools that can run longer (cs_pull_solution, cs_create_auth_profile, environment provisioning, every pac wrapper) accept background: true, return a jobId at once, and cs_job_status reports the phases and the result from an on-disk record that survives a server restart. A tool decides whether it may change anything before it starts a job, so the confirm contract is unaffected.
• Writes are never retried. A read that fails on a transport error or a 429/5xx is retried with backoff and honours Retry-After; a publish or an import that timed out may already have been applied, so it is reported, not repeated.

Two accounts: maker and admin

Making agents and administering the tenant are usually different accounts. pac keeps one active authentication profile per machine, so create one profile per account and let the server switch:

pac auth create --name maker --environment <environment id or url>
pac auth create --name admin --environment <environment id or url>

Or from the session: cs_create_auth_profile with name, environment and background: true, because pac opens its own browser and waits for the sign-in (cs_job_status reports when the profile exists). cs_list_auth_profiles shows the profiles and which is active.

Core sync and solution tools use CPS_PAC_PROFILE; admin commands and tenant backup use CPS_ADMIN_PROFILE; every pac wrapper and cs_pac also accept an explicit profile. When the server selects a profile it restores the previous one afterwards, and every pac call in the process shares one queue, so multi-step operations (bootstrap, solution pull and deploy, snapshots) hold the profile for the whole run. Other server instances and terminal pac commands are outside that coordination. The MSAL sign-in used by the API-based tools is separate again and independent of pac.

Build a new agent

From an empty folder to a published agent you can talk to. Each step is one tool call; the steps that change the environment show a dry run first.

1. Pick the environment. cs_list_environments (needs cs_login), or take the environment id from the Copilot Studio URL.

2. Pick or create the solution. cs_list_solutions shows what exists; an existing solution works as long as it is unmanaged and you use its publisher prefix. To start a solution for your agents: cs_create_solution uniqueName=contoso_Agents publisherPrefix=contoso confirm=true. The solution is the unit you later export and import to move the agent to test and production, so it is worth choosing rather than letting one be created per agent.

3. Create the agent inside it. cs_create_agent name="Contoso Support" publisherPrefix=contoso projectDir=./contoso-support environment=<id> solutionName=contoso_Agents confirm=true (add createSolution=true to fold step 2 in). The server scaffolds locally with pac copilot init, packs with the solution name, imports, then clones the live agent back so projectDir is a sync-connected workspace with the default system topics. Without environment you get a local scaffold only, which can pack settings, agent and topics but not knowledge, tools or flows.

   Leave out publisherPrefix or projectDir and the tool asks instead of guessing, listing the publishers in the environment (and, when you named a solution, the one prefix that solution's publisher allows) and suggesting a folder named after the agent. The prefix is worth the question: it becomes part of the schema name of every component the agent will ever have (contoso_contososupport.topic.Greeting), it cannot be changed afterwards without recreating them, and it has to match the publisher of the solution the agent lands in.

4. Say what the agent is for. cs_generate_instructions purpose="Answer IT questions and create ServiceNow tickets" audience="Employees" tone="Friendly, brief" boundaries=["never reset passwords"] modelName="Agent instructions" drafts the instructions with an AI Builder prompt (cs_list_prompts shows the prompts in the environment; create a "write agent instructions" prompt once in AI Builder if you have none). Review the draft, call again with apply=true to write it into agent.mcs.yml; later refine=true with a changeRequest revises what is there. Or write them yourself with cs_update_agent, which also sets response instructions and mode, conversation history, capabilities, moderation, model and conversation starters (the full map).

5. Give it something to work with. cs_add_knowledge_source for a public website, SharePoint, a Graph connector or uploaded files; cs_add_topic for deterministic conversations built from trigger phrases plus message, question, condition, set-variable, redirect, HTTP, flow, generative answers (optionally scoped to named knowledge sources), adaptive card, transfer and end nodes; cs_add_tool for anything the agent should call (the tools workflow). cs_add_trigger and cs_add_variable cover event triggers and global variables.

6. Review and validate. cs_review_agent is a rules-based read of the whole workspace with a 10-point score: missing escalation or fallback, weak tool descriptions, overlapping trigger phrases, private knowledge with no authentication, secrets in files. Each finding names the rule and the fix. cs_validate then checks every file against the authoring schema (744 definitions) and across files: connection references that nothing binds, catalog operations that do not exist, redirects to topics that are not there.

7. Push. cs_push confirm=true is the portal's Save: the draft agent now shows your topics, knowledge and tools. The dry run runs validation and the quick drift check first, and the push is refused when a colleague changed the same component in the portal since your last pull. Tools with a connection reference need one portal step: open the tool under the agent's Tools, Connect, then cs_pull to bring the binding down.

8. Publish and talk to it. cs_publish confirm=true, then cs_chat utterance="my laptop is slow". The testing workflow turns that into repeatable checks.

flowchart TD
    A["cs_init"] --> B["cs_list_solutions<br/>pick one, or cs_create_solution"]
    B --> C["cs_create_agent<br/>environment + solutionName + confirm"]
    C --> D["cs_generate_instructions<br/>AI Builder prompt, then apply"]
    D --> E["cs_add_topic / cs_add_knowledge_source / cs_add_tool<br/>(cs_list_connectors, cs_describe_connector)"]
    E --> R["cs_review_agent"]
    R --> H["cs_validate"]
    H -- errors --> E
    H -- clean --> I["cs_push confirm"]
    I --> J{"tool needs a connection?"}
    J -- yes --> J1["portal: authorise once"] --> J2["cs_pull"] --> K
    J -- no --> K["cs_publish confirm"]
    K --> L["cs_chat"]

GitHub Copilot harness agents (cs_create_agent with authoringMode: cli-copilot) are a smaller surface: init, pack, import, instructions and chat. Topics and evaluations are standard-harness features.

Work on an existing agent

Most agents already exist, often made in the portal. The loop is clone, change, review, merge, push.

1. Clone it. cs_list_agents (through pac or Dataverse), then cs_clone_agent bot=<id or schema name> outputDir=./support-agent. The result is a sync-connected workspace with agent.mcs.yml, settings.mcs.yml, topics/, knowledge/, actions/, trigger/, variables/, workflows/ and the connection references. cs_describe_workspace inventories it and ends with next steps.
2. Change it. Components are found by name, file stem or path. cs_edit_topic changes trigger phrases, priority and nodes (by position or id); cs_edit_tool changes descriptions, inputs and the connection; cs_edit_knowledge changes a site or a trigger condition; cs_remove_component deletes a topic, knowledge source, tool, trigger or variable and prunes the connection reference nothing else uses, noting any redirect left dangling. cs_update_agent and cs_update_settings cover the agent's own settings. Adding works as in the new-agent flow. Every edit keeps the file header the extension expects.
3. Review and merge. cs_review_agent, then cs_pull to bring down what colleagues changed in the portal (pac's three-way merge), then cs_validate.
4. Push. cs_push confirm=true. If a portal change and a local edit touch the same component the push is blocked; cs_pull resolves it, force: true overrides it.
5. Commit. Keep the workspace in git and commit after every pull (the tool result reminds you). Portal drift then shows up as a diff you can review: accepting it is a commit, rejecting it is a push of the local version.

Around that loop: cs_delete_agent and cs_delete_solution remove things from the environment (confirm); cs_extract_agent_template and cs_create_agent_from_template turn one agent into a template for more; cs_extract_translations and cs_merge_translations do the localisation round trip (.resx or .json, with whatIf); cs_quarantine_agent takes an agent out of service and back.

Give the agent tools

Copilot Studio agents can call any connector in the environment (more than a thousand Microsoft-published ones plus custom connectors), MCP servers exposed through connectors, cloud flows, AI Builder prompts, other agents, and a few rarer kinds. The server knows the kinds from the YAML schema and the instances from the environment, which is the only source that knows what exists there.

1. Find the connector. cs_list_connectors search=ServiceNow lists the environment's connector registry, the same list the portal's Add a tool shows, with MCP servers flagged. Without a sign-in it falls back to an offline seed generated from the public connector reference (display name to shared_ id, no operations): a starting point, not proof the connector is enabled for you.
2. Find the operation. cs_describe_connector connector=shared_service-now operation=incident turns the connector's OpenAPI definition into operations with operationId, required and optional parameters and response fields; x-ms-agentic-protocol: mcp-streamable-1.0 marks MCP endpoints. Definitions are cached under .cs-catalog/<environment>/ so later calls are offline.
3. Add the tool. cs_add_tool takes a typed spec for a connector action, an MCP server, a cloud flow, an AI Builder prompt (cs_list_prompts shows them), a connected agent or a child agent, and a raw type for the rest (AI plugin, Bot Framework skill, client action, computer-use agent). With the definition cached it checks the operationId, fills the automatic inputs from the operation's required parameters, and writes the YAML under actions/ plus a connection-reference stub. If you have not named a connector or operation yet the call comes back as a question with the ranked candidates.
4. Connect it, once, in the portal. A connection is an authorised link that only the portal can create (the one exception is a service-principal Dataverse connection, which cs_create_connection makes). After cs_push, open the tool under the agent's Tools, Connect, then cs_pull. cs_validate warns about tool files whose operation is not in the cached definition, and cs_review_agent flags tools whose description will not let the orchestrator pick them.