Copilot Studio MCP

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

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 . 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- .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

Mistral Vibe, in ~/.vibe/config.toml (or $VIBE_HOME/config.toml; a ./.vibe/config.toml in the working folder takes precedence). Vibe gives a server 10 seconds to start by default, which a first npx fetch on a corporate network can exceed, so install globally and run the entry point with node (find the folder with npm root -g). On Windows, keep paths in single quotes: TOML reads backslashes inside double quotes as escapes, and "C:\Users\..." is not valid TOML.

[[mcp_servers]]

name = "copilot-studio" transport = "stdio" command = "node" args = ['C:\Users\ \AppData\Roaming\npm\node_modules\copilot-studio-mcp\dist\index.js'] startup_timeout_sec = 60 # default 10 tool_timeout_sec = 300 # default 60; solution exports and evaluation runs take longer

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 ` 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